Font Inventory Schema v1.3¶
NOTE¶
The runtime JSON schema is the sole source of truth and lives in:
src/fontshow/schema/inventory_v1_3.json
This document is a human-oriented rendering of that schema.
Full JSON Schema¶
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "urn:fontshow:schema:inventory:1.3",
"title": "Fontshow Inventory Schema v1.3",
"description": "Canonical Fontshow inventory schema for normalized font discovery, enrichment, and LaTeX-oriented validation metadata.",
"type": "object",
"required": [
"metadata",
"fonts"
],
"additionalProperties": false,
"properties": {
"metadata": {
"type": "object",
"description": "Inventory-wide metadata describing the producer, runtime environment, and validation context associated with the inventory file.",
"required": [
"schema_version",
"input_inventory_tool",
"input_inventory_tool_version",
"inference_level",
"fonttools",
"run_environment",
"validation"
],
"additionalProperties": false,
"properties": {
"schema_version": {
"type": "string",
"const": "1.3",
"description": "Schema version identifier for this inventory document."
},
"input_inventory_tool": {
"type": "string",
"minLength": 1,
"description": "Command or component that produced the current inventory payload."
},
"input_inventory_tool_version": {
"type": "string",
"minLength": 1,
"description": "Version string of the tool that produced the current inventory payload."
},
"inference_level": {
"type": "string",
"minLength": 1,
"description": "Inference strictness or enrichment level applied to the inventory."
},
"fonttools": {
"type": "object",
"description": "Versioned metadata about the fontTools extraction surface available when the inventory was produced.",
"required": [
"available",
"fontconfig_charset_included",
"version"
],
"additionalProperties": false,
"properties": {
"available": {
"type": "boolean",
"description": "Whether fontTools was available to the producing command."
},
"fontconfig_charset_included": {
"type": "boolean",
"description": "Whether Fontconfig charset-derived information was included in the inventory."
},
"version": {
"type": "string",
"minLength": 1,
"description": "fontTools version reported during inventory generation."
}
}
},
"run_environment": {
"type": "object",
"description": "Minimal system identification for reproducibility and diagnostics.",
"required": [
"os",
"os_release",
"kernel",
"machine",
"python_version",
"hostname",
"execution_context"
],
"additionalProperties": true,
"properties": {
"os": {
"type": "string",
"minLength": 1,
"description": "Operating-system name reported by the producing environment."
},
"os_release": {
"type": "string",
"minLength": 1,
"description": "Operating-system release identifier of the producing environment."
},
"kernel": {
"type": "string",
"minLength": 1,
"description": "Kernel identifier of the producing environment."
},
"machine": {
"type": "string",
"minLength": 1,
"description": "Machine architecture reported by the producing environment."
},
"python_version": {
"type": "string",
"minLength": 1,
"description": "Python runtime version used by the producing command."
},
"hostname": {
"type": "string",
"minLength": 1,
"description": "Hostname reported by the producing environment."
},
"execution_context": {
"type": "string",
"enum": [
"native",
"wsl",
"container",
"other"
],
"description": "Normalized execution context classification for the producing environment."
}
}
},
"validation": {
"type": "object",
"description": "Inventory-wide validation metadata for external runtime surfaces relevant to downstream processing.",
"required": [
"lualatex"
],
"additionalProperties": false,
"properties": {
"lualatex": {
"$ref": "#/$defs/lualatex_validation_metadata",
"description": "Inventory-level LaTeX runtime metadata describing the LuaLaTeX environment associated with validation and loadability decisions."
}
}
}
}
},
"fonts": {
"type": "array",
"description": "List of normalized per-face font entries contained in the inventory.",
"items": {
"$ref": "#/$defs/font_entry"
}
}
},
"$defs": {
"font_entry": {
"type": "object",
"description": "Canonical per-face inventory entry containing identity, metrics, enrichment, typography, and validation state.",
"additionalProperties": false,
"required": [
"path",
"family",
"subfamily",
"typographic_subfamily",
"full_name",
"postscript_name",
"version_string",
"unique_font_id",
"metrics",
"coverage",
"inference",
"charset",
"typography",
"loadability"
],
"properties": {
"path": {
"type": "string",
"minLength": 1,
"description": "Canonical font file path. Multiple faces in the same file share this path."
},
"family": {
"type": "string",
"minLength": 1,
"description": "Canonical family name associated with the font face."
},
"subfamily": {
"type": "string",
"minLength": 1,
"description": "Style or face name reported for the font entry."
},
"typographic_subfamily": {
"type": [
"string",
"null"
],
"description": "Typographic subfamily name when available, otherwise null."
},
"full_name": {
"type": "string",
"minLength": 1,
"description": "Human-readable full font face name."
},
"postscript_name": {
"type": "string",
"minLength": 1,
"description": "PostScript face name used for stable font identification."
},
"version_string": {
"type": "string",
"minLength": 1,
"description": "Version string extracted from the font metadata."
},
"unique_font_id": {
"type": "string",
"minLength": 1,
"description": "Deterministic Fontshow identifier for the font face."
},
"metrics": {
"$ref": "#/$defs/metrics",
"description": "Normalized technical metrics and numeric font properties."
},
"coverage": {
"type": "object",
"additionalProperties": true,
"description": "Coverage and Unicode-derived enrichment data associated with the font."
},
"inference": {
"type": "object",
"additionalProperties": true,
"description": "Inference outputs derived from coverage, charset, and language processing."
},
"charset": {
"type": "object",
"additionalProperties": true,
"description": "Charset-oriented raw or normalized data retained for downstream analysis."
},
"typography": {
"$ref": "#/$defs/typography",
"description": "Typography-oriented rendering metadata, specimens, and render-policy fields."
},
"loadability": {
"$ref": "#/$defs/loadability",
"description": "Per-font persisted loadability state for external rendering engines."
},
"warnings": {
"type": "array",
"description": "Structured warnings attached to the font entry during inventory generation or enrichment.",
"items": {
"$ref": "#/$defs/warning"
}
}
}
},
"metrics": {
"type": "object",
"description": "Normalized numeric metrics and technical font properties used for diagnostics and downstream policy decisions.",
"required": [
"units_per_em",
"ascent",
"descent",
"weight_class",
"width_class",
"italic_angle",
"is_fixed_pitch",
"glyph_count"
],
"additionalProperties": false,
"properties": {
"units_per_em": {
"type": "integer",
"minimum": 1,
"description": "Units-per-em value reported by the font."
},
"ascent": {
"type": "integer",
"description": "Ascent metric reported by the font."
},
"descent": {
"type": "integer",
"description": "Descent metric reported by the font."
},
"weight_class": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Normalized OS/2 weight class value."
},
"width_class": {
"type": "integer",
"minimum": 1,
"maximum": 9,
"description": "Normalized OS/2 width class value."
},
"italic_angle": {
"type": "number",
"description": "Italic angle reported by the font."
},
"is_fixed_pitch": {
"type": "boolean",
"description": "Whether the font is reported as fixed-pitch or monospaced."
},
"glyph_count": {
"type": "integer",
"minimum": 1,
"description": "Number of glyphs reported by the font."
}
}
},
"typography": {
"type": "object",
"description": "Typography-oriented fields used for specimen generation, script labeling, and render-policy selection.",
"required": [
"sample_text",
"specimen_text",
"specimen_strategy",
"specimen_glyph_count",
"primary_script",
"script_display_name",
"render_policy",
"script_source"
],
"additionalProperties": false,
"properties": {
"sample_text": {
"type": "object",
"description": "Embedded sample text extracted from the font itself.",
"required": [
"source",
"text"
],
"additionalProperties": false,
"properties": {
"source": {
"type": "string",
"const": "font",
"description": "Provenance label for the embedded sample text."
},
"text": {
"type": "string",
"description": "Sample text extracted from the font, which may be empty when no embedded sample is available."
}
}
},
"specimen_text": {
"type": "string",
"minLength": 1,
"description": "Final deterministic specimen text chosen for rendering and validation."
},
"specimen_strategy": {
"type": "string",
"description": "Strategy that produced the final specimen text.",
"enum": [
"internal",
"script",
"cmap",
"deferred",
"validated-language-sample",
"validated-fallback"
]
},
"specimen_glyph_count": {
"type": [
"integer",
"null"
],
"minimum": 1,
"description": "Count of accepted base glyphs in the final specimen text."
},
"specimen_rejection_reason": {
"type": [
"string",
"null"
],
"description": "Structured rejection or fallback reason recorded during specimen generation."
},
"primary_script": {
"type": [
"string",
"null"
],
"description": "Primary script code selected for the font, when one is available."
},
"script_display_name": {
"type": [
"string",
"null"
],
"description": "Human-readable display label associated with the primary script."
},
"render_policy": {
"type": "object",
"description": "LaTeX-oriented render-policy values derived from the selected script.",
"required": [
"polyglossia_language",
"fontspec_opts"
],
"additionalProperties": false,
"properties": {
"polyglossia_language": {
"type": [
"string",
"null"
],
"description": "Polyglossia language identifier associated with the selected script, when applicable."
},
"fontspec_opts": {
"type": [
"string",
"null"
],
"description": "fontspec option fragment associated with the selected script, when applicable."
}
}
},
"script_source": {
"type": [
"string",
"null"
],
"description": "Source from which the primary script decision was derived."
},
"opentype_features": {
"type": "array",
"description": "Reported OpenType feature tags preserved for typography-oriented inspection.",
"items": {
"type": "string"
}
}
}
},
"loadability": {
"type": "object",
"description": "Per-font persisted loadability state for external engines that may reject or constrain rendering.",
"required": [
"lualatex"
],
"additionalProperties": false,
"properties": {
"lualatex": {
"type": "object",
"description": "Persisted LuaLaTeX loadability result for the current font entry.",
"required": [
"attempted",
"loadable",
"reason",
"runtime_fingerprint",
"probe_input"
],
"additionalProperties": false,
"properties": {
"attempted": {
"type": "boolean",
"description": "Whether LuaLaTeX loadability probing has been attempted for this font."
},
"loadable": {
"type": [
"boolean",
"null"
],
"description": "Persisted LuaLaTeX loadability result when probing has produced a definitive outcome."
},
"reason": {
"type": [
"string",
"null"
],
"description": "Deterministic short reason or failure summary associated with the persisted loadability state."
},
"runtime_fingerprint": {
"type": [
"string",
"null"
],
"description": "Runtime fingerprint under which the per-font loadability result was computed."
},
"probe_input": {
"type": [
"string",
"null"
],
"description": "Serialized probe input or probe-selection hint associated with the persisted validation attempt."
}
}
}
}
},
"lualatex_validation_metadata": {
"type": "object",
"description": "Inventory-level metadata describing the LuaLaTeX-related program surface used for validation and loadability decisions.",
"required": [
"attempted",
"engine",
"engine_version",
"luaotfload_version",
"fontspec_version",
"polyglossia_version",
"runtime_fingerprint",
"render_policy_version"
],
"additionalProperties": false,
"properties": {
"attempted": {
"type": "boolean",
"description": "Whether inventory-wide LuaLaTeX validation or probing has been attempted."
},
"engine": {
"type": [
"string",
"null"
],
"description": "Name of the LaTeX engine associated with the validation metadata."
},
"engine_version": {
"type": [
"string",
"null"
],
"description": "Version string reported by the LaTeX engine."
},
"luaotfload_version": {
"type": [
"string",
"null"
],
"description": "Version of the luaotfload package available in the associated LaTeX runtime."
},
"fontspec_version": {
"type": [
"string",
"null"
],
"description": "Version of the fontspec package available in the associated LaTeX runtime."
},
"polyglossia_version": {
"type": [
"string",
"null"
],
"description": "Version of the Polyglossia package available in the associated LaTeX runtime."
},
"runtime_fingerprint": {
"type": [
"string",
"null"
],
"description": "Stable fingerprint of the relevant LaTeX runtime surface."
},
"render_policy_version": {
"type": [
"string",
"null"
],
"description": "Version or fingerprint of the render-policy inputs associated with validation."
}
}
},
"warning": {
"type": "object",
"description": "Structured warning record attached to an inventory font entry.",
"required": [
"code",
"message",
"severity"
],
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"minLength": 1,
"description": "Machine-readable warning code."
},
"message": {
"type": "string",
"minLength": 1,
"description": "Human-readable warning message."
},
"severity": {
"type": "string",
"enum": [
"info",
"warning",
"error"
],
"description": "Normalized warning severity."
}
}
}
}
}
Related¶
docs/schema/index.mdsrc/fontshow/schema/inventory_v1_3.json