data

Last updated on

Data operations for Paradoc artifacts.

Usage

paradoc data <command> [options]

Subcommands

data template

Generate an instance template from a form artifact.

paradoc data template <file> [options]

Arguments

Options

Examples

Generate template to stdout:

paradoc data template my-form.yaml

Generate template to file:

paradoc data template my-form.yaml --out data.yaml

Output

For a lease form with a text, address, money, date, boolean, enum, and number field, and one annex:

fields:
  tenantName: ""
  address:
    line1: ""
    locality: ""
    region: ""
    postalCode: ""
    country: ""
  monthlyRent:
    amount: 0
    currency: USD
  startDate: ""
  furnished: false
  term: monthly
  occupants: null
annexes:
  photoId: null

A field with a default gets that value. Otherwise each field gets a placeholder for its type:

When the form declares annexes, the template has an annexes block with each annex set to null. The template has no parties block.

The placeholders are a starting point, not valid data. Replace each one before you run data validate. An empty string, an empty date, or a null number fails a required field. Object placeholders (address, phone, person, organization, identification), zero money, and PT0S still pass, so replace those by hand.

data fill

Fill form data interactively, or from a data payload, and save it to an output file.

paradoc data fill <file> --out <file> [options]

Arguments

Options

Description

Without --data, the fill command walks you through each field in the form with interactive prompts. Field types are validated, and complex types (like addresses or money) can be entered as JSON.

With --data, it runs without prompts. The payload is a { fields, parties, annexes } object, or bare field values that are read as fields. It is validated as the SDK validates form.fill(data).validate(), and the filled payload, with field defaults and parties, is written to --out. The command exits with code 1 and writes nothing if validation fails.

Examples

Fill interactively:

paradoc data fill my-form.yaml --out filled-data.yaml

Fill from a data file:

paradoc data fill my-form.yaml --data input.json --out filled-data.yaml

Interactive session:

Fill Form: Residential Lease Agreement

? Address: 123 Main St
? Monthly Rent (Enter as JSON): {"amount": 1500, "currency": "USD"}
? Start Date: 2025-02-01
? End Date: 2026-01-31

✓ Form data saved
  Output: filled-data.yaml
  Format: YAML

data validate

Validate instance data against a form artifact. Exits with code 0 when the data is valid and 1 when it is not.

The data is a { fields, parties, annexes } payload, or bare field values that are read as fields. The command reports the same errors as the SDK's form.fill(data).validate(): expression-based required, party role rules, annex values, rule failures, and unknown top-level keys. With --json, a valid result carries the filled payload as data; an invalid one carries errors, and ruleErrors when a form rule fails.

paradoc data validate <form-file> <data> [options]

Arguments

Options

Examples

Validate a data file:

paradoc data validate my-form.yaml data.json

Validate data from stdin and print a JSON result:

cat data.json | paradoc data validate my-form.yaml - --json

data extract

Read filled PDF forms back into form data through the form's PDF layer bindings, and write the data and a report for each field as JSON. It reads fillable (AcroForm) fields only; flattened and scanned PDFs need the hosted Paradoc extraction service. The result is the same as the SDK's form.extract().

paradoc data extract <form-file> <pdf> [options]

Arguments

Options

Output

For one PDF, the output is { file, layer, data, report }. data holds only the values read back exactly, as a { fields, parties } payload you can pass to data validate or data fill. report.entries has one entry for each binding target, with a status of recovered, empty, not_recoverable, or unparseable and the raw PDF values. report.unbound lists PDF fields that hold a value no binding covers.

For a directory, the output is { results: [...] } with one result for each .pdf file in name order. A file that cannot be read has { file, error: { code, message } } in place of the data.

The command exits with code 1 when a PDF cannot be read: for example, no_form_fields for a PDF with no fields, encrypted_pdf, not_matching when the PDF is not this form, or layer_required when the form has several PDF layers and --layer is not set.

Examples

Extract one PDF:

paradoc data extract w-9.yaml completed-w9.pdf

Extract a directory of filled copies against one layer and save the result:

paradoc data extract 1099-nec.yaml ./filled --layer pdfCopyB --out extracted.json

See also

• new - Create new form artifacts
• render - Render forms with data
• inspect - List the raw AcroForm fields of a PDF

An artifact argument may be a file path or an installed @namespace/name reference from .paradoc/lock.json. An uninstalled reference fails with an error.