From 2c8feeb36ce0b8ae658541ec334d55d9496de7f3 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 12 Jan 2017 10:05:06 -0800 Subject: [PATCH 1/2] config: Bring "unique... within this map" back together Pull the empty-key restriction out into its own sentence (instead of leaving it in the middle of the uniqueness restriction). Drop the "best practice" portion, because the following line is "Keys SHOULD be named using a reverse domain notation...", which covers that idea more explicitly. Signed-off-by: W. Trevor King --- config.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/config.md b/config.md index 8b6bdd314..ad45d0387 100644 --- a/config.md +++ b/config.md @@ -393,7 +393,8 @@ If a hook returns a non-zero exit code, then an error is logged and the remainin This information MAY be structured or unstructured. 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 and MUST NOT be an empty string within this map, and best practice is to namespace the keys. +Keys MUST be unique within this map. +Keys MUST NOT be an empty string. 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 subsequent specifications. If there are no annotations then this property MAY either be absent or an empty map. From 9cc61372e83b9b0bb68cdcf7660e02da77470342 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 13 Jan 2017 07:26:12 -0800 Subject: [PATCH 2/2] config: Split annotations restrictions into one-per-sentence As recommended by Daniel [1], although I've adjusted his recommended wording slightly and split the requirements into paragraphs. [1]: https://github.com/opencontainers/runtime-spec/pull/654#discussion_r95981169 Signed-off-by: W. Trevor King --- config.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/config.md b/config.md index ad45d0387..8925318e1 100644 --- a/config.md +++ b/config.md @@ -391,15 +391,19 @@ If a hook returns a non-zero exit code, then an error is logged and the remainin **`annotations`** (object, OPTIONAL) contains arbitrary metadata for the container. This information MAY be structured or unstructured. -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. +Annotations MUST be a key-value map. +If there are no annotations then this property MAY either be absent or an empty map. + +Keys MUST be strings. Keys MUST be unique within this map. Keys MUST NOT be an empty string. 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 subsequent specifications. -If there are no annotations then this property MAY either be absent or an empty map. Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown annotation key. +Values MUST be strings. +Values MAY be an empty string. + ```json "annotations": { "com.example.gpu-cores": "2"