notarius/docs/integrations/json-output.md

JSON Output

This document is the durable JSON output file-format contract produced by the implemented json output module and written by the CLI.

Output Directory

The CLI writes logical output files under:

<output-root>/<run-id>/

The default output root is ./notarius-output. Operational behavior is covered in Operations.

Files

The json output module writes:

• index.json
• manifest.json
• lanes/<lane-id>.json, one file per normalized raw lane output
• rejected.json
• warnings.json

Files are pretty-printed JSON with a trailing newline when the payload is JSON.

index.json

Shape:

{
  "manifest_file": "manifest.json",
  "output_files": [
    {
      "lane_id": "spells",
      "media_type": "application/json",
      "file": "lanes/spells.json",
      "module_key": "noop",
      "schema_id": "notarius.dnd.spells",
      "schema_name": "notarius_dnd_spells_v1",
      "schema_version": "v1"
    }
  ],
  "rejected_file": "rejected.json",
  "warnings_file": "warnings.json"
}

output_files is sorted by lane ID. Output file names are produced by sanitizing the lane ID:

• characters outside A-Z, a-z, 0-9, ., _, and - become _;
• repeated .. sequences are replaced;
• leading and trailing ., _, and - are trimmed;
• empty sanitized names are rejected;
• two lanes that sanitize to the same output file are rejected.

manifest.json

manifest.json contains a run manifest:

{
  "run_id": "run-123",
  "pipeline_id": "dnd-session",
  "pipeline_digest": "sha256:...",
  "input_module": "seriatim",
  "chunker": "dnd/scenes",
  "source_digests": ["sha256:..."],
  "extractors": ["dnd/spells"],
  "merger": "appendorder",
  "normalizer": "noop",
  "output_encoder": "json",
  "artifact_lanes": [
    {
      "id": "spells",
      "extractor": "dnd/spells",
      "merger": "appendorder",
      "normalizer": "noop"
    }
  ],
  "validation_status": "approved",
  "started_at": "2026-01-01T00:00:00Z",
  "completed_at": "2026-01-01T00:00:01Z"
}

Fields with empty values may be omitted by JSON encoding.

source_digests contains source document digests only. Bound references are recorded separately under references, which contains provenance only: target stage, lane ID when present, slot name, origin type and URI, digest, media type, byte size, and binding source. Reference content is not written to durable output.

Reference stage is chunk, extract, merge, or normalize. lane_id is omitted for chunk references and present for extract, merge, and normalize references.

validation_status is approved when no raw outputs were rejected and rejected when one or more raw outputs were rejected.

normalized_outputs summarizes each normalized lane output without embedding payload bytes. Entries include lane ID, normalizer module key, source ID, media type, and response schema provenance where available.

rejected_outputs summarizes rejected module outputs without embedding raw payload bytes. Entries include stage, lane, module, chunk, validator or reason, message, attempt count, and optional diagnostic artifact path.

Output Payload Files

Each normalized raw output is written to lanes/<sanitized-lane-id>.json. The JSON output encoder accepts only application/json normalized outputs. The file contains the raw JSON payload pretty-printed.

For the current D&D spell extractor, lanes/spells.json has this shape:

{
  "spell_casts": [
    {
      "caster": "Aria",
      "spell": "Cure Wounds",
      "effect": "heals an injured ally",
      "narrative_description": "Aria raises her holy symbol and casts Cure Wounds.",
      "source_refs": [
        {
          "source_id": "session-alpha",
          "start_unit_id": 1,
          "end_unit_id": 1
        }
      ]
    }
  ]
}

rejected.json

Shape:

{
  "rejected": []
}

When raw output validation rejects an output, entries use the contracts.RejectedOutput shape, including stage, lane ID, module key, validator name, reason code, message, attempt count, and optional diagnostic artifact path.

warnings.json

Shape:

{
  "warnings": [
    {
      "scope": "extract",
      "reason_code": "example",
      "message": "human-readable warning"
    }
  ]
}

warnings is an empty array when no warnings are reported.