Merge pull request opencontainers#510 from duglin/extension

Add text about extensions

Signed-off-by: Deng Guangxing <dengguangxing@huawei.com>

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"
     }
 }
 ```

schema/validate.go

@@ -6,39 +6,44 @@ import (
 	"os"
 	"path/filepath"
 
+	"github.com/urfave/cli"
 	"github.com/xeipuuv/gojsonschema"
 )
 
-func main() {
-	nargs := len(os.Args[1:])
-	if nargs == 0 || nargs > 2 {
-		fmt.Printf("ERROR: usage is: %s <schema.json> [<document.json>]\n", os.Args[0])
-		os.Exit(1)
-	}
+const usage = `check document with specified schema
+
+validate --schema <schema.json> <document.json>`
+
+func validate(context *cli.Context) error {
+	nargs := context.NArg()
 
-	schemaPath, err := filepath.Abs(os.Args[1])
+	schemaFile := context.String("schema")
+	if schemaFile == "" {
+		return fmt.Errorf("Error: schema-json file must be specified!")
+	}
+	schemaPath, err := filepath.Abs(schemaFile)
 	if err != nil {
-		fmt.Println(err)
-		os.Exit(1)
+		return fmt.Errorf("Error: invalid schema-file path: %s", err)
 	}
 	schemaLoader := gojsonschema.NewReferenceLoader("file://" + schemaPath)
 	var documentLoader gojsonschema.JSONLoader
 
-	if nargs > 1 {
-		documentPath, err := filepath.Abs(os.Args[2])
+	if nargs == 1 {
+		documentArg := context.Args().Get(0)
+		documentPath, err := filepath.Abs(documentArg)
 		if err != nil {
-			fmt.Println(err)
-			os.Exit(1)
+			return fmt.Errorf("Error: invalid document-file path: %s\n", err)
 		}
 		documentLoader = gojsonschema.NewReferenceLoader("file://" + documentPath)
-	} else {
+	} else if nargs == 0 {
 		documentBytes, err := ioutil.ReadAll(os.Stdin)
 		if err != nil {
-			fmt.Println(err)
-			os.Exit(1)
+			return fmt.Errorf("Error: read input document failed: %s\n", err)
 		}
 		documentString := string(documentBytes)
 		documentLoader = gojsonschema.NewStringLoader(documentString)
+	} else {
+		return fmt.Errorf("Error: invalid arguments number\n")
 	}
 
 	result, err := gojsonschema.Validate(schemaLoader, documentLoader)
@@ -53,6 +58,28 @@ func main() {
 		for _, desc := range result.Errors() {
 			fmt.Printf("- %s\n", desc)
 		}
+	}
+
+	return nil
+}
+
+func main() {
+	app := cli.NewApp()
+	app.Name = "validate"
+	app.Usage = usage
+
+	app.Flags = []cli.Flag{
+		cli.StringFlag{
+			Name:  "schema,s",
+			Value: "",
+			Usage: "specify the schema-json file",
+		},
+	}
+
+	app.Action = validate
+
+	if err := app.Run(os.Args); err != nil {
+		fmt.Println(err)
 		os.Exit(1)
 	}
 }