# Form Schema

An artifact for dynamic documents with fields, annexes, and parties

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

A Form is the workhorse of Paradoc. It defines dynamic documents that can be populated at runtime with:

* data fields
* parties (including roles and signature/witness requirements)
* annexes (attachments that can be appended at runtime)

It can be used to create a simple consent form with a few fields to complex forms with multiple nested fields, annexes, signatory requirements, and conditional rendering logic.

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `$schema?` | `string` | Current dated schema URL. Required in artifact files and optional for in-memory objects |
| `kind` | `'form'` | Literal "form" discriminator |
| `name` | `string` | Unique identifier; must follow slug constraints |
| `version?` | `string` | Artifact version (semantic versioning) |
| `title?` | `string` | Human-friendly name presented to end users |
| `description?` | `string` | Long-form description or context |
| `code?` | `string` | The form number as printed by its issuer (e.g. W-9, ACORD 25), or a self-issued form's own number |
| `language?` | `string` | BCP 47-style source language tag. Defaults to en when omitted |
| `issuer?` | `string` | Organization that issues the form (e.g. U.S. Internal Revenue Service) |
| `edition?` | `Edition` | The issuer's edition this artifact encodes, for artifacts the issuer reissues. Every edition of one artifact shares the same name and has its own version line |
| `metadata?` | `Metadata` | Custom metadata map (keys must be alphanumeric with hyphens) |
| `instructions?` | `ContentRef` | Domain or compliance reference content (e.g., IRS instructions, regulatory guidance) |
| `agentInstructions?` | `ContentRef` | LLM/agent prompts for field ordering, grouping, tone, and presentation guidance |
| `defs?` | `DefsSection` | Named typed computed values that can be referenced in field/annex conditions |
| `rules?` | `RulesSection` | Form-level validation rules evaluated at fill time |
| `fields?` | `Record<string, FormField>` | Field definitions keyed by identifier |
| `layers?` | `Record<string, Layer>` | Named layers for rendering this form into different formats |
| `defaultLayer?` | `string` | Key of the default layer to use when none specified |
| `allowAdditionalAnnexes?` | `boolean` | Whether additional ad-hoc annexes can be attached beyond those defined in the annexes record |
| `annexes?` | `Record<string, FormAnnex>` | Predefined annex slots keyed by identifier |
| `parties?` | `Record<string, FormParty>` | Party role definitions keyed by role identifier, with constraints and signature requirements |

## Form Components

| Component                                  | Description                                        |
| ------------------------------------------ | -------------------------------------------------- |
| [FormField](/schemas/artifacts/form/field) | Field definitions for capturing user input         |
| [FormAnnex](/schemas/artifacts/form/annex) | Attachment slot definitions                        |
| [FormParty](/schemas/artifacts/form/party) | Party role definitions with signature requirements |

## Examples



**YAML**

```yaml
$schema: https://schema.paradoc.dev/2026-10-02.json
kind: form
name: lease-agreement
version: "1.0.0"
title: Residential Lease Agreement
description: Standard residential lease agreement

defs:
  hasPets:
    type: boolean
    value: "fields.petsAllowed == true"

fields:
  propertyAddress:
    type: address
    label: Property Address
    required: true
  monthlyRent:
    type: money
    label: Monthly Rent
    required: true
  leaseStart:
    type: date
    label: Lease Start Date
    required: true
  leaseTerm:
    type: enum
    label: Lease Term
    enum: [{ value: "12 months" }, { value: "24 months" }, { value: "Month-to-month" }]
  petsAllowed:
    type: boolean
    label: Pets Allowed
    default: false
  petDeposit:
    type: money
    label: Pet Deposit
    visible: hasPets
    required: hasPets

parties:
  landlord:
    label: Landlord
    partyType: any
    required: true
    signature:
      required: true
  tenant:
    label: Tenant
    partyType: person
    min: 1
    max: 4  # allows 1-4 tenants (array format)
    required: true
    signature:
      required: true
      witnesses: 1

layers:
  pdf:
    kind: file
    mimeType: application/pdf
    path: /templates/lease-agreement.pdf
    bindings:
      property_address: propertyAddress
      monthly_rent: monthlyRent
  html:
    kind: file
    mimeType: text/html
    path: /templates/lease-agreement.html

defaultLayer: pdf

annexes:
  identification:
    title: Tenant Identification
    description: Copy of government-issued ID
    required: true
  proofOfIncome:
    title: Proof of Income
    description: Recent pay stubs or tax returns
    required: false
```

**JSON**

```json
{
  "$schema": "https://schema.paradoc.dev/2026-10-02.json",
  "kind": "form",
  "name": "lease-agreement",
  "version": "1.0.0",
  "title": "Residential Lease Agreement",
  "description": "Standard residential lease agreement",
  "defs": {
    "hasPets": {
      "type": "boolean",
      "value": "fields.petsAllowed == true"
    }
  },
  "fields": {
    "propertyAddress": {
      "type": "address",
      "label": "Property Address",
      "required": true
    },
    "monthlyRent": {
      "type": "money",
      "label": "Monthly Rent",
      "required": true
    },
    "leaseStart": {
      "type": "date",
      "label": "Lease Start Date",
      "required": true
    },
    "leaseTerm": {
      "type": "enum",
      "label": "Lease Term",
      "enum": [{ "value": "12 months" }, { "value": "24 months" }, { "value": "Month-to-month" }]
    },
    "petsAllowed": {
      "type": "boolean",
      "label": "Pets Allowed",
      "default": false
    },
    "petDeposit": {
      "type": "money",
      "label": "Pet Deposit",
      "visible": "hasPets",
      "required": "hasPets"
    }
  },
  "parties": {
    "landlord": {
      "label": "Landlord",
      "partyType": "any",
      "required": true,
      "signature": {
        "required": true
      }
    },
    "tenant": {
      "label": "Tenant",
      "partyType": "person",
      "min": 1,
      "max": 4,
      "required": true,
      "signature": {
        "required": true,
        "witnesses": 1
      }
    }
  },
  "layers": {
    "pdf": {
      "kind": "file",
      "mimeType": "application/pdf",
      "path": "/templates/lease-agreement.pdf",
      "bindings": {
        "property_address": "propertyAddress",
        "monthly_rent": "monthlyRent"
      }
    },
    "html": {
      "kind": "file",
      "mimeType": "text/html",
      "path": "/templates/lease-agreement.html"
    }
  },
  "defaultLayer": "pdf",
  "annexes": {
    "identification": {
      "title": "Tenant Identification",
      "description": "Copy of government-issued ID",
      "required": true
    },
    "proofOfIncome": {
      "title": "Proof of Income",
      "description": "Recent pay stubs or tax returns",
      "required": false
    }
  }
}
```

## Related

* [Layer](/schemas/artifacts/shared/layer) - Layer specification