Quick Start

Quick Start

This page takes a new project from an empty file to validated vocabulary, generated source, and editor diagnostics.

1. Install the package tools

Lexicon is a Swift package. The current package declares Swift 6.3, Swift language mode 6, macOS 15, and iOS 18.

git clone https://github.com/ollieatkinson/Lexicon.git
cd Lexicon
swift build --product lexicon
swift build --product lexicon-generate
swift build --product lexicon-lsp

During local development you can run tools through SwiftPM:

swift run lexicon --help
swift run lexicon-generate --help
swift run lexicon-lsp --help

For editor integrations, build a release language server and put it on PATH:

swift build -c release --product lexicon-lsp
cp .build/release/lexicon-lsp /usr/local/bin/lexicon-lsp

If you do not want to copy the binary, configure your editor with the absolute path to .build/release/lexicon-lsp.

2. Create a lexicon

Create commerce.lexicon. Indentation is significant and uses tabs.

# Shared commerce vocabulary.
> API, UI, analytics, and support can keep local words while sharing meaning.

commerce:
	type:
		boolean:
		string:
	api:
		order:
			submit:
			+ commerce.type.boolean
			? true
	ui:
		checkout:
			button:
				primary:
				+ commerce.api.order.submit
	analytics:
		event:
			checkout_started:
			+ commerce.ui.checkout.button.primary
	support:
		ticket:
			status:
			+ commerce.type.string
			? "open"

This says:

• commerce.api.order.submit is a boolean capability.
• commerce.ui.checkout.button.primary is typed by the API submit capability.
• commerce.analytics.event.checkout_started is connected to the UI button concept.
• commerce.support.ticket.status has a default string value.
• Notes use > and are intended for readers of the vocabulary.
• Comments use # and are authoring/tooling annotations.

3. Validate and inspect it

swift run lexicon validate commerce.lexicon
swift run lexicon lint commerce.lexicon
swift run lexicon inspect commerce.lexicon commerce.ui.checkout.button.primary
swift run lexicon tree commerce.lexicon commerce --depth 4 --metadata

Validation and inspection commands print structured JSON so scripts and editor tooling can consume the output.

4. Search it

swift run lexicon search commerce.lexicon submit button --mode hybrid --limit 5
swift run lexicon search commerce.lexicon support status --mode token --limit 5
swift run lexicon refs commerce.lexicon commerce.ui.checkout.button.primary

Use hybrid as the default search mode. Use token when you are looking for exact-ish path/name matches.

5. Generate source

Generate one target at a time when two targets share an extension. For example, swift and swift-standalone both emit .swift.

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

The -o/--output value is a path without the final extension. Lexicon appends the generator extension, such as .swift, .go, .rs, .ts, .json, or .jsonld.

6. Add project LSP configuration

Create lexicon-lsp.json at the workspace root:

{
  "lexicon": "commerce.lexicon"
}

The language server composes imports and indexes the live graph. It then provides completions and unknown-path diagnostics for:

• Lexicon document references, such as + commerce.type.boolean.
• Go exact-path calls, such as l("commerce.api.order.submit").
• Rust exact-path macros, such as l!(commerce.api.order.submit).

See Editor Support for editor-specific setup.

7. Add the package to another Swift project

.package(
	url: "https://github.com/ollieatkinson/Lexicon.git",
	branch: "trunk"
)

Then depend on the products you need:

.product(name: "Lexicon", package: "Lexicon")
.product(name: "SwiftLexicon", package: "Lexicon")
.product(name: "LexiconGenerators", package: "Lexicon")

Use Lexicon to parse, compose, inspect, and edit documents. Use SwiftLexicon when your generated Swift source depends on the shared runtime. Use LexiconGenerators when you are integrating generation into your own tool.