# Overview

Paradoc schema reference

Canonical URL: https://docs.paradoc.dev/schemas/

Paradoc 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-02`.

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

```json
{
  "$schema": "https://schema.paradoc.dev/2026-10-02.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 [`paradoc 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 `paradoc 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-Paradoc address | Fails with an unknown-version error.  |

Each error names what it found and the current version, and points to `paradoc 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()`, `p.form()`, `p.document()`, `p.checklist()` and `p.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 '@paradoc/sdk'

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

### Version history

Before 1.0, the package and hosted schema service contain only the current dated schema set. Superseded prerelease schemas remain available through repository history, but they are not a supported package or hosted-service surface. Migration support is separate: `paradoc migrate` continues to recognize the versions listed below.

| Version      | Changes                                                                                                                                                                                                                                                                                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `2026-10-02` | An artifact can name its issuer (`issuer`) and the issuer's edition it encodes (`edition`: `key`, `label`, `date`, `effectiveFrom`). `releaseDate` is removed. A registry bundle item names its artifact by address (`@org/repo/name`) with optional `edition` and `version`. `paradoc migrate` removes `releaseDate` and moves a slug's `@version` into `version`. |
| `2026-09-24` | A layer declares signature slots only in `signatures`: `signatureBlocks` and `anchorBlocks` are removed. `paradoc migrate` moves each block into `signatures` under the same id, with the block type `date` renamed `date_signed`.                                                                                                                                  |
| `2026-09-23` | Only a PDF file layer takes `bindings` and `bindingsFrom`. A binding maps an AcroForm field name (key) to a Paradoc path (value), and a key fits a fully qualified AcroForm name (up to 500 characters).                                                                                                                                                            |
| `2026-09-22` | Signature placement `'auto'` is renamed `'flow'`. An inline layer cannot hold a React composition (`text/tsx`, `text/jsx`). A duration needs at least one date or time component.                                                                                                                                                                                   |
| `2026-08-10` | Adds the layer `signatures` slot map.                                                                                                                                                                                                                                                                                                                               |
| `2026-08-06` | Adds list fields.                                                                                                                                                                                                                                                                                                                                                   |
| `2026-01-01` | First published version.                                                                                                                                                                                                                                                                                                                                            |

## Hosted server

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

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

## Package dependency

**Installation**

**npm**

```bash
npm install @paradoc/schemas
```

**pnpm**

```bash
pnpm add @paradoc/schemas
```

**yarn**

```bash
yarn add @paradoc/schemas
```

**bun**

```bash
bun add @paradoc/schemas
```

**Usage**

```typescript
import bundledSchema from '@paradoc/schemas/schema.json'
import { SCHEMA_VERSION, PARADOC_SCHEMA_URL, readSchemaAddress } from '@paradoc/schemas'

SCHEMA_VERSION // '2026-10-02'
PARADOC_SCHEMA_URL // 'https://schema.paradoc.dev/2026-10-02.json'
readSchemaAddress('https://schema.paradoc.dev/2026-09-24.json') // { kind: 'known', version: '2026-09-24' }
```

## Schema Reference

The Paradoc 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. |