# JSON output contract

Integrate the openbooks.v1 release and refusal contract with exact decimal money, source evidence and verification assertions.

Source: https://openbooks.lumeo.co.in/docs/output-contract

Every completed document decision uses the `openbooks.v1` JSON schema. The CLI, Python, Node.js, and HTTP API expose the same underlying document. Some entry points wrap it in a result or event, so unwrap it before applying the contract below.

## Read the envelope first [#read-the-envelope-first]

1. Check `schema_version` against the version your integration supports.
2. For `status: "ok"`, read the released records under `data` and retain their assertions and source evidence.
3. For `status: "refused"`, read `error.code` and `error.message`. The document has `data: null`.
4. Handle missing decisions, such as a timeout or interrupted stream, at the job level. See [refusal and execution handling](/docs/refusals).

## Released documents [#released-documents]

| Field | Contents |
| --- | --- |
| `status` | `"ok"` |
| `file` | Input name and SHA-256, detected format, layout version and extraction method. A model-checked release also identifies the weights and calibration by SHA-256. |
| `data` | `accounts`, `parties`, `batches`, `transactions` and `claims`. Collections can be empty and fields vary with the layout. |
| `evidence` | Source locations and raw text indexed by record and field. |
| `assertions` | Statement, settlement or layout-specific checks. All must pass with at least one independent check. |

This transaction is from the [sample terminal](/docs/quickstart).

~~~json
{
  "id": "txn-00001",
  "batch_id": "batch-1",
  "account_id": "acct-1",
  "date": "2026-01-02",
  "direction": "debit",
  "amount": { "amount": "100.00", "currency": "INR" },
  "balance_after": { "amount": "900.00", "currency": "INR" },
  "description": "Sample payment",
  "reference": null
}
~~~

Retain money as decimal strings, and use a decimal library for arithmetic. Carry the currency alongside the amount. Date fields are ISO calendar dates where the layout supplies a date. Scope record IDs to their source document when combining files.

## Evidence and independent checks [#evidence-and-independent-checks]

Use the record ID and field name to find the source. In the quickstart, `evidence["txn-00001.amount"]` gives the first transaction's amount as it appeared on row 2 of the CSV.

~~~json
{
  "page": null,
  "bbox": null,
  "row": 2,
  "raw_text": "100.00",
  "method": "parser"
}
~~~

`page`, `bbox`, and `row` describe where to look and can be null when a location is unavailable or inapplicable. `raw_text` preserves the source reading or records that a value was supplied by the caller. `method` records how the field was extracted.

Each assertion reports `id`, `rule`, `expected`, `computed`, `passed`, and `independent`. The quickstart's closing-balance assertion compares an expected `"950.00 INR"` from the source against the same amount computed from the opening balance and transactions. It passes and is independent because the expected closing amount comes from the CSV.

## Refused documents [#refused-documents]

~~~json
{
  "schema_version": "openbooks.v1",
  "status": "refused",
  "data": null,
  "error": {
    "code": "PARSE_ERROR",
    "message": "statement has no stated opening balance; supply --opening",
    "file_sha256": "4cbb7e3f45dc4860ba6c14e51b32a2667fbb526b4f6f78e7861bc3d6b4f1f997"
  }
}
~~~

Read `error.code` for programmatic handling and `error.message` during review. The refusal hash is `error.file_sha256`. In a release, it is `file.sha256`. Both identify the exact input bytes. Store processing parameters and versions when the same bytes may be run with different settings.

## Validate documents at the integration boundary [#validate-documents-at-the-integration-boundary]

Use the [release schema](/schema/openbooks.v1.schema.json) or [refusal schema](/schema/openbooks.v1.refusal.schema.json) according to the document status. Both are included in the Python package and mirrored by the Node.js validation helpers. When retaining normalized records, store the original decision with enough context to find its assertions and evidence later. See the [Python API](/docs/python#validate-stored-output) for a validation example.
