Language JSON and SKOS JSON LD

JSON and SKOS JSON-LD

Lexicon can emit two interchange formats:

• json for the resolved classes and mixins snapshot used by generators and tools.
• json-ld for SKOS JSON-LD.

Generate JSON

swift run lexicon-generate commerce.lexicon --type json -o build/commerce

This writes:

build/commerce.json

Use it when another tool wants the resolved graph without linking Swift code.

Common consumers:

• documentation sites
• search indexes
• validation dashboards
• ontology review tools
• code generators outside this package

JSON Shape

The JSON snapshot contains the root name, generation date, classes, children, synonyms, defaults, and notes. A class entry represents a resolved lemma.

Use exact IDs as stable keys:

{
  "id": "commerce.ui.checkout.button.primary",
  "name": "primary"
}

Do not depend on array ordering unless a consuming tool explicitly sorts entries.

Generate SKOS JSON-LD

swift run lexicon-generate commerce.lexicon --type json-ld -o build/commerce

This writes:

build/commerce.jsonld

Use JSON-LD when the lexicon should be read by ontology, knowledge-graph, or documentation systems.

What SKOS Output Is For

SKOS JSON-LD is useful when:

• domain terms need stable concept URIs
• synonyms should be visible to knowledge tools
• product language should be browsable outside source code
• terms from different teams need a shared concept graph

It is not a replacement for generated source in application code. Use language generators when compile-time accessors matter.

Pipeline Example

mkdir -p build/lexicon

swift run lexicon lint lexicons/commerce.lexicon
swift run lexicon-generate lexicons/commerce.lexicon --type json -o build/lexicon/commerce
swift run lexicon-generate lexicons/commerce.lexicon --type json-ld -o build/lexicon/commerce

Then publish:

build/lexicon/commerce.json
build/lexicon/commerce.jsonld

Review Workflow

For non-engineering review, JSON-LD often pairs well with generated documentation:

1. Authors edit .lexicon files.
2. CI runs lexicon lint.
3. CI generates json and json-ld.
4. A docs job renders the graph into pages or a concept browser.
5. Reviewers discuss vocabulary changes from concepts, references, and synonyms instead of source formatting.