From 070df5f5d99fea88b06ba45cb290f843dda832e6 Mon Sep 17 00:00:00 2001
From: BobDu <i@bobdu.cc>
Date: Wed, 19 Aug 2026 18:23:36 +0800
Subject: [PATCH] Describe integer fields with JSON types and bound the
 descriptor size

Signed-off-by: BobDu <i@bobdu.cc>
---
 descriptor.md                  |  3 ++-
 image-index.md                 |  2 +-
 manifest.md                    |  2 +-
 schema/defs-descriptor.json    |  2 +-
 schema/descriptor_test.go      | 11 +++++++++
 schema/image-index-schema.json |  2 +-
 schema/imageindex_test.go      | 44 ++++++++++++++++++++++++++++++++++
 7 files changed, 61 insertions(+), 5 deletions(-)

diff --git a/descriptor.md b/descriptor.md
index 56c76d6e4..44e953a76 100644
--- a/descriptor.md
+++ b/descriptor.md
@@ -29,12 +29,13 @@ The following fields contain the primary properties that constitute a Descriptor
   This REQUIRED property is the _digest_ of the targeted content, conforming to the requirements outlined in [Digests](#digests).
   Retrieved content SHOULD be verified against this digest when consumed via untrusted sources.
 
-- **`size`** *int64*
+- **`size`** *integer*
 
   This REQUIRED property specifies the size, in bytes, of the raw content.
   This property exists so that a client will have an expected size for the content before processing.
   If the length of the retrieved content does not match the specified length, the content SHOULD NOT be trusted.
   The size MUST NOT be negative.
+  The size MUST NOT be greater than 9007199254740991 (2^53-1).
 
 - **`urls`** *array of strings*
 
diff --git a/image-index.md b/image-index.md
index 7cd44ea2e..3a38b030c 100644
--- a/image-index.md
+++ b/image-index.md
@@ -9,7 +9,7 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
 
 ## _Image Index_ Property Descriptions
 
-- **`schemaVersion`** *int*
+- **`schemaVersion`** *integer*
 
   This REQUIRED property specifies the image manifest schema version.
   For this version of the specification, this MUST be `2` to ensure backward compatibility with older versions of Docker.
diff --git a/manifest.md b/manifest.md
index 7a0ef7340..ac8365470 100644
--- a/manifest.md
+++ b/manifest.md
@@ -15,7 +15,7 @@ Unlike the [image index](image-index.md), which contains information about a set
 
 ## _Image Manifest_ Property Descriptions
 
-- **`schemaVersion`** *int*
+- **`schemaVersion`** *integer*
 
   This REQUIRED property specifies the image manifest schema version.
   For this version of the specification, this MUST be `2` to ensure backward compatibility with older versions of Docker. The value of this field will not change. This field MAY be removed in a future version of the specification.
diff --git a/schema/defs-descriptor.json b/schema/defs-descriptor.json
index 6fdc86e80..cd42deb66 100644
--- a/schema/defs-descriptor.json
+++ b/schema/defs-descriptor.json
@@ -10,7 +10,7 @@
     "size": {
       "type": "integer",
       "minimum": 0,
-      "maximum": 9223372036854776000
+      "maximum": 9007199254740991
     },
     "digest": {
       "description": "the cryptographic checksum digest of the object, in the pattern '<algorithm>:<encoded>'",
diff --git a/schema/descriptor_test.go b/schema/descriptor_test.go
index 94f9f8d4c..fac35c86c 100644
--- a/schema/descriptor_test.go
+++ b/schema/descriptor_test.go
@@ -390,6 +390,17 @@ func TestDescriptor(t *testing.T) {
   "mediaType": "application/vnd.oci.image.manifest.v1+json",
   "size": -7682,
   "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270"
+}`,
+			fail: true,
+		},
+
+		// expected failure: size is outside the safe integer range of a double
+		{
+			descriptor: `
+{
+  "mediaType": "application/vnd.oci.image.manifest.v1+json",
+  "size": 9007199254740992,
+  "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270"
 }`,
 			fail: true,
 		},
diff --git a/schema/image-index-schema.json b/schema/image-index-schema.json
index 2e5dbf5cd..d6b6a4308 100644
--- a/schema/image-index-schema.json
+++ b/schema/image-index-schema.json
@@ -39,7 +39,7 @@
           },
           "size": {
             "description": "the size in bytes of the referenced object",
-            "$ref": "defs.json#/definitions/int64"
+            "$ref": "defs-descriptor.json#/definitions/size"
           },
           "digest": {
             "description": "the cryptographic checksum digest of the object, in the pattern '<algorithm>:<encoded>'",
diff --git a/schema/imageindex_test.go b/schema/imageindex_test.go
index bc230feb3..cf9ba9466 100644
--- a/schema/imageindex_test.go
+++ b/schema/imageindex_test.go
@@ -302,6 +302,50 @@ func TestImageIndex(t *testing.T) {
   ],
   "subject" : "nope"
 }
+`,
+			fail: true,
+		},
+
+		// expected failure: negative manifest size
+		{
+			imageIndex: `
+{
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.index.v1+json",
+  "manifests": [
+    {
+      "mediaType": "application/vnd.oci.image.manifest.v1+json",
+      "size": -7682,
+      "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
+      "platform": {
+        "architecture": "amd64",
+        "os": "linux"
+      }
+    }
+  ]
+}
+`,
+			fail: true,
+		},
+
+		// expected failure: manifest size is outside the safe integer range of a double
+		{
+			imageIndex: `
+{
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.index.v1+json",
+  "manifests": [
+    {
+      "mediaType": "application/vnd.oci.image.manifest.v1+json",
+      "size": 9007199254740992,
+      "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
+      "platform": {
+        "architecture": "amd64",
+        "os": "linux"
+      }
+    }
+  ]
+}
 `,
 			fail: true,
 		},