# Overview

Asterdoc schema reference

Canonical URL: https://docs.asterdoc.com/schemas/

Asterdoc is built on JSON Schema standard [Draft 2020-12](https://json-schema.org/specification).

The schemas define the JSON shape of an artifact. To build the same artifacts in TypeScript, see the [SDK reference](/sdk).

## 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`:

```json
{
  "$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`](/cli/commands/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`:

| `$schema`                                                                 | Result                                |
| ------------------------------------------------------------------------- | ------------------------------------- |
| The current version                                                       | Loads and validates as usual.         |
| An earlier version                                                        | Fails with an outdated-version error. |
| Missing                                                                   | Fails with a missing-version error.   |
| An unpublished date, the undated `schema.json`, or a non-Asterdoc address | Fails with an unknown-version error.  |

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`](/cli/commands/migrate) accepts another version.

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

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

### Version history

| Version      | Changes                                                                                                                                                                                                                                                                              |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `2026-10-28` | First Asterdoc version. It has the same shape as Paradoc's `2026-10-02` at `schema.paradoc.dev`. To move a Paradoc artifact to it, bring the artifact to `2026-10-02` with Paradoc 0.8 if it is older, then run `asterdoc migrate <file> --from 2026-10-28`. Only `$schema` changes. |

## Hosted server

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

| Schema           | URL                                                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Versioned bundle | `https://schema.asterdoc.com/2026-10-28.json`                                                                          |
| Individual items | `https://schema.asterdoc.com/2026-10-28/form.json`, `bundle.json`, `checklist.json`, `document.json`                   |
| Latest bundle    | `https://schema.asterdoc.com/schema.json`, for editors. It names no version, so an artifact file uses a dated address. |

## Package dependency

**Installation**

**npm**

```bash
npm install @asterdoc/schemas
```

**pnpm**

```bash
pnpm add @asterdoc/schemas
```

**yarn**

```bash
yarn add @asterdoc/schemas
```

**bun**

```bash
bun add @asterdoc/schemas
```

**Usage**

```typescript
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:

| Category                          | Description                                                                                    |
| --------------------------------- | ---------------------------------------------------------------------------------------------- |
| [Artifacts](/schemas/artifacts)   | Top-level artifact types that define document structures.                                      |
| [Primitives](/schemas/primitives) | Low-level types for representing common data types like addresses, monetary amounts, and more. |