From 27a05de3f66a0b2e255dd1f197b2ca4f17fb4a1e Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Sun, 26 Jun 2016 12:49:13 -0700 Subject: [PATCH] Add text about extensions Mimic https://github.com/opencontainers/image-spec/pull/164 and they should be kept in-sync Signed-off-by: Doug Davis --- config.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/config.md b/config.md index 8d2d746d3..42b782ab8 100644 --- a/config.md +++ b/config.md @@ -324,15 +324,24 @@ The semantics are the same as `Path`, `Args` and `Env` in [golang Cmd](https://g **`annotations`** (object, optional) contains arbitrary metadata for the container. This information MAY be structured or unstructured. -Annotations are key-value maps. +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 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. ```json "annotations": { - "key1" : "value1", - "key2" : "value2" + "com.example.gpu-cores" : "2" } ``` +## Extensibility +Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unkown property. +Instead they MUST ignore unknown properties. + ## Configuration Schema Example Here is a full example `config.json` for reference. @@ -683,8 +692,8 @@ Here is a full example `config.json` for reference. "mountLabel": "system_u:object_r:svirt_sandbox_file_t:s0:c715,c811" }, "annotations": { - "key1": "value1", - "key2": "value2" + "com.example.key1": "value1", + "com.example.key2": "value2" } } ```