@kumwe/studio-protocol 0.1.0-alpha.10

package/schemas/media-reference.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/media-reference.schema.json",
+  "title": "Studio persisted media reference",
+  "description": "A small, usage-specific reference stored in an artifact. It contains no URL, binary data, storage path, credential, or host delivery authority.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "kind", "assetId", "usage", "accessibility"],
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "media-reference" },
+    "assetId": { "$ref": "common.schema.json#/$defs/stableId" },
+    "assetRevision": { "$ref": "common.schema.json#/$defs/revision" },
+    "usage": { "$ref": "common.schema.json#/$defs/qualifiedName" },
+    "renditionIntent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["role"],
+      "properties": {
+        "role": { "$ref": "common.schema.json#/$defs/localName" },
+        "fit": { "enum": ["contain", "cover", "fill", "scale-down"] },
+        "preferredMediaTypes": {
+          "type": "array",
+          "maxItems": 10,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9!#$&^_.+-]+/[a-z0-9!#$&^_.+-]+(?![\\s\\S])",
+            "maxLength": 200
+          }
+        }
+      }
+    },
+    "focalPoint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y"],
+      "properties": {
+        "x": { "type": "number", "minimum": 0, "maximum": 1 },
+        "y": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "cropIntent": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode", "width", "height"],
+          "properties": {
+            "mode": { "const": "aspect-ratio" },
+            "width": { "type": "integer", "minimum": 1, "maximum": 10000 },
+            "height": { "type": "integer", "minimum": 1, "maximum": 10000 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode", "x", "y", "width", "height"],
+          "properties": {
+            "mode": { "const": "rectangle" },
+            "x": { "type": "number", "minimum": 0, "maximum": 1 },
+            "y": { "type": "number", "minimum": 0, "maximum": 1 },
+            "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 },
+            "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }
+          }
+        }
+      ]
+    },
+    "accessibility": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode", "altText"],
+          "properties": {
+            "mode": { "const": "informative" },
+            "altText": { "type": "string", "minLength": 1, "maxLength": 5000 },
+            "caption": { "type": "string", "maxLength": 20000 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode"],
+          "properties": {
+            "mode": { "const": "decorative" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode", "altFieldPath"],
+          "properties": {
+            "mode": { "const": "bound" },
+            "altFieldPath": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 32,
+              "items": { "$ref": "common.schema.json#/$defs/localName" }
+            },
+            "captionFieldPath": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 32,
+              "items": { "$ref": "common.schema.json#/$defs/localName" }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/media-upload-grant.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/media-upload-grant.schema.json",
+  "title": "Studio media upload grant",
+  "description": "The host's authorization to transfer one upload. Bytes never cross the JSON port: the host issues a short-lived, single-purpose destination it controls and the client transfers directly to it, so custody, quotas and storage placement stay host-owned and a large body never traverses the port transport. A grant authorizes exactly the declared upload and expires; it is not a credential the client may reuse, cache, or apply to another upload.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["expiresAt", "method", "plan", "uploadId", "url"],
+  "properties": {
+    "expiresAt": {
+      "description": "When the grant stops being honoured. A client that has not completed by then re-authorizes rather than retrying against a dead destination.",
+      "$ref": "common.schema.json#/$defs/rfc3339Instant"
+    },
+    "headers": {
+      "description": "Headers the client must send verbatim on the transfer. They carry no user credential and are never logged by the client.",
+      "type": "object",
+      "maxProperties": 20,
+      "propertyNames": {
+        "type": "string",
+        "pattern": "^[A-Za-z][A-Za-z0-9-]*(?![\\s\\S])",
+        "maxLength": 100
+      },
+      "additionalProperties": { "type": "string", "maxLength": 2000 }
+    },
+    "method": { "enum": ["POST", "PUT"] },
+    "plan": {
+      "description": "The bounded transfer plan the host derived from its policy. The client transfers within it and never negotiates a larger bound.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["maximumBytes", "resumable"],
+      "properties": {
+        "chunkBytes": { "type": "integer", "minimum": 1024, "maximum": 1073741824 },
+        "maximumBytes": { "type": "integer", "minimum": 1, "maximum": 1099511627776 },
+        "resumable": { "type": "boolean" }
+      }
+    },
+    "uploadId": {
+      "description": "The opaque host-issued upload identity used to complete or abort the transfer.",
+      "$ref": "common.schema.json#/$defs/stableId"
+    },
+    "url": {
+      "description": "The absolute https destination the host controls. It is never an author-supplied value and never a Studio-derived address.",
+      "type": "string",
+      "pattern": "^https://",
+      "maxLength": 2000
+    }
+  }
+}

package/schemas/media-upload-session.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/media-upload-session.schema.json",
+  "title": "Studio media upload session",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "kind", "id", "request", "state", "progress"],
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "media-upload-session" },
+    "id": { "$ref": "common.schema.json#/$defs/stableId" },
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["filename", "mediaType", "byteSize", "purpose"],
+      "properties": {
+        "filename": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "pattern": "^[^\\u0000-\\u001F\\u007F/\\\\]+(?![\\s\\S])"
+        },
+        "mediaType": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9!#$&^_.+-]*/[a-z0-9][a-z0-9!#$&^_.+-]*(?![\\s\\S])",
+          "maxLength": 120
+        },
+        "byteSize": { "type": "integer", "minimum": 1, "maximum": 1099511627776 },
+        "purpose": { "$ref": "common.schema.json#/$defs/qualifiedName" },
+        "checksum": { "$ref": "common.schema.json#/$defs/integrity" }
+      }
+    },
+    "plan": { "$ref": "#/$defs/plan" },
+    "state": {
+      "enum": [
+        "requested",
+        "authorized",
+        "transferring",
+        "verifying",
+        "complete",
+        "failed",
+        "cancelled"
+      ]
+    },
+    "progress": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["transferredBytes", "totalBytes"],
+      "properties": {
+        "transferredBytes": { "type": "integer", "minimum": 0, "maximum": 1099511627776 },
+        "totalBytes": { "type": "integer", "minimum": 0, "maximum": 1099511627776 }
+      }
+    },
+    "asset": { "$ref": "#/$defs/acceptedAsset" },
+    "failure": { "$ref": "common.schema.json#/$defs/diagnostic" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "state": { "const": "complete" } }, "required": ["state"] },
+      "then": {
+        "properties": { "asset": { "$ref": "#/$defs/acceptedAsset" } },
+        "required": ["asset"]
+      }
+    },
+    {
+      "if": { "properties": { "state": { "const": "failed" } }, "required": ["state"] },
+      "then": {
+        "properties": { "failure": { "$ref": "common.schema.json#/$defs/diagnostic" } },
+        "required": ["failure"]
+      }
+    },
+    {
+      "if": {
+        "properties": { "state": { "enum": ["authorized", "transferring", "verifying"] } },
+        "required": ["state"]
+      },
+      "then": {
+        "properties": { "plan": { "$ref": "#/$defs/plan" } },
+        "required": ["plan"]
+      }
+    },
+    {
+      "if": { "properties": { "state": { "const": "requested" } }, "required": ["state"] },
+      "then": { "not": { "required": ["asset"] } }
+    }
+  ],
+  "$defs": {
+    "acceptedAsset": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "revision", "state"],
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/stableId" },
+        "revision": { "$ref": "common.schema.json#/$defs/revision" },
+        "state": { "enum": ["processing", "ready", "rejected", "quarantined"] }
+      }
+    },
+    "plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["maximumBytes", "resumable"],
+      "properties": {
+        "maximumBytes": { "type": "integer", "minimum": 1, "maximum": 1099511627776 },
+        "chunkBytes": { "type": "integer", "minimum": 1024, "maximum": 1073741824 },
+        "resumable": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schemas/media-vector.schema.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/media-vector.schema.json",
+  "title": "Studio canonical media policy vector",
+  "description": "One canonical upload-policy decision: a host-declared policy, an upload request, and either the deterministic policy-derived plan or a stable failure code, optionally extended with cancellation and retry legality for the media-upload-session state machine.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "kind", "id", "description", "policy", "request", "expect"],
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "media-vector" },
+    "id": { "$ref": "common.schema.json#/$defs/stableId" },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["acceptedMediaTypes", "maximumBytes", "resumable"],
+      "properties": {
+        "acceptedMediaTypes": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 100,
+          "items": { "$ref": "#/$defs/mediaType" }
+        },
+        "chunkBytes": { "type": "integer", "minimum": 1024, "maximum": 1073741824 },
+        "maximumBytes": { "type": "integer", "minimum": 1, "maximum": 1099511627776 },
+        "resumable": { "type": "boolean" }
+      }
+    },
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["filename", "mediaType", "byteSize", "purpose"],
+      "properties": {
+        "filename": {
+          "description": "Deliberately looser than the media-upload-session request shape so rejection vectors can carry filenames the canonical contract refuses.",
+          "type": "string",
+          "maxLength": 500
+        },
+        "mediaType": { "$ref": "#/$defs/mediaType" },
+        "byteSize": { "type": "integer", "minimum": 1, "maximum": 1099511627776 },
+        "purpose": { "$ref": "common.schema.json#/$defs/qualifiedName" },
+        "checksum": { "$ref": "common.schema.json#/$defs/integrity" }
+      }
+    },
+    "expect": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["outcome", "plan"],
+          "properties": {
+            "outcome": { "const": "accepted" },
+            "plan": { "$ref": "#/$defs/plan" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["outcome", "code"],
+          "properties": {
+            "outcome": { "const": "rejected" },
+            "code": { "$ref": "#/$defs/failureCode" },
+            "messageMustNotContain": {
+              "description": "Raw request or policy values the user-facing failure message MUST NOT echo.",
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 10,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200
+              }
+            }
+          }
+        }
+      ]
+    },
+    "cancel": {
+      "description": "Cancellation legality: the session state during which cancel() is issued and the resulting terminal state. Cancellation from an active state ends in cancelled; cancellation after completion is a no-op.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["during", "finalState"],
+      "properties": {
+        "during": { "enum": ["complete", "requested", "transferring", "verifying"] },
+        "finalState": { "enum": ["cancelled", "complete"] }
+      }
+    },
+    "retry": {
+      "description": "Retry legality for a rejected request: retry is legal only from the failed state and always runs under a fresh session identity with the identical request.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["freshSession"],
+      "properties": {
+        "freshSession": { "const": true }
+      }
+    }
+  },
+  "$defs": {
+    "failureCode": {
+      "enum": ["studio.media/upload-failed", "studio.media/upload-too-large"]
+    },
+    "mediaType": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9!#$&^_.+-]*/[a-z0-9][a-z0-9!#$&^_.+-]*(?![\\s\\S])",
+      "maxLength": 120
+    },
+    "plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["maximumBytes", "resumable"],
+      "properties": {
+        "maximumBytes": { "type": "integer", "minimum": 1, "maximum": 1099511627776 },
+        "chunkBytes": { "type": "integer", "minimum": 1024, "maximum": 1073741824 },
+        "resumable": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schemas/migration.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/migration.schema.json",
+  "title": "Studio migration declaration",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contractVersion",
+    "kind",
+    "id",
+    "version",
+    "owner",
+    "label",
+    "artifactKinds",
+    "sourceVersions",
+    "targetVersion",
+    "lossClassification"
+  ],
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "migration" },
+    "id": { "$ref": "common.schema.json#/$defs/qualifiedName" },
+    "version": { "$ref": "common.schema.json#/$defs/semanticVersion" },
+    "owner": { "$ref": "common.schema.json#/$defs/ownerReference" },
+    "label": { "$ref": "common.schema.json#/$defs/messageReference" },
+    "description": { "$ref": "common.schema.json#/$defs/messageReference" },
+    "artifactKinds": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 5,
+      "uniqueItems": true,
+      "items": {
+        "enum": ["block-definition", "blueprint", "content-model", "entry", "theme"]
+      }
+    },
+    "sourceVersions": { "$ref": "common.schema.json#/$defs/versionRange" },
+    "targetVersion": { "$ref": "common.schema.json#/$defs/semanticVersion" },
+    "lossClassification": { "enum": ["lossless", "lossy"] },
+    "extensions": { "$ref": "common.schema.json#/$defs/extensions" }
+  }
+}

package/schemas/pattern.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/pattern.schema.json",
+  "title": "Studio composition pattern",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contractVersion",
+    "kind",
+    "id",
+    "version",
+    "revision",
+    "owner",
+    "label",
+    "blockDependencies",
+    "roots"
+  ],
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "pattern" },
+    "id": { "$ref": "common.schema.json#/$defs/stableId" },
+    "version": { "$ref": "common.schema.json#/$defs/semanticVersion" },
+    "revision": { "$ref": "common.schema.json#/$defs/revision" },
+    "owner": { "$ref": "common.schema.json#/$defs/ownerReference" },
+    "label": { "$ref": "common.schema.json#/$defs/messageReference" },
+    "description": { "$ref": "common.schema.json#/$defs/messageReference" },
+    "blockDependencies": {
+      "type": "array",
+      "maxItems": 200,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["type", "version", "revision"],
+        "properties": {
+          "type": { "$ref": "common.schema.json#/$defs/qualifiedName" },
+          "version": { "$ref": "common.schema.json#/$defs/semanticVersion" },
+          "revision": { "$ref": "common.schema.json#/$defs/revision" },
+          "integrity": { "$ref": "common.schema.json#/$defs/integrity" }
+        }
+      }
+    },
+    "roots": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 100,
+      "items": { "$ref": "blueprint.schema.json#/$defs/node" }
+    },
+    "extensions": { "$ref": "common.schema.json#/$defs/extensions" }
+  }
+}

package/schemas/plugin-manifest.schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/plugin-manifest.schema.json",
+  "title": "Studio plugin manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contractVersion",
+    "kind",
+    "id",
+    "version",
+    "owner",
+    "label",
+    "activation",
+    "entryModules",
+    "contributions",
+    "requiredCapabilities",
+    "optionalCapabilities",
+    "dependencies",
+    "permissions"
+  ],
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "plugin-manifest" },
+    "id": { "$ref": "common.schema.json#/$defs/qualifiedName" },
+    "version": { "$ref": "common.schema.json#/$defs/semanticVersion" },
+    "owner": { "$ref": "common.schema.json#/$defs/ownerReference" },
+    "label": { "$ref": "common.schema.json#/$defs/messageReference" },
+    "description": { "$ref": "common.schema.json#/$defs/messageReference" },
+    "activation": { "enum": ["declarative", "executable"] },
+    "entryModules": {
+      "type": "array",
+      "maxItems": 10,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["realm", "path", "integrity"],
+        "properties": {
+          "realm": { "enum": ["application", "worker", "sandboxed-frame"] },
+          "path": { "$ref": "common.schema.json#/$defs/packageRelativePath" },
+          "integrity": { "$ref": "common.schema.json#/$defs/integrity" }
+        }
+      }
+    },
+    "contributions": {
+      "type": "array",
+      "maxItems": 5000,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "id", "version", "resource", "integrity"],
+        "properties": {
+          "kind": {
+            "enum": [
+              "block",
+              "command",
+              "design-vocabulary",
+              "field-adapter",
+              "inspector",
+              "locale",
+              "migration",
+              "panel",
+              "pattern",
+              "renderer-capability",
+              "test-fixture",
+              "transform"
+            ]
+          },
+          "id": { "$ref": "common.schema.json#/$defs/qualifiedName" },
+          "version": { "$ref": "common.schema.json#/$defs/semanticVersion" },
+          "resource": { "$ref": "common.schema.json#/$defs/packageRelativePath" },
+          "integrity": { "$ref": "common.schema.json#/$defs/integrity" },
+          "executable": { "type": "boolean", "default": false }
+        }
+      }
+    },
+    "requiredCapabilities": {
+      "type": "array",
+      "maxItems": 100,
+      "items": { "$ref": "#/$defs/capabilityRequirement" }
+    },
+    "optionalCapabilities": {
+      "type": "array",
+      "maxItems": 100,
+      "items": { "$ref": "#/$defs/capabilityRequirement" }
+    },
+    "dependencies": {
+      "type": "array",
+      "maxItems": 100,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "versions", "optional"],
+        "properties": {
+          "id": { "$ref": "common.schema.json#/$defs/qualifiedName" },
+          "versions": { "$ref": "common.schema.json#/$defs/versionRange" },
+          "optional": { "type": "boolean" }
+        }
+      }
+    },
+    "permissions": {
+      "type": "array",
+      "maxItems": 100,
+      "uniqueItems": true,
+      "items": { "$ref": "common.schema.json#/$defs/qualifiedName" }
+    },
+    "locales": {
+      "type": "array",
+      "maxItems": 100,
+      "uniqueItems": true,
+      "items": { "$ref": "common.schema.json#/$defs/locale" }
+    },
+    "extensions": { "$ref": "common.schema.json#/$defs/extensions" }
+  },
+  "$defs": {
+    "capabilityRequirement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "versions"],
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/qualifiedName" },
+        "versions": { "$ref": "common.schema.json#/$defs/versionRange" }
+      }
+    }
+  }
+}