Overview

Last updated on

Asterdoc is built on JSON Schema standard Draft 2020-12.

The schemas define the JSON shape of an artifact. To build the same artifacts in TypeScript, see the SDK reference.

Installation

The schemas are available as a bundle and as individual schemas.

Schema versions

Each version of the artifact schema is identified by a date. The current version is 2026-10-28.

Every artifact file names the version it follows in $schema:

{
  "$schema": "https://schema.asterdoc.com/2026-10-28.json",
  "kind": "form",
  "name": "residential-lease"
}

Artifacts serialized with the SDK (toJSON() and toYAML()) always carry the current version's address. An artifact built with the SDK is always the current version.

A new dated version is created only for a breaking change: a change that some existing valid artifact no longer satisfies. An additive change keeps the current version. Each new version ships with a migration step from the version before it, and asterdoc migrate applies those steps to bring an older artifact file up to date. Nothing changes an artifact file's version without that command.

Loading rules

Every loading surface applies the same rules: the SDK, the CLI, the AI tools, and registry consumers such as asterdoc add. An artifact file, read from JSON or YAML, must carry $schema:

Each error names what it found and the current version, and points to asterdoc migrate. Loading never migrates.

In the SDK, load() and safeLoad() read file content and apply these rules; the error is a SchemaVersionError with a code of missing-version, outdated-version, or unknown-version. Every other way to create an artifact takes an object that may have been built in memory, so it accepts one without $schema, but a $schema it does carry must still be current: loadFromObject(), a.form(), a.document(), a.checklist() and a.bundle() with an object, their .from() and .safeFrom(), and the builder's .from(). validate() reports the same condition as an issue at $schema. A bundle holds each inline part to the rule too, and the error names the part. Only migrate accepts another version.

import { load, SchemaVersionError } from '@asterdoc/sdk'

try {
  load(fileContents)
} catch (error) {
  if (error instanceof SchemaVersionError) console.error(error.code, error.message)
}

Version history

Hosted server

The hosted service exposes the current prerelease schema set and the live root schemas.

Package dependency

Installation

npm install @asterdoc/schemas

Usage

import bundledSchema from '@asterdoc/schemas/schema.json'
import { SCHEMA_VERSION, ASTERDOC_SCHEMA_URL, readSchemaAddress } from '@asterdoc/schemas'

SCHEMA_VERSION // '2026-10-28'
ASTERDOC_SCHEMA_URL // 'https://schema.asterdoc.com/2026-10-28.json'
readSchemaAddress('https://schema.asterdoc.com/2026-10-28.json') // { kind: 'known', version: '2026-10-28' }

Schema Reference

The Asterdoc schemas are broken down into 2 categories: