image-index: stipulate architecture-specific conventions

 * os.version:  speculated Windows-specific convention from the example
 * os.features: still unclear. should be clearly standardized in post-v1.0.0
 * variant:     speculated arm-specific convention from the example
 * features:    speculated x86-specific convention from the example, and put little modification

Signed-off-by: Akihiro Suda <[email protected]>

Author: AkihiroSuda

image-index.md

@@ -55,19 +55,29 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
 
     - **`os.version`** *string*
 
-        This OPTIONAL property specifies the operating system version, for example `10.0.10586`.
+        This OPTIONAL property specifies the operating system version.
+        Image indexes SHOULD use, and implementations SHOULD understand the following convention:
+        - `windows`: `sprintf("%d.%d.%d", dwMajorVersion, dwMinorVersion, dwBuildNumber)` with the fields of the `OSVERSIONINFOEX` structure returned by `GetVersionEx()`. e.g., `10.0.10586`.
+        If an operating system is not listed here, it SHOULD be submitted to this specification for standardization.
 
     - **`os.features`** *array of strings*
 
         This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature (for example on Windows `win32k`).
+        A convention for other features SHOULD be submitted to this specification for standardization.
 
     - **`variant`** *string*
 
-        This OPTIONAL property specifies the variant of the CPU, for example `armv6l` to specify a particular CPU variant of the ARM CPU.
+        This OPTIONAL property specifies the variant of the CPU.
+        Image indexes SHOULD use, and implementations SHOULD understand the following convention:
+        - `arm` and `arm64`: `machine` field of the Linux `utsname` structure returned by `uname(2)`. e.g., `armv6l`.
+        If an architecture is not listed here, it SHOULD be submitted to this specification for standardization.
 
     - **`features`** *array of strings*
 
-        This OPTIONAL property specifies an array of strings, each specifying a mandatory CPU feature (for example `sse4` or `aes`).
+        This OPTIONAL property specifies an array of strings, each specifying a mandatory CPU feature.
+        Image indexes SHOULD use, and implementations SHOULD understand the following convention:
+        - `386` and `amd64`: `flags` entries of the Linux `/proc/cpuinfo`. e.g., `sse4_2` or `aes`.
+        If an architecture is not listed here, it SHOULD be submitted to this specification for standardization.
 
 - **`annotations`** *string-string map*
 
@@ -100,7 +110,7 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
         "architecture": "amd64",
         "os": "linux",
         "os.features": [
-          "sse4"
+          "sse4_2"
         ]
       }
     }

schema/imageindex_test.go

@@ -61,7 +61,7 @@ func TestImageIndex(t *testing.T) {
         "architecture": "amd64",
         "os": "linux",
         "features": [
-          "sse4"
+          "sse4_2"
         ]
       }
     }
@@ -84,7 +84,7 @@ func TestImageIndex(t *testing.T) {
         "architecture": "amd64",
         "os": "linux",
         "features": [
-          "sse4"
+          "sse4_2"
         ]
       }
     }
@@ -128,7 +128,7 @@ func TestImageIndex(t *testing.T) {
         "architecture": "amd64",
         "os": "linux",
         "features": [
-          "sse4"
+          "sse4_2"
         ]
       }
     }
@@ -152,7 +152,7 @@ func TestImageIndex(t *testing.T) {
         "architecture": "amd64",
         "os": "linux",
         "features": [
-          "sse4"
+          "sse4_2"
         ]
       }
     }
@@ -185,7 +185,7 @@ func TestImageIndex(t *testing.T) {
         "architecture": "amd64",
         "os": "linux",
         "features": [
-          "sse4"
+          "sse4_2"
         ]
       }
     }

specs-go/v1/index.go

@@ -26,19 +26,19 @@ type Platform struct {
 	OS string `json:"os"`
 
 	// OSVersion is an optional field specifying the operating system
-	// version, for example `10.0.10586`.
+	// version, for example on Windows `10.0.10586`.
 	OSVersion string `json:"os.version,omitempty"`
 
 	// OSFeatures is an optional field specifying an array of strings,
 	// each listing a required OS feature (for example on Windows `win32k`).
 	OSFeatures []string `json:"os.features,omitempty"`
 
 	// Variant is an optional field specifying a variant of the CPU, for
-	// example `ppc64le` to specify a little-endian version of a PowerPC CPU.
+	// example `armv6l` to specify a particular CPU variant of the ARM CPU.
 	Variant string `json:"variant,omitempty"`
 
 	// Features is an optional field specifying an array of strings, each
-	// listing a required CPU feature (for example `sse4` or `aes`).
+	// listing a required CPU feature (for example `sse4_2` or `aes` on 386 and amd64).
 	Features []string `json:"features,omitempty"`
 }