From e2a0d6e56f554c06e3165dfd3e1c20c5a35d5ff0 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 22 Sep 2016 21:35:16 -0700 Subject: [PATCH] considerations: DRY annotations and extensibility As I suggested in the PR landing these blocks [1,2,3]. I've shifted the extensibility section to a separate considerations.md, since it's a generic policy that applies to both our manifest and manifest-list. I've pushed the annotations meat into the lower-level manifest specification (linking there from the higher-level manifest-list specification). The extensibility requirements and annotations field might arguably apply to our other JSON types as well. The separate extensibility file sets the stage for that, but I've left the other types off this commit to focus on making the current requirements more DRY without changing the specified behavior. My personal preference would be to have separate canonicalization.md and extensibility.md files, but Jonathan wanted the single file: On Mon, Oct 10, 2016 at 09:22:46AM -0700, Jonathan Boulle wrote [4]: > Ehh, I preferred it where it was - now worried about death by a > thousand files (extensibility, canonicalization, etc etc). Can we > combine them (into a generic "considerations" document or similar), > or just put this back? [1]: https://github.com/opencontainers/image-spec/pull/164#issuecomment-243952187 [2]: https://github.com/opencontainers/image-spec/pull/164#issuecomment-244279771 [3]: https://github.com/opencontainers/image-spec/pull/164#r77871859 [4]: https://github.com/opencontainers/image-spec/pull/340#issuecomment-252670278 Signed-off-by: W. Trevor King --- Makefile | 2 +- README.md | 4 +++- canonicalization.md => considerations.md | 5 +++++ manifest-list.md | 15 +-------------- manifest.md | 4 ---- 5 files changed, 10 insertions(+), 20 deletions(-) rename canonicalization.md => considerations.md (84%) diff --git a/Makefile b/Makefile index 9db7dec2d..b373d5d31 100644 --- a/Makefile +++ b/Makefile @@ -31,7 +31,7 @@ DOC_FILES := \ config.md \ manifest.md \ manifest-list.md \ - canonicalization.md + considerations.md FIGURE_FILES := \ img/media-types.png diff --git a/README.md b/README.md index 756086dbd..917a522ca 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,9 @@ The OCI Image Format project creates and maintains the software shipping contain - [Image Configuration](config.md) - [Image Manifest](manifest.md) - [Image Manifest List](manifest-list.md) -- [Canonicalization](canonicalization.md) +- [Considerations](considerations.md) + - [Extensibility](considerations.md#extensibility) + - [Canonicalization](considerations.md#canonicalization) ## Overview diff --git a/canonicalization.md b/considerations.md similarity index 84% rename from canonicalization.md rename to considerations.md index 3875ad271..e2e8f4ccd 100644 --- a/canonicalization.md +++ b/considerations.md @@ -1,3 +1,8 @@ +# Extensibility + +Implementations that are reading/processing [manifests](manifest.md) or [manifest lists](manifest-list.md) MUST NOT generate an error if they encounter an unknown property. +Instead they MUST ignore unknown properties. + # Canonicalization OCI Images [are](descriptor.md) [content-addressable](image-layout.md). diff --git a/manifest-list.md b/manifest-list.md index b3aef15fe..085b07ad8 100644 --- a/manifest-list.md +++ b/manifest-list.md @@ -66,20 +66,7 @@ This section defines the `application/vnd.oci.image.manifest.list.v1+json` [medi - **`annotations`** *string-string map* - This OPTIONAL property contains arbitrary metadata for the manifest list. - Annotations MUST be a key-value map where both the key and value MUST be strings. - While the value MUST be present, it MAY be an empty string. - Keys MUST be unique within this map, and best practice is to namespace the keys. - Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`. - Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by other specifications. - If there are no annotations then this property MUST either be absent or be an empty map. - Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown annotation key. - - See [Pre-Defined Annotation Keys](manifest.md#pre-defined-annotation-keys). - -### Extensibility -Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown property. -Instead they MUST ignore unknown properties. + This OPTIONAL property contains arbitrary metadata for the manifest list with the same semantics as the [manifest's `annotations`](manifest.md#image-manifest-property-descriptions) ## Example Manifest List diff --git a/manifest.md b/manifest.md index 71fc35bb8..3979ca336 100644 --- a/manifest.md +++ b/manifest.md @@ -71,10 +71,6 @@ Unlike the [Manifest List](manifest-list.md), which contains information about a See [Pre-Defined Annotation Keys](#pre-defined-annotation-keys). -### Extensibility -Implementations that are reading/processing image manifests MUST NOT generate an error if they encounter an unknown property. -Instead they MUST ignore unknown properties. - ## Example Image Manifest *Example showing an image manifest:*