OverviewLast updated on
Last updated on
Paradoc schema reference
Paradoc 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-02.
Every artifact file names the version it follows in $schema:
{
"$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 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 accepts another version.
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 install @paradoc/schemasUsage
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 | Top-level artifact types that define document structures. |
| Primitives | Low-level types for representing common data types like addresses, monetary amounts, and more. |