Document Syntax

Document Syntax

Lexicon documents use a compact TaskPaper-like format. Indentation is significant and uses tabs.

Syntax Summary

Syntax	Meaning
name:	Defines a lemma. Its full ID is its dot path, such as commerce.ui.product.card.
+ commerce.type.string	Adds a type reference. Types provide inherited children and default fallbacks.
= enabled	Makes a lemma a synonym of another lemma, resolved relative to the parent when possible.
? true	Sets a literal JSON default. Strings, numbers, booleans, arrays, objects, and null are supported.
? @ commerce.some.default	Sets a default by reference.
@ ./shared.lexicon	Imports another lexicon. At document level it composes with the root; inside a node it grafts there.
> note	Adds a domain-facing note to the current document or node.
# comment	Adds an authoring/tooling comment to the current document or node.

Names must start with a letter and may contain letters, digits, and underscores.

Minimal Document

commerce:
	product:
		card:

The IDs are:

• commerce
• commerce.product
• commerce.product.card

Types

commerce:
	type:
		string:
		boolean:
	api:
		product:
			title:
			+ commerce.type.string
			is:
				eligible:
				+ commerce.type.boolean

Type references let a lemma inherit child structure and communicate semantic membership. A node may have more than one type:

primary:
	action:
	+ commerce.ui.type.button.primary
	+ commerce.ux.type.action

Synonyms

buy:
	enabled:
	+ commerce.api.order.create.can.submit
	active:
	= enabled

active is a synonym for enabled under the same parent. This is useful when one surface says "enabled" and another says "active" but both point to the same concept.

Defaults

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

is:
	eligible:
	+ commerce.type.boolean
	? true

metadata:
	? { "source": "checkout", "version": 1 }

Defaults are JSON values. Quote string defaults, but do not quote booleans, numbers, arrays, objects, or null.

Reference defaults use ? @:

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

Notes and Comments

# Maintainer note: keep this aligned with the analytics event registry.
> The user has started the checkout flow.
checkout_started:
	+ commerce.analytics.type.event

Use notes for vocabulary readers. Use comments for maintainers, generation hints, or source-document history.

Imports

@ ./shared-commerce.lexicon

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

Document-level imports are composed with the root. Node-level imports are grafted at the node where the import appears.

Multiple Roots

commerce:
	product:

support:
	case:
	+ commerce.product

A document can contain multiple roots. When generating source or building a graph, pick the root you want to expose.

Imports can collapse multiple roots into one composed graph when the imported roots are grafted under a selected root. See Composition and Imports.

Tabs Matter

Spaces in leading indentation are ignored for hierarchy. The language server diagnoses leading spaces because they usually mean the author expected nesting that the parser will not see.

Use editor settings that insert hard tabs for .lexicon files.