diff --git a/image-index.md b/image-index.md
index c85fd47b8..f6dd89cdd 100644
--- a/image-index.md
+++ b/image-index.md
@@ -55,15 +55,15 @@ 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 is *reserved* for future versions of the specification and hence SHOULD NOT be used.
 
     - **`os.features`** *array of strings*
 
-        This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature (for example on Windows `win32k`).
+        This OPTIONAL property is *reserved* for future versions of the specification and hence SHOULD NOT be used.
 
     - **`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 is *reserved* for future versions of the specification and hence SHOULD NOT be used.
 
     - **`features`** *array of strings*
 
diff --git a/specs-go/v1/descriptor.go b/specs-go/v1/descriptor.go
index c461647ef..b96c777f8 100644
--- a/specs-go/v1/descriptor.go
+++ b/specs-go/v1/descriptor.go
@@ -51,15 +51,16 @@ type Platform struct {
 	OS string `json:"os"`
 
 	// OSVersion is an optional field specifying the operating system
-	// version, for example `10.0.10586`.
+	// version. This property is reserved and SHOULD NOT be used.
 	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`).
+	// each listing a required OS feature. This property is reserved and
+	// SHOULD NOT be used.
 	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.
+	// Variant is an optional field specifying a variant of the CPU.
+	// This property is reserved and SHOULD NOT be used.
 	Variant string `json:"variant,omitempty"`
 
 	// Features is an optional field specifying an array of strings, each