Example Commerce Vocabulary

Commerce Example

This example keeps database, API, session, UI, UX, and support terms separate while still letting them refer to each other.

It demonstrates:

• document metadata
• multiple roots
• document-level imports
• node-level imports
• type references
• synonyms
• literal defaults
• notes and comments
• composition into one generated root

File Layout

lexicons/
  commerce.lexicon
  shared-commerce.lexicon
  data-types.lexicon
  storefront-api.lexicon
  product-ui.lexicon
lexicon-lsp.json

commerce.lexicon

# Commerce language shared by API, UI, session and product surfaces.
> Product teams can add local dialects without replacing the shared vocabulary.
@ ./shared-commerce.lexicon

commerce:
# The main application vocabulary.
> Terms under this root are composed into generated platform code.
	db:
	@ ./data-types.lexicon
	session:
	# Runtime ownership is separate from API and UI ownership.
		configuration:
			value:
		state:
			value:
			shared:
				value:
				+ commerce.session.state.value
			stored:
				value:
				+ commerce.session.state.value
	api:
		storefront:
		@ ./storefront-api.lexicon
	ui:
		product:
		@ ./product-ui.lexicon
	ux:
		onboarding:
			choose:
				product:
				+ commerce.ux.type.story
					confirm:
					+ commerce.ux.type.task
support:
# A second root can still reference the commerce vocabulary.
	case:
	+ commerce.db.collection
		status:
		+ commerce.db.type.string
		? "open"

shared-commerce.lexicon

commerce:
	db:
		collection:
			id:
			+ commerce.db.type.string
		leaf:
	session:
		configuration:
			value:
		state:
			value:
			shared:
				value:
				+ commerce.session.state.value
			stored:
				value:
				+ commerce.session.state.value
	ui:
		type:
		> Reusable controls are deliberately small; product screens compose them.
			control:
			label:
			card:
			+ commerce.ui.type.control
			button:
				primary:
				+ commerce.ui.type.control
				secondary:
				+ commerce.ui.type.control
	ux:
		type:
			action:
			story:
			task:

data-types.lexicon

db:
	type:
		any:
		+ commerce.db.leaf
		boolean:
		+ commerce.db.leaf
		string:
		+ commerce.db.leaf
		tag:
		+ commerce.db.leaf

storefront-api.lexicon

storefront:
	products:
	+ commerce.db.collection
		product:
		+ commerce.db.collection
			id:
			+ commerce.db.type.string
			title:
			+ commerce.db.type.string
			is:
				eligible:
				+ commerce.db.type.boolean
				+ commerce.session.state.value
			ineligible:
				reason:
				+ commerce.db.type.string
	order:
		create:
		+ commerce.ux.type.task
			can:
				submit:
				+ commerce.db.type.boolean
				+ commerce.session.configuration.value
			primary:
				action:
				+ commerce.ui.type.button.primary
				+ commerce.ux.type.action

product-ui.lexicon

product:
	card:
	+ commerce.ui.type.card
		title:
		+ commerce.ui.type.label
		buy:
		+ commerce.ui.type.button.primary
		+ commerce.ux.type.action
		# UI says enabled; analytics may say active.
			enabled:
			+ commerce.api.storefront.order.create.can.submit
			? true
			active:
			= enabled

Project Configuration

{
  "lexicon": "lexicons/commerce.lexicon"
}

Save this as lexicon-lsp.json at the repository root.

Validate and Inspect

swift run lexicon validate lexicons/commerce.lexicon
swift run lexicon lint lexicons/commerce.lexicon
swift run lexicon inspect lexicons/commerce.lexicon commerce.ui.product.card.buy.enabled
swift run lexicon tree lexicons/commerce.lexicon commerce --depth 5 --inherited --metadata

Important facts after composition:

• commerce.api.storefront.products.product is a collection-backed API concept.
• commerce.api.storefront.products.product.is.eligible is both a boolean and a session value.
• commerce.api.storefront.order.create.primary.action is both a UI primary button and a UX action.
• commerce.ui.product.card.buy.enabled is typed by the API/session submit capability.
• commerce.ui.product.card.buy.active is a synonym for enabled, preserving a local UI dialect.
• support.case.status is composed under the commerce root and has default value "open".

Generate Code

swift run lexicon-generate lexicons/commerce.lexicon --type swift -o Generated/Commerce
swift run lexicon-generate lexicons/commerce.lexicon --type go --go-package commerce -o Generated/commerce
swift run lexicon-generate lexicons/commerce.lexicon --type rust -o Generated/commerce
swift run lexicon-generate lexicons/commerce.lexicon --type ts -o Generated/commerce
swift run lexicon-generate lexicons/commerce.lexicon --type json,json-ld -o Generated/commerce

Generated Swift:

import SwiftLexicon

let submit = commerce.api.storefront.order.create.can.submit
let enabled = commerce.ui.product.card.buy.enabled
let active = commerce.ui.product.card.buy.active

print(submit.__)
print(enabled == active)

Generated Go:

submit := commerce.Commerce.Api.Storefront.Order.Create.Can.Submit
fmt.Println(submit.ID())
fmt.Println(l("commerce.ui.product.card.buy.enabled").ID())

Generated Rust:

let submit = lexicon::l!(commerce.api.storefront.order.create.can.submit);
let enabled = lexicon::l().commerce().ui().product().card().buy().enabled();

assert_eq!(submit.id(), "commerce.api.storefront.order.create.can.submit");
assert_eq!(enabled.id(), "commerce.ui.product.card.buy.enabled");

Generated TypeScript:

const submit = commerce.api.storefront.order.create.can.submit;
const enabled = commerce.ui.product.card.buy.enabled;

console.log(submit.__);
console.log(enabled.__);

Why This Shape Works

The API, UI, session, UX, and support surfaces do not collapse into one model. They stay separate, but the references make shared meaning explicit.

That is the core Lexicon pattern:

• keep ownership local
• connect concepts deliberately
• generate stable accessors
• use search and editor tooling to make the connections discoverable