# data Data operations for artifacts Canonical URL: https://docs.paradoc.dev/cli/commands/data/ Data operations for Paradoc artifacts. ## Usage ```bash paradoc data [options] ``` ## Subcommands | Command | Description | | ---------- | --------------------------------------------------- | | `template` | Generate an instance template from a form | | `fill` | Fill form data interactively or from a data payload | | `validate` | Validate instance data against a form artifact | | `extract` | Extract form data from filled PDF forms | *** ## data template Generate an instance template from a form artifact. ```bash paradoc data template [options] ``` ### Arguments | Argument | Description | | -------- | ------------------------------ | | `file` | Form artifact file (JSON/YAML) | ### Options | Option | Description | | -------------- | ------------------------------------------------- | | `--out ` | Output file path (format detected from extension) | | `--json` | Force JSON output format | | `--yaml` | Force YAML output format | | `--silent` | Suppress console output (exit code only) | ### Examples Generate template to stdout: ```bash paradoc data template my-form.yaml ``` Generate template to file: ```bash 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: ```yaml 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: | Type | Placeholder | | ---------------------------------------------------------- | --------------------------------------------------------------------- | | `text`, `email`, `uri`, `uuid`, `date`, `datetime`, `time` | `""` | | `boolean` | `false` | | `number`, `percentage`, `rating` | `null` | | `enum` | the first option's value, or `null` with no options | | `multiselect` | `[]` | | `list` | `[]` | | `money` | `{ amount: 0, currency: USD }` | | `address` | `line1`, `locality`, `region`, `postalCode`, and `country`, each `""` | | `phone` | `{ number: "" }` | | `person`, `organization` | `{ name: "" }` | | `identification` | `{ type: "", number: "" }` | | `coordinate` | `{ lat: 0, lon: 0 }` | | `bbox` | `southWest` and `northEast`, each `{ lat: 0, lon: 0 }` | | `duration` | `PT0S` | | `fieldset` | an object with a placeholder for each nested field | 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`](#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. ```bash paradoc data fill --out [options] ``` ### Arguments | Argument | Description | | -------- | ------------------------------ | | `file` | Form artifact file (JSON/YAML) | ### Options | Option | Description | | --------------------- | ------------------------------------------------------------------------- | | `--out ` | Output file path, format detected from extension (required) | | `--data ` | Data payload: file path, `-` for stdin, or inline JSON. Skips the prompts | | `--json` | Force JSON output format | | `--yaml` | Force YAML output format | ### 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: ```bash paradoc data fill my-form.yaml --out filled-data.yaml ``` Fill from a data file: ```bash 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. ```bash paradoc data validate [options] ``` ### Arguments | Argument | Description | | ----------- | ------------------------------------------------------- | | `form-file` | Form artifact file (JSON/YAML) | | `data` | Instance data: file path, `-` for stdin, or inline JSON | ### Options | Option | Description | | ---------- | ---------------------------------------- | | `--json` | Output a machine-readable JSON result | | `--silent` | Suppress console output (exit code only) | ### Examples Validate a data file: ```bash paradoc data validate my-form.yaml data.json ``` Validate data from stdin and print a JSON result: ```bash 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()`](/sdk/artifacts/form#extracting-data-from-a-filled-pdf). ```bash paradoc data extract [options] ``` ### Arguments | Argument | Description | | ----------- | ------------------------------------------- | | `form-file` | Form artifact file (JSON/YAML) | | `pdf` | A filled PDF, or a directory of filled PDFs | ### Options | Option | Description | | --------------- | ------------------------------------------------------------------------------ | | `--layer ` | PDF layer to read against. Required when the form has more than one PDF layer. | | `--out ` | Write the JSON to a file instead of stdout | ### 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`](#data-validate) or [`data fill`](#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: ```bash paradoc data extract w-9.yaml completed-w9.pdf ``` Extract a directory of filled copies against one layer and save the result: ```bash paradoc data extract 1099-nec.yaml ./filled --layer pdfCopyB --out extracted.json ``` ## See also * [new](/cli/commands/new) - Create new form artifacts * [render](/cli/commands/render) - Render forms with data * [inspect](/cli/commands/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.