Core Concepts

Core Concepts

Lexicon is easiest to use when the vocabulary model is clear. The same words appear in the parser, CLI, generator, runtime, and language server.

Document

A document is parsed source. It can contain:

• document notes and comments
• document-level imports
• one or more roots
• nodes
• type references
• synonyms
• default values

A document can be valid even when it has more than one root. Code generation normally works from one selected root after imports have been composed.

Graph

A graph is one selected root tree from a document. A document can contain many roots; a graph has one root.

Graph-level work is useful when you want to generate source for one vocabulary surface, export a branch, or inspect the resolved tree beneath one root.

Lexicon

A Lexicon is the resolved object graph. It indexes lemmas by stable dot-path IDs and resolves:

• own children
• inherited children from types
• synonyms
• default values
• source versus inherited nodes

Application code should prefer generated accessors over raw string lookup where possible.

Lemma

A lemma is a semantic node. Its full ID is its dot path:

commerce.ui.checkout.button.primary

A lemma knows its name, parent, own children, inherited children, type references, synonyms, defaults, notes, comments, and source.

Type

A type reference is written with +:

submit:
	+ commerce.type.boolean

Types provide inherited children and semantic membership. If commerce.api.order.submit is typed as commerce.type.boolean, generated and runtime code can treat the submit capability as a boolean-like concept.

Types are not only primitive data types. They can represent UX actions, UI controls, analytics event families, persistence ownership, operational status, or any domain class that should be reused.

Synonym

A synonym is written with =:

enabled:
active:
	= enabled

The synonym preserves a local dialect while pointing to another lemma. References are resolved relative to the parent when possible, so = enabled under buy resolves to buy.enabled.

Use synonyms when two teams need different words for the same concept. Do not use them to hide a naming disagreement that needs a product decision.

Default Value

A literal default is written with ?:

status:
	+ commerce.type.string
	? "open"

enabled:
	+ commerce.type.boolean
	? true

Lexicon supports JSON literals: strings, numbers, booleans, arrays, objects, and null.

A default can also be a reference:

selected:
	? @ commerce.ui.checkout.button.primary

Import

An import is written with @:

@ ./shared-commerce.lexicon

commerce:
	api:
		@ ./storefront-api.lexicon

Document-level imports compose with the root. Node-level imports graft an external vocabulary at that point.

See Composition and Imports for the rules and project layout patterns.

Note

A note is written with >:

> Used by support agents when an order needs human review.

Notes are domain-facing prose. They explain vocabulary to readers and can be surfaced in generated JSON metadata.

Comment

A comment is written with #:

# Keep this spelling aligned with the existing analytics event.

Comments are authoring/tooling annotations. They are preserved by the document model, CLI, and CRDT layers.

Own versus Resolved

Own structure is what the source document declares directly. Resolved structure includes inherited children, synonym resolution, composed imports, and default fallback behavior.

When debugging a vocabulary:

• Use lexicon tree without --inherited to see only declared structure.
• Use lexicon tree --inherited to see the live shape a generated accessor or runtime lookup will observe.
• Use lexicon inspect when you need source, type, default, note, comment, and child details for one lemma.