Schemas

Reference#

Every schema lives in schemas/ at the repository root and uses JSON Schema draft 2020-12. Each schema carries an $id that equals its published URL, so the copy at https://litespec.dev/4.0.0/schemas/<file> and the file in schemas/ state the same contract. The validate and model pages state the commands that check each file. The release ships seven schemas, one per section below.

Manifest Schema#

The top-level properties name the release and what it ships. schemaVersion is the constant 5. version is the release, such as 4.0.0. name and agentsEntry name the standard and its agent entry point. stacks, shapes, and extensions list what a consumer project selects from. stack and packages pin the tool versions. uiBaseline and uiBaselineSvelte pin the controlled UI presets.

The release manifest opens with these fields:

{
  "$schema": "./schemas/litespec-manifest.schema.json",
  "schemaVersion": 5,
  "version": "4.0.0",
  "name": "litespec",
  "agentsEntry": "AGENTS.md"
}

Consumer Project Schema#

The top-level properties describe the project. project holds the project name. size is small or large. shape is server or client-only. stacks lists the selected stacks. reviewedLiteSpecVersion records the LiteSpec release the project last reviewed. paths locates the specification tree, the glossary, the UI package, and the frontends. stackConfig holds per-stack configuration, such as the .NET backend paths. selectedExtensions lists the active extensions with their criterion. refusals names the codes the derived generic results carry. marks, proof, dependencies, and screenshots carry further project choices. The project file states every field.

The consumer template opens with these fields:

{
  "$schema": "https://litespec.dev/4.0.0/schemas/litespec-project.schema.json",
  "project": { "name": "__PROJECT__" },
  "size": "small",
  "shape": "server",
  "stacks": ["dotnet", "react"],
  "reviewedLiteSpecVersion": "4.0.0"
}

Record Schema#

The schema holds no single property list. Instead it carries a oneOf across 36 page variants, one per record type and page style, so each record file and each document frontmatter matches exactly one variant: productPage, goalPage, constraintPage, researchPage, decisionPage, problemPage, featurePage, actorPage, rolePage, journeyPage, modulePage, aggregatePage, useCasePage, reactionPage, jobPage, notificationPage, externalSystemPage, integrationEventPage, runbookPage, exceptionPage, permissionListPage, entryPointPage, entryPointListPage, screenPage, settingPage, settingSetPage, ruleSetPage, retentionSchedulePage, indexPage, tutorialPage, howToPage, referencePage, commandPage, configurationPage, glossaryPage, and exampleCastPage. Each variant requires type plus its own fields, such as id and title. A record present in git is decided; no variant carries approval, status, or history fields.

A list page carries its entries in records: requirement, permission, rule, result, scenario, event, entry-point, and setting entries. The identifier patterns sit beside the variants in $defs, such as useCaseId for use-case/<module>.<name>, reactionId for reaction/<module>.<name>, jobId for job/<module>.<name>, notificationId, settingId, integrationEventId, journeyStepId for journey/<name>#s1, and derivedResultId for the derived generic results. Shared shapes sit there too: the access object with grant and tenant, the query output groups, paging, consistency, effectEntry with exactly one verb of runs, sends, emits, or calls, the reaction trigger, the job kind and schedule, idempotency, audit, the one onFailure shape, and dataClassEntry.

A use case page requires kind, which is command or query, and the access object, and its record file holds these fields. The entry point the use case is reached through states the caller auth; the use case states only grant and tenant:

{
  "type": "use-case",
  "id": "use-case/<module>.<name>",
  "title": "<Use case display title>",
  "kind": "command",
  "access": { "grant": "permission/<name>", "tenant": "own" }
}

Glossary Schema#

The top-level properties hold the closed vocabulary. schemaVersion is the constant 2. terms holds one entry per concept, each with its id, term, meaning, layer of intent or behavior, aliases naming the established synonyms, labels, rejected synonyms, broader and narrower terms, and closed-set values. mannered holds the metaphor terms the project rejects everywhere, each with its term and its instead.

The consumer glossary template carries real mannered entries:

"mannered": [
  { "term": "load-bearing", "instead": "required" },
  { "term": "one-way door", "instead": "irreversible" }
]

Design Contract Schema#

The top-level properties bind the contract to its package. kind is the constant design-contract. schemaVersion is the constant 1. package names the shared UI package. profile names the density the worked example uses. shell names the application shell. patterns lists the floorplans the package provides.

The consumer template opens its design contract with these fields:

{
  "kind": "design-contract",
  "schemaVersion": 1,
  "package": "@__PROJECT__/ui",
  "profile": "application-balanced",
  "shell": "application-shell/default",
  "patterns": ["list-page", "entity-page"]
}

UI Pattern Catalog Schema#

The top-level properties hold one decision per recurring UI question. kind is the constant ui-pattern-catalog. schemaVersion is the constant 1. registry names the command that renders every option for visual review. breakpoints names the viewport widths in CSS pixels. groups holds the catalog groups. patterns holds the decisions, each with its options, chosen decision, compact behavior, and per-platform implementations.

The consumer template catalog opens with these fields:

{
  "$schema": "https://litespec.dev/4.0.0/schemas/ui-pattern-catalog.schema.json",
  "kind": "ui-pattern-catalog",
  "schemaVersion": 1,
  "breakpoints": { "compact": 768 }
}

UI Source Lock Schema#

The top-level properties pin what was installed. schemaVersion is the constant 1. generator is shadcn/ui or shadcn-svelte. cli is the pinned CLI version. preset repeats the manifest baseline the package installs. registry names where the source came from. formatter names the code formatter. components lists every installed primitive with its name, address, status, paths, digest, and dependencies.

The consumer template lock opens with these fields:

{
  "$schema": "https://litespec.dev/4.0.0/schemas/ui-source-lock.schema.json",
  "schemaVersion": 1,
  "generator": "shadcn/ui",
  "cli": "4.21.5"
}

Notes#

A schema states one exact shape per release, with no compatible range between releases. A consumer adopting a later release absorbs every difference at that moment, under litespec/core/authoring#publish-each-release-as-a-complete-contract and litespec/core/authoring#exclude-cross-release-compatibility-work. When the published copy and the repository copy disagree, the repository copy wins, because every check reads schemas/ from the checkout its tool belongs to.