Skip to content

Commit 58c082d

Browse files
committed
Add note about portability concerns
Signed-off-by: Jon Johnson <[email protected]>
1 parent ce281ce commit 58c082d

File tree

1 file changed

+4
-1
lines changed

1 file changed

+4
-1
lines changed

descriptor.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,13 +155,16 @@ Note that `[A-F]` MUST NOT be used here.
155155

156156
In many contexts, such as when downloading content over a network, resolving a descriptor to its content has a measurable fixed "roundtrip" latency cost.
157157
For large blobs, the fixed cost is usually inconsequental, as the majority of time will be spent actually fetching the content.
158-
For very small blobs, the fixed cost will be quite significant.
158+
For very small blobs, the fixed cost can be quite significant.
159159

160160
Implementations MAY choose to embed small pieces of content directly within a descriptor to avoid roundtrips.
161161

162162
Implementations SHOULD NOT populate the `data` field in situations where doing so would unexpectedly modify content identifiers.
163163
For example, a registry SHOULD NOT arbitrarily populate `data` fields within uploaded manifests, as that would modify the content address of those manifests.
164164

165+
Implementations SHOULD consider limitations of storage systems when deciding whether or not to embed data.
166+
Many implementations will refuse to accept or parse manifests that violate the limitations of their storage systems, so descriptors concerned with portability SHOULD avoid embedding large amounts of data.
167+
165168
## Examples
166169

167170
The following example describes a [_Manifest_](manifest.md#image-manifest) with a content identifier of "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270" and a size of 7682 bytes:

0 commit comments

Comments
 (0)