Next: Health checks, Previous: Command reference, Up: Manual

6. JSON output and schemas

machine-readable output, the three JSON Schemas, and stability guarantees.

Every reporting command takes --json and then prints exactly one JSON document to standard output. Human-readable output is not stable and not meant to be parsed; JSON output is.

The three schemas

The schemas are JSON Schema draft 2020-12, generated from the Rust types and checked in to schemas/. Continuous integration fails if they drift from the code.

face.json: The metadata of one face: the document that info --json prints and that the index stores. Its top-level type is FaceMetadata and it carries a schema_version.
collection.json: The file that collection export writes and collection import reads: a name, an ordered list of faces identified by identity hash, PostScript name and path, so that it survives a move to another machine.
cli-output.json: One definition per command's --json output type, so a consumer can validate list, facets, check, dupes, stats and the rest.

Print any of them from the binary you have, which is always the right version:

fontina schema face
fontina schema collection
fontina schema cli-output

Stability

Fields are added, not removed or renamed, within a schema version.
A change that is not backwards compatible bumps schema_version in face.json and is called out in the changelog.
Health check identifiers (area/check) are never renamed. New ones may appear.
Face ids are stable for the life of a file in the index. They are not stable across indexes; use the identity hash or the PostScript name for that.

Examples

Ids of every variable font, for a shell loop:

fontina list --variable --json | jq -r '.[].id'

Families that cover Devanagari, with the number of faces in each:

fontina families --script Deva --json | jq -r '.[] | "\(.family)\t\(.faces | length)"'

Fail a script if any font forbids embedding:

fontina license --json | jq -e 'all(.[]; .embedding.level != "restricted_license")'

Validate a collection file before importing it:

fontina schema collection > collection.schema.json
check-jsonschema --schemafile collection.schema.json editorial.json

The stored metadata

The index stores the complete FaceMetadata document for each face, as JSON, beside the columns it indexes for filtering. info --json returns that document unchanged. Anything a future filter needs is therefore already on disk; a migration backfills the column from the JSON rather than rescanning.

Next: Health checks, Previous: Command reference, Up: Manual