Add text about extensions

Doug Davis · Doug Davis · commit 27a05de3f66a · 2016-09-01T19:18:07.000-07:00
Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>
diff --git 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"
     }
 }
 ```
