Language

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openpresentation.org/schema/opf-language/v1",
  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
  "title": "Language",
  "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/gallery ships them as catalogDisplay.languages.",
  "type": "object",
  "required": [
    "$schema",
    "id",
    "name",
    "bcp47"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "const": "https://openpresentation.org/schema/opf-language/v1",
      "description": "Identifies this record as a language in the openpresentation.org catalog."
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "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",
        "japanese",
        "chinese-simplified"
      ]
    },
    "name": {
      "type": "string",
      "description": "Human-readable language name.",
      "examples": [
        "English",
        "Spanish",
        "Japanese",
        "Chinese (simplified)"
      ]
    },
    "code": {
      "type": "string",
      "description": "ISO 639-3 (or 639-2) three-letter language code. Carried for engines that prefer ISO codes.",
      "examples": [
        "ENG",
        "SPA",
        "FRA",
        "JPN",
        "CHI"
      ]
    },
    "bcp47": {
      "type": "string",
      "description": "BCP-47 language tag for this record. Use 'en-GB' for UK English; 'en-UK' is not a valid BCP-47 region form.",
      "examples": [
        "en",
        "en-US",
        "en-GB",
        "es-MX",
        "ja-JP",
        "zh-Hans"
      ]
    },
    "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' 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. 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. 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": "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",
        "nirmala-ui"
      ]
    },
    "googleFontScheme": {
      "type": "string",
      "description": "The font-scheme id a picker suggests for this language when targeting Google Slides output. Display metadata.",
      "examples": [
        "roboto",
        "noto-sans",
        "noto-sans-sc"
      ]
    },
    "summary": {
      "type": "string",
      "description": "One-sentence note about coverage or font defaults.",
      "examples": [
        "English language preset using a Latin-script font scheme.",
        "Japanese language preset paired with a Microsoft YaHei East-Asian scheme."
      ]
    },
    "description": {
      "type": "string",
      "description": "Longer prose describing the language record and any font-pairing rationale.",
      "examples": [
        "English (US) preset. Defaults to Aptos for PowerPoint output and Roboto for Google Slides output. Use this entry as a baseline; override fontScheme on individual decks when brand fonts differ."
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Free-form labels for filtering and search.",
      "examples": [
        [
          "latin",
          "default"
        ],
        [
          "east-asian"
        ],
        [
          "complex-script",
          "rtl"
        ]
      ]
    },
    "preview": {
      "type": "object",
      "description": "Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available.",
      "properties": {
        "src": {
          "type": "string",
          "format": "uri",
          "description": "Main preview image (PNG/JPG). Used as the primary visual in picker UIs and previews of the record.",
          "examples": [
            "https://www.pptx.gallery/languages/english.png"
          ]
        },
        "thumbnailSrc": {
          "type": "string",
          "format": "uri",
          "description": "Smaller thumbnail preview suited to dense grid views.",
          "examples": [
            "https://www.pptx.gallery/languages/english.thumbnail.png"
          ]
        },
        "vectorSrc": {
          "type": "string",
          "format": "uri",
          "description": "SVG / vector preview for crisp scaling at any size.",
          "examples": [
            "https://www.pptx.gallery/languages/english.svg"
          ]
        }
      }
    }
  }
}