@openpresentation/opf 0.13.0 → 0.15.1

package/dist/spec/schemas/color-scheme.schema.json

@@ -2,23 +2,31 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-color-scheme/v1",
   "title": "Color Scheme",
-  "description": "Schema for color-scheme records in the pptx.gallery library. Each scheme is a named palette with the twelve PowerPoint color slots (six accents, two darks, two lights, plus hyperlink and followed-hyperlink), suitable for being mapped directly into OOXML theme XML. Color schemes are referenced from OPF documents via design.colorScheme or design.colorScheme.id; the engine resolves the reference against catalogs.colorSchemes (inline) -> catalogs.colorSchemes.source -> the default catalog at https://www.pptx.gallery/color-schemes. Slot overrides on design.colorScheme take precedence over the resolved scheme.\n\nThe slot fields here mirror the inline-override fields on the in-document ColorScheme type (in opf.schema.json), so library entries and inline OPF overrides are interchangeable.",
+  "description": "Schema for color-scheme records. Each scheme is a named palette with the twelve PowerPoint color slots (six accents, two darks, two lights, plus hyperlink and followed-hyperlink), suitable for being mapped directly into OOXML theme XML. Documents reference a scheme from design.colorScheme (or design.colorScheme.id) and from a theme's colorScheme; slot overrides on design.colorScheme take precedence over the resolved scheme.\n\nThe slot fields here mirror the inline-override fields on the in-document ColorScheme type (in opf.schema.json), so records and inline OPF overrides are interchangeable.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",
   "required": [
     "$schema",
     "id",
     "name"
   ],
+  "$defs": {
+    "HexColor": {
+      "type": "string",
+      "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
+      "description": "Hex color: '#RGB', '#RRGGBB' or '#RRGGBBAA'. The same definition as HexColor in opf.schema.json.",
+      "examples": ["#fff", "#2874A6", "#0F172AFF"]
+    }
+  },
   "properties": {
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-color-scheme/v1",
-      "description": "Identifies this record as a color scheme in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a colour scheme record. Required in a published file; an embedded copy omits it."
     },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this color scheme. Lowercase kebab-case.",
+      "description": "The colour scheme's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field.",
       "examples": [
         "cool-horizon",
         "boost",
@@ -36,27 +44,6 @@
         "Forest Green"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["replacedBy"],
-      "description": "Present when this color scheme is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated color scheme record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "summary": {
       "type": "string",
       "description": "One-sentence positioning of the palette — what mood it evokes and where to use it.",
@@ -73,7 +60,7 @@
       ]
     },
     "accent1": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 1 color (hex). Mirrors the OOXML accent1 slot.",
       "examples": [
         "#2874A6",
@@ -82,7 +69,7 @@
       ]
     },
     "accent2": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 2 color (hex). Mirrors the OOXML accent2 slot.",
       "examples": [
         "#1B4F72",
@@ -91,7 +78,7 @@
       ]
     },
     "accent3": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 3 color (hex). Mirrors the OOXML accent3 slot.",
       "examples": [
         "#5499C7",
@@ -100,7 +87,7 @@
       ]
     },
     "accent4": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 4 color (hex). Mirrors the OOXML accent4 slot.",
       "examples": [
         "#7BDBB2",
@@ -109,7 +96,7 @@
       ]
     },
     "accent5": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 5 color (hex). Mirrors the OOXML accent5 slot.",
       "examples": [
         "#3AC67A",
@@ -118,7 +105,7 @@
       ]
     },
     "accent6": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 6 color (hex). Mirrors the OOXML accent6 slot.",
       "examples": [
         "#24A89E",
@@ -127,42 +114,42 @@
       ]
     },
     "dark1": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Dark 1 color (hex). Typically the deepest neutral; OOXML dark1.",
       "examples": [
         "#000000"
       ]
     },
     "dark2": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Dark 2 color (hex). Secondary dark; OOXML dark2.",
       "examples": [
         "#011842"
       ]
     },
     "light1": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Light 1 color (hex). Typically the slide canvas; OOXML lt1.",
       "examples": [
         "#FFFFFF"
       ]
     },
     "light2": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Light 2 color (hex). Secondary light surface; OOXML lt2.",
       "examples": [
         "#F0F0F0"
       ]
     },
     "hyperlink": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Hyperlink color (hex). OOXML hlink.",
       "examples": [
         "#0563C1"
       ]
     },
     "followedHyperlink": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Followed-hyperlink color (hex). OOXML folHlink.",
       "examples": [
         "#954F72"

package/dist/spec/schemas/finding.schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openpresentation.org/schema/opf-finding/v1",
+  "title": "Finding Report",
+  "description": "The report format every OPF tool shares. A finding is one thing a checker found at one place in a presentation: a stable rule id, a severity, a category, a JSON Pointer path, a message, and optionally source positions, the measured numbers behind it and suggested fixes as JSON Patch. `validate` in `@openpresentation/opf`, the Markdown and YAML converters, the editor's Review panel and hosted reviewers such as pptx.dev's AI review all produce this shape, so a host shows and applies findings from any of them the same way. A report lists findings, tells whether any has severity `error` (`valid`) and counts them by severity; `validate` adds `schemaValid`, `checks` and variable fields on top of it. Core's checks are deterministic and run locally; findings from other producers use their own rule-id prefix and say so in `source`.",
+  "type": "object",
+  "required": ["valid", "findings", "counts"],
+  "properties": {
+    "valid": {
+      "type": "boolean",
+      "description": "True when no finding has severity `error`."
+    },
+    "findings": {
+      "type": "array",
+      "description": "Every finding, in report order.",
+      "items": { "$ref": "#/$defs/Finding" }
+    },
+    "counts": {
+      "type": "object",
+      "description": "How many findings each severity has.",
+      "required": ["error", "warning", "info"],
+      "additionalProperties": false,
+      "properties": {
+        "error": { "type": "integer", "minimum": 0 },
+        "warning": { "type": "integer", "minimum": 0 },
+        "info": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "$defs": {
+    "FindingSeverity": {
+      "type": "string",
+      "enum": ["error", "warning", "info"],
+      "description": "`error` makes a report invalid. `warning` is a problem the author should fix. `info` is advisory."
+    },
+    "FindingCategory": {
+      "description": "What kind of question the finding answers. Core uses `format` (is it well-formed OPF), `references` (does everything it points at resolve), `policy` (host house rules), `accessibility`, `layout` (will it present as authored) and `content` (is anything left unfinished). Other producers may use their own category names, such as `narrative` or `audience-fit`.",
+      "anyOf": [
+        { "type": "string", "enum": ["format", "references", "policy", "accessibility", "layout", "content"] },
+        { "type": "string", "minLength": 1 }
+      ]
+    },
+    "FindingLocation": {
+      "type": "object",
+      "description": "A range in the checked text: UTF-16 offset and length from the start, and the one-based line and column of the start. Present when the finding was produced from text (JSON, Markdown or YAML).",
+      "required": ["offset", "length", "line", "column"],
+      "additionalProperties": false,
+      "properties": {
+        "offset": { "type": "integer", "minimum": 0 },
+        "length": { "type": "integer", "minimum": 0 },
+        "line": { "type": "integer", "minimum": 1 },
+        "column": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "JsonPatchOperation": {
+      "description": "One RFC 6902 JSON Patch operation. Paths are JSON Pointers into the checked presentation.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["op", "path", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "op": { "type": "string", "enum": ["add", "replace", "test"] },
+            "path": { "type": "string" },
+            "value": {}
+          }
+        },
+        {
+          "type": "object",
+          "required": ["op", "path"],
+          "additionalProperties": false,
+          "properties": {
+            "op": { "type": "string", "const": "remove" },
+            "path": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["op", "from", "path"],
+          "additionalProperties": false,
+          "properties": {
+            "op": { "type": "string", "enum": ["move", "copy"] },
+            "from": { "type": "string" },
+            "path": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "FindingFocus": {
+      "type": "object",
+      "description": "The field an author has to fill in, for a fix that cannot be written as a patch.",
+      "required": ["path", "field"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string", "description": "JSON Pointer of the field to edit." },
+        "field": { "type": "string", "description": "What the field is, such as `alt`, `title`, `text`, `link`, `language` or `fontSize`." },
+        "value": { "type": ["string", "number", "boolean", "null", "array", "object"], "description": "The field's current value, when it has one." }
+      }
+    },
+    "FindingFix": {
+      "type": "object",
+      "description": "A suggested repair. Core never applies it: the host shows it and applies it through its own undoable edit path. A `patch` fix carries JSON Patch operations; a `focus` fix only names the field the author has to fill in.",
+      "required": ["title"],
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string", "minLength": 1, "description": "What applying the fix does, in a few words." },
+        "id": { "type": "string", "description": "Stable id within one finding, such as `focus-alt` or `use-readable-color`." },
+        "kind": { "type": "string", "enum": ["patch", "focus"], "default": "patch", "description": "`patch` fixes carry `patch`; `focus` fixes carry `focus`." },
+        "safe": { "type": "boolean", "description": "True when applying the fix cannot change what the content says or how it looks beyond the repair, such as switching a failing colour to the one the theme chose. False fixes need a deliberate choice." },
+        "patch": {
+          "type": "array",
+          "description": "RFC 6902 JSON Patch operations that apply the fix to the checked presentation.",
+          "items": { "$ref": "#/$defs/JsonPatchOperation" }
+        },
+        "focus": { "$ref": "#/$defs/FindingFocus" }
+      }
+    },
+    "FindingSuggestion": {
+      "type": "object",
+      "description": "A value the author could use instead, such as a catalog record that exists. Suggestions name records actually present in the checked context and never replace authored values silently.",
+      "required": ["value", "label", "origin"],
+      "additionalProperties": false,
+      "properties": {
+        "value": { "type": ["string", "number", "boolean", "null"] },
+        "label": { "type": "string" },
+        "origin": { "type": "string", "description": "Where the suggestion comes from: `schema`, `document` (a record the document embeds), `registered` (a catalog the host registered) or `contract`." },
+        "definition": { "type": "string", "description": "Where the suggested record or constraint is defined." }
+      }
+    },
+    "ValidationIssue": {
+      "type": "object",
+      "description": "The raw schema or semantic issue behind a finding, kept with every union alternative so a host can inspect the exact constraint.",
+      "required": ["path", "message", "keyword", "schemaPath", "params"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string" },
+        "message": { "type": "string" },
+        "keyword": { "type": "string", "description": "The JSON Schema keyword that failed, or `opf` for a rule the schema cannot express." },
+        "schemaPath": { "type": "string" },
+        "params": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "Finding": {
+      "type": "object",
+      "description": "One thing a checker found at one place in a presentation.",
+      "required": ["ruleId", "severity", "category", "path", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "ruleId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$",
+          "description": "Stable `<producer>/<rule>` id, such as `opf/text-contrast` for core or `pptx.dev/narrative-gap` for a hosted reviewer. Ids do not change between releases."
+        },
+        "source": {
+          "type": "string",
+          "description": "The producer: `opf` (the default) for core, or the name of another tool such as `pptx.dev/review`."
+        },
+        "severity": { "$ref": "#/$defs/FindingSeverity" },
+        "category": { "$ref": "#/$defs/FindingCategory" },
+        "path": {
+          "type": "string",
+          "description": "JSON Pointer to the value the finding is about, such as `/slides/4/title`. Empty for the whole document, or for a value in a supplied context such as a loaded catalog."
+        },
+        "scope": {
+          "type": "string",
+          "enum": ["document", "context"],
+          "description": "`document` (the default) when `path` points into the checked presentation, `context` when it points into host-supplied context such as loaded catalog records."
+        },
+        "message": { "type": "string", "minLength": 1, "description": "What is wrong, in a sentence." },
+        "help": { "type": "string", "description": "What to do about it." },
+        "slide": { "type": "integer", "minimum": 0, "description": "Zero-based index of the slide the finding belongs to." },
+        "slideId": { "type": "string", "description": "The id of that slide, when it has one." },
+        "location": { "$ref": "#/$defs/FindingLocation" },
+        "definition": { "type": "string", "description": "A link to the rule's documentation or to the schema constraint or catalog record the finding is about." },
+        "lookup": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Arguments for the `opf schema` or `opf catalog` command that shows the definition, as an argument list rather than a shell string."
+        },
+        "suggestions": { "type": "array", "items": { "$ref": "#/$defs/FindingSuggestion" } },
+        "measured": {
+          "type": "object",
+          "description": "The numbers behind the finding, such as `{ \"ratio\": 2.1, \"needed\": 4.5 }`.",
+          "additionalProperties": { "type": ["number", "string", "boolean", "null"] }
+        },
+        "fixes": { "type": "array", "items": { "$ref": "#/$defs/FindingFix" } },
+        "validation": { "$ref": "#/$defs/ValidationIssue" }
+      }
+    }
+  }
+}

package/dist/spec/schemas/font-scheme.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-font-scheme/v1",
   "title": "Font Scheme",
-  "description": "Schema for font-scheme records in the pptx.gallery library. Each scheme pairs a major (heading) and minor (body) font family in the OOXML majorFont/minorFont sense, scoped to a target app (PowerPoint or Google Slides) and a language family (Latin, East Asian, or Complex Script). Font schemes are referenced from OPF documents via design.fontScheme or design.fontScheme.id; the engine resolves the reference against catalogs.fontSchemes (inline) → catalogs.fontSchemes.source → the default catalog at https://www.pptx.gallery/font-schemes. Role overrides on design.fontScheme (heading, body, accent, code) take precedence over the resolved scheme.",
+  "description": "Schema for font-scheme records. Each scheme pairs a major (heading) and minor (body) font family in the OOXML majorFont/minorFont sense, scoped to a target app (powerpoint or google-slides) and a language family (Latin, East Asian, or Complex Script). Documents reference a scheme from design.fontScheme (or design.fontScheme.id), from a theme's fontScheme and from a language's fontScheme / googleFontScheme. Role overrides on design.fontScheme (heading, body, accent, code), each a font family name, take precedence over the resolved scheme.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",
   "required": [
     "$schema",
@@ -15,12 +15,12 @@
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-font-scheme/v1",
-      "description": "Identifies this record as a font scheme in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a font scheme record. Required in a published file; an embedded copy omits it."
     },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this font scheme. Lowercase kebab-case.",
+      "description": "The font scheme's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field.",
       "examples": [
         "aptos",
         "tenorite",
@@ -40,27 +40,6 @@
         "Microsoft Yahei"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["replacedBy"],
-      "description": "Present when this font scheme is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated font scheme record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "major": {
       "type": "string",
       "description": "Heading (major) font family — mirrors the OOXML majorFont entry.",
@@ -80,41 +59,11 @@
       ]
     },
     "code": {
-      "type": "object",
-      "description": "Optional monospaced font for code blocks and inline code. It has the same shape as the OPF FontScheme 'code' role, so a record and an inline design.fontScheme override are interchangeable. OOXML has no code slot, so exporters write this family on code runs. When neither design.fontScheme nor the resolved record defines 'code', engines fall back to Roboto Mono.",
-      "required": [
-        "family"
-      ],
-      "properties": {
-        "family": {
-          "type": "string",
-          "description": "Monospaced font family name.",
-          "examples": [
-            "Consolas",
-            "Courier New"
-          ]
-        },
-        "weight": {
-          "type": "number",
-          "description": "Numeric font weight (e.g., 400 for regular, 700 for bold)."
-        },
-        "style": {
-          "type": "string",
-          "enum": [
-            "normal",
-            "italic"
-          ],
-          "description": "Font style."
-        },
-        "letterSpacing": {
-          "type": "number",
-          "description": "Letter spacing (tracking) in ems."
-        }
-      },
+      "type": "string",
+      "description": "Optional monospaced font family name for code blocks and for inline code runs (TextRun.code). It has the same shape as the OPF FontScheme 'code' role, so a record and an inline design.fontScheme override are interchangeable. OOXML has no code slot, so exporters write this family on code runs. When neither design.fontScheme nor the resolved record defines 'code', engines fall back to Roboto Mono.",
       "examples": [
-        {
-          "family": "Consolas"
-        }
+        "Consolas",
+        "Courier New"
       ]
     },
     "eastAsian": {
@@ -181,34 +130,27 @@
     "app": {
       "type": "string",
       "enum": [
-        "PowerPoint",
-        "Google Slides"
+        "powerpoint",
+        "google-slides"
       ],
-      "description": "Target application this font pairing is intended for."
+      "description": "Target application this font pairing is intended for. Metadata for pickers and catalog filters: no engine changes its output by it."
     },
     "languageFamily": {
       "type": "string",
       "enum": [
         "latin",
         "ea",
-        "cs"
+        "cs",
+        "eastAsian",
+        "complexScript"
       ],
-      "description": "OOXML font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' for East Asian scripts, 'cs' for Complex Scripts. As the design font scheme, an 'ea' or 'cs' scheme also fills that script slot with its own major/minor families when its languages list is empty or names the presentation language."
+      "description": "Font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' (or 'eastAsian', the same value) for East Asian scripts, 'cs' (or 'complexScript', the same value) for Complex Scripts. The long names match the 'eastAsian' and 'complexScript' slot keys; the short names match the OOXML a:ea and a:cs elements; core reads both spellings as one value. As the design font scheme, an 'ea'/'eastAsian' or 'cs'/'complexScript' scheme also fills that script slot with its own major/minor families when its languages list is empty or names the presentation language."
     },
     "languages": {
       "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Optional list of human-readable language names this scheme is curated for. Useful for picker UIs that group fonts by language coverage.",
-      "examples": [
-        [
-          "Chinese (simplified)",
-          "Chinese (traditional)",
-          "Japanese",
-          "Korean"
-        ]
-      ]
+      "items": { "type": "string", "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$" },
+      "description": "Optional list of BCP-47 language tags this scheme is curated for. Useful for picker UIs that group fonts by language coverage. As the design font scheme, an 'ea' or 'cs' scheme fills its script slot only when this list is empty or names the presentation language: an entry matches a tag with the same language subtag (and the same script, when the entry names one).",
+      "examples": [["zh-Hans", "zh-Hant", "ja", "ko"]]
     },
     "textSample": {
       "type": "string",

package/dist/spec/schemas/language.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-language/v1",
   "title": "Language",
-  "description": "Schema for language records in the pptx.gallery library. Each record names a presentation language, carries a BCP-47 language tag, and pairs it with sensible default font schemes for PowerPoint and Google Slides output. Languages are referenced from OPF documents via language; the engine resolves the reference against catalogs.languages (inline) → catalogs.languages.source → the default catalog at https://www.pptx.gallery/languages. The presentation language field also accepts BCP-47 tags directly or inline Language objects for engine-aware language records that carry default-font hints.",
+  "description": "Schema for language records: display metadata for the language pickers of authoring tools (name, ISO code, the default font schemes a picker suggests). The document's 'language' is an engine vocabulary, a BCP-47 tag validated directly; engines never look a language record up, and their script, direction, OOXML tag and default script fonts come from spec/reference/engine-vocabularies.json. pptx.gallery publishes these records and @openpresentation/opf/catalog ships them as catalogDisplay.languages.",
   "type": "object",
   "required": [
     "$schema",
@@ -19,7 +19,7 @@
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this language via language. Lowercase kebab-case.",
+      "description": "The record's id in the gallery's language catalog, lowercase kebab-case. Documents name a language by its BCP-47 tag ('bcp47'), never by this id.",
       "examples": [
         "english",
         "spanish",
@@ -37,27 +37,6 @@
         "Chinese (simplified)"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["replacedBy"],
-      "description": "Present when this language is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated language record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "code": {
       "type": "string",
       "description": "ISO 639-3 (or 639-2) three-letter language code. Carried for engines that prefer ISO codes.",
@@ -83,23 +62,23 @@
     },
     "ooxmlLang": {
       "type": "string",
-      "description": "Curated culture tag for OOXML text-run language attributes (a:rPr/@lang, a:endParaRPr/@lang), in the language-[Script-]REGION form Office recognizes (e.g. 'ja-JP', 'ar-SA', 'ms-MY', 'nb-NO', 'fil-PH', 'zh-CN'). Engines emit it instead of 'bcp47' when the document names the language by catalog id or by a tag without a region; a region-bearing tag written by the author is emitted as written. Curated rather than inferred so output does not depend on the runtime's locale data.",
+      "description": "Curated culture tag for OOXML text-run language attributes (a:rPr/@lang, a:endParaRPr/@lang), in the language-[Script-]REGION form Office recognizes (e.g. 'ja-JP', 'ar-SA', 'ms-MY', 'nb-NO', 'fil-PH', 'zh-CN'). Engines emit it instead of 'bcp47' for a tag without a region; a region-bearing tag written by the author is emitted as written. Display metadata here: engines take the curated tag from their language vocabulary. Curated rather than inferred so output does not depend on the runtime's locale data.",
       "examples": ["en-US", "ja-JP", "ar-SA", "ms-MY", "nb-NO", "zh-CN"]
     },
     "direction": {
       "type": "string",
       "enum": ["ltr", "rtl"],
-      "description": "Base text direction for the language. When omitted, engines derive it from the script: Arabic (Arab), Hebrew (Hebr), Syriac (Syrc), Thaana (Thaa), N'Ko (Nkoo), Adlam (Adlm), Samaritan (Samr), Mandaic (Mand) and Hanifi Rohingya (Rohg) are right-to-left; every other script is left-to-right. Bundled language records state it explicitly.",
+      "description": "Base text direction for the language. When omitted, engines derive it from the script: Arabic (Arab), Hebrew (Hebr), Syriac (Syrc), Thaana (Thaa), N'Ko (Nkoo), Adlam (Adlm), Samaritan (Samr), Mandaic (Mand) and Hanifi Rohingya (Rohg) are right-to-left; every other script is left-to-right. The engine language vocabulary (spec/reference/engine-vocabularies.json) states it for the tags it knows.",
       "examples": ["ltr", "rtl"]
     },
     "script": {
       "type": "string",
-      "description": "ISO 15924 script code of the language's writing system. The script selects the OOXML font slot the language's text uses: East Asian scripts (Hans, Hant, Hani, Jpan, Kore, Hang, Hira, Kana, Bopo, Yiii) use the eastAsian slot; complex scripts (for example Arab, Hebr, Syrc, Thaa, Deva, Beng, Guru, Gujr, Orya, Taml, Telu, Knda, Mlym, Sinh, Thai, Laoo, Tibt, Mymr, Khmr, Mong) use the complexScript slot; every other script (Latn, Cyrl, Grek, Armn, Geor, Ethi, ...) uses the latin slot. When omitted, engines infer it from the BCP-47 tag. Bundled language records state it explicitly. See docs/programs/font-fidelity-everywhere/script-font-model.md.",
+      "description": "ISO 15924 script code of the language's writing system. The script selects the OOXML font slot the language's text uses: East Asian scripts (Hans, Hant, Hani, Jpan, Kore, Hang, Hira, Kana, Bopo, Yiii) use the eastAsian slot; complex scripts (for example Arab, Hebr, Syrc, Thaa, Deva, Beng, Guru, Gujr, Orya, Taml, Telu, Knda, Mlym, Sinh, Thai, Laoo, Tibt, Mymr, Khmr, Mong) use the complexScript slot; every other script (Latn, Cyrl, Grek, Armn, Geor, Ethi, ...) uses the latin slot. When omitted, engines infer it from the BCP-47 tag. The engine language vocabulary (spec/reference/engine-vocabularies.json) states it for the tags it knows. See docs/programs/font-fidelity-everywhere/script-font-model.md.",
       "examples": ["Latn", "Cyrl", "Grek", "Arab", "Hebr", "Jpan", "Kore", "Hans", "Hant", "Deva", "Thai"]
     },
     "fontScheme": {
       "type": "string",
-      "description": "Default font-scheme id for this language when targeting PowerPoint output. Resolves against catalogs.fontSchemes the same way design.fontScheme or design.fontScheme.id does. Its major/minor families fill the language's script slot (eastAsian or complexScript, chosen by 'script') unless the effective design font scheme sets that slot itself; the latin slot always follows the design font scheme.",
+      "description": "The font-scheme id a picker suggests for this language when targeting PowerPoint output. Display metadata: engines take a language's default script fonts from their own vocabulary.",
       "examples": [
         "aptos",
         "microsoft-yahei",
@@ -108,7 +87,7 @@
     },
     "googleFontScheme": {
       "type": "string",
-      "description": "Default font-scheme id for this language when targeting Google Slides output. Resolves against catalogs.fontSchemes the same way design.fontScheme or design.fontScheme.id does. Used in place of 'fontScheme' when resolving script fonts for Google Slides output.",
+      "description": "The font-scheme id a picker suggests for this language when targeting Google Slides output. Display metadata.",
       "examples": [
         "roboto",
         "noto-sans",