@textmode/document 0.0.0-stage → 1.0.0

package/schemas/2.0/schema.json

@@ -0,0 +1,357 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://textmode.art/schemas/textmode-document-2.0.schema.json",
+	"title": "Textmode document 2.0",
+	"description": "Editable textmode cell snapshots and layer stacks.",
+	"oneOf": [
+		{
+			"$ref": "#/$defs/selectedDocument"
+		},
+		{
+			"$ref": "#/$defs/allDocument"
+		}
+	],
+	"$defs": {
+		"positiveSafeInteger": {
+			"type": "integer",
+			"minimum": 1,
+			"maximum": 9007199254740991,
+			"description": "Positive integer in the interoperable JavaScript safe range."
+		},
+		"canvas": {
+			"type": "object",
+			"required": ["width", "height"],
+			"properties": {
+				"width": {
+					"$ref": "#/$defs/positiveSafeInteger",
+					"description": "Width in pixels; the decoder checks equality with the corresponding grid product."
+				},
+				"height": {
+					"$ref": "#/$defs/positiveSafeInteger",
+					"description": "Height in pixels; the decoder checks equality with the corresponding grid product."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Legacy grid pixel extent. For selected documents this equals the grid extent; for all documents it equals the first layer grid extent. It is not a composite viewport. See docs/specification-2.0.md#canvas-field."
+		},
+		"grid": {
+			"type": "object",
+			"required": ["cols", "rows", "cellWidth", "cellHeight"],
+			"properties": {
+				"cols": {
+					"$ref": "#/$defs/positiveSafeInteger",
+					"description": "Positive number of columns."
+				},
+				"rows": {
+					"$ref": "#/$defs/positiveSafeInteger",
+					"description": "Positive number of rows."
+				},
+				"cellWidth": {
+					"$ref": "#/$defs/positiveSafeInteger",
+					"description": "Positive cell width in pixels."
+				},
+				"cellHeight": {
+					"$ref": "#/$defs/positiveSafeInteger",
+					"description": "Positive cell height in pixels."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Logical cell count and pixel dimensions of each cell. Products must remain safe integers."
+		},
+		"rgba": {
+			"type": "object",
+			"required": ["r", "g", "b", "a"],
+			"properties": {
+				"r": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 255,
+					"description": "Red channel."
+				},
+				"g": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 255,
+					"description": "Green channel."
+				},
+				"b": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 255,
+					"description": "Blue channel."
+				},
+				"a": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 255,
+					"description": "Alpha: 0 is transparent and 255 is opaque."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Unpremultiplied RGBA integer channels from 0 through 255."
+		},
+		"color": {
+			"oneOf": [
+				{
+					"type": "string",
+					"pattern": "^#[0-9A-Fa-f]{6}(?:[0-9A-Fa-f]{2})?$"
+				},
+				{
+					"$ref": "#/$defs/rgba"
+				}
+			],
+			"description": "RGB or RGBA hexadecimal notation, or explicit RGBA channels. Six-digit notation implies alpha 255."
+		},
+		"transform": {
+			"type": "object",
+			"required": ["invert", "flipX", "flipY", "rotation"],
+			"properties": {
+				"invert": {
+					"type": "boolean",
+					"description": "Glyph inversion; alpha means this cannot generally be replaced by swapping colors."
+				},
+				"flipX": {
+					"type": "boolean",
+					"description": "Mirror the glyph horizontally."
+				},
+				"flipY": {
+					"type": "boolean",
+					"description": "Mirror the glyph vertically."
+				},
+				"rotation": {
+					"type": "number",
+					"description": "Cell rotation in degrees; normalized by the decoder to [0, 360)."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Per-cell glyph transforms. Rotation is finite degrees; decoding normalizes it to [0, 360)."
+		},
+		"cell": {
+			"type": "object",
+			"required": ["x", "y", "character", "foreground", "background", "transform"],
+			"properties": {
+				"x": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 9007199254740991,
+					"description": "Zero-based column index; must equal the position within its row."
+				},
+				"y": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 9007199254740991,
+					"description": "Zero-based row index; must equal the row position."
+				},
+				"character": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 64,
+					"description": "Nonempty Unicode glyph string, preserved without normalization. The decoder rejects unpaired surrogates and enforces a scalar-count budget."
+				},
+				"foreground": {
+					"$ref": "#/$defs/color",
+					"description": "Glyph color with alpha."
+				},
+				"background": {
+					"$ref": "#/$defs/color",
+					"description": "Cell background color with alpha. A space with a visible background remains meaningful."
+				},
+				"transform": {
+					"$ref": "#/$defs/transform",
+					"description": "Per-cell glyph inversion, flips, and rotation."
+				}
+			},
+			"additionalProperties": true,
+			"description": "One cell at its redundant zero-based row and column. Coordinates must match array position; this cross-field rule is checked by the decoder."
+		},
+		"cells": {
+			"type": "object",
+			"required": ["encoding", "rows"],
+			"properties": {
+				"encoding": {
+					"const": "object-rows-v1",
+					"description": "Tagged cell encoding; v2 supports only object-rows-v1."
+				},
+				"rows": {
+					"type": "array",
+					"items": {
+						"type": "array",
+						"items": {
+							"$ref": "#/$defs/cell"
+						}
+					},
+					"description": "Dense row-major arrays; row count and lengths must equal the owning grid. The decoder checks this invariant."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Dense row-major cells, including transparent cells. Row count and lengths must equal the grid. See docs/specification-2.0.md#cell-encoding."
+		},
+		"metadata": {
+			"type": "object",
+			"required": ["createdAt", "generator"],
+			"properties": {
+				"createdAt": {
+					"type": "string",
+					"format": "date-time",
+					"pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]+)?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])$",
+					"description": "Real calendar date and time with uppercase T and timezone, required seconds, optional fractional seconds, and no leap seconds. Enable date-time format assertions in validators."
+				},
+				"generator": {
+					"type": "object",
+					"required": ["name", "version"],
+					"properties": {
+						"name": {
+							"type": "string",
+							"minLength": 1
+						},
+						"version": {
+							"type": "string",
+							"minLength": 1
+						}
+					},
+					"additionalProperties": true,
+					"description": "Producer identity; it does not select executable behavior."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Optional informational creation and generator metadata. When present, both members are required."
+		},
+		"selectedLayer": {
+			"type": "object",
+			"required": ["id", "cells"],
+			"properties": {
+				"id": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Nonempty informational source identifier. It is not a persistent cross-document identity; the decoder does not enforce uniqueness."
+				},
+				"cells": {
+					"$ref": "#/$defs/cells",
+					"description": "Complete dense cell rows."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Informational source ID and cells. A selected snapshot does not carry layer presentation or font identity."
+		},
+		"stackLayer": {
+			"type": "object",
+			"required": ["id", "visible", "opacity", "blendMode", "offsetX", "offsetY", "rotationZ", "grid", "cells"],
+			"properties": {
+				"id": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Nonempty informational source identifier. It is not a persistent cross-document identity; the decoder does not enforce uniqueness."
+				},
+				"visible": {
+					"type": "boolean",
+					"description": "Whether the layer participates in presentation. Hidden cells are still stored."
+				},
+				"opacity": {
+					"type": "number",
+					"minimum": 0,
+					"maximum": 1,
+					"description": "Layer opacity from 0 through 1, separate from cell alpha."
+				},
+				"blendMode": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Nonempty blend mode name. The decoder preserves unknown names; apps decide which they can present."
+				},
+				"offsetX": {
+					"type": "number",
+					"description": "Horizontal compositing offset in pixels."
+				},
+				"offsetY": {
+					"type": "number",
+					"description": "Vertical compositing offset in pixels."
+				},
+				"rotationZ": {
+					"type": "number",
+					"description": "Layer rotation in degrees, clockwise about the layer center in textmode.js; preserved by the decoder."
+				},
+				"grid": {
+					"$ref": "#/$defs/grid",
+					"description": "Grid dimensions and cell metrics."
+				},
+				"cells": {
+					"$ref": "#/$defs/cells",
+					"description": "Complete dense cell rows."
+				}
+			},
+			"additionalProperties": true,
+			"description": "One ordered layer with independent grid, cells, and presentation values."
+		},
+		"selectedDocument": {
+			"type": "object",
+			"required": ["format", "formatVersion", "target", "canvas", "grid", "layer"],
+			"properties": {
+				"format": {
+					"const": "textmode.document",
+					"description": "Required format discriminator."
+				},
+				"formatVersion": {
+					"const": "2.0.0",
+					"description": "On-disk format version, independent of package versions."
+				},
+				"target": {
+					"const": "selected",
+					"description": "Shape discriminator: selected uses layer and root grid; all uses layers."
+				},
+				"metadata": {
+					"$ref": "#/$defs/metadata",
+					"description": "metadata"
+				},
+				"canvas": {
+					"$ref": "#/$defs/canvas",
+					"description": "Legacy grid pixel extent, not the final canvas or a composite viewport."
+				},
+				"grid": {
+					"$ref": "#/$defs/grid",
+					"description": "Grid dimensions and cell metrics."
+				},
+				"layer": {
+					"$ref": "#/$defs/selectedLayer",
+					"description": "One cell snapshot."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Selected cell snapshot. All listed properties except metadata are required."
+		},
+		"allDocument": {
+			"type": "object",
+			"required": ["format", "formatVersion", "target", "canvas", "layers"],
+			"properties": {
+				"format": {
+					"const": "textmode.document",
+					"description": "Required format discriminator."
+				},
+				"formatVersion": {
+					"const": "2.0.0",
+					"description": "On-disk format version, independent of package versions."
+				},
+				"target": {
+					"const": "all",
+					"description": "Shape discriminator: selected uses layer and root grid; all uses layers."
+				},
+				"metadata": {
+					"$ref": "#/$defs/metadata",
+					"description": "metadata"
+				},
+				"canvas": {
+					"$ref": "#/$defs/canvas",
+					"description": "Legacy grid pixel extent, not the final canvas or a composite viewport."
+				},
+				"layers": {
+					"type": "array",
+					"minItems": 1,
+					"items": {
+						"$ref": "#/$defs/stackLayer"
+					},
+					"description": "Nonempty ordered layer stack, bottom first."
+				}
+			},
+			"additionalProperties": true,
+			"description": "One or more layers in bottom-to-top order. The decoder applies cumulative cell and layer budgets."
+		}
+	}
+}