Skip to content

Commit

Permalink
Add note about portability concerns
Browse files Browse the repository at this point in the history
  • Loading branch information
jonjohnsonjr committed Mar 18, 2021
1 parent e2cc12a commit a2a4db3
Showing 1 changed file with 4 additions and 1 deletion.
5 changes: 4 additions & 1 deletion descriptor.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,13 +155,16 @@ Note that `[A-F]` MUST NOT be used here.

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

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

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

Implementations SHOULD consider limitations of storage systems when deciding whether or not to embed data.
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.

## Examples

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

0 comments on commit a2a4db3

Please sign in to comment.