Center for Federal Accountability › Reports

JSON Normalization Contract (FederalRegister → cfa-reports)

Standardized JSON shape used to generate Documentation.AI MDX hubs and drill-down detail pages from FederalRegister report outputs.

This documentation defines the JSON contract for the cfa-reports documentation generator pipeline.

Why normalization exists

FederalRegister report streams (FederalRegister/scripts/run_report.py) have different JSON shapes. The normalization layer converts each report stream into a consistent hub/detail-friendly structure stored in cfa-reports/docs/data/.

Common top-level fields (required)

Every normalized file under cfa-reports/docs/data/ must include:

• report: string
  • The logical report type identifier for the generator (e.g. open_comment, external_documents).
• generated_at: string (ISO timestamp)
  • When the normalized bundle was created (or, for “direct copies”, the upstream timestamp).
• export_source: string (optional)
  • Where the data came from (e.g. federal_register_output).
• summary: object
  • Hub-level metrics/counts used by index.mdx.
• documents: array
  • The ordered list of “items” that will become detail pages.

Common per-item fields (required)

Each element of documents[] must include:

• slug: string
  • Stable route-friendly identifier (generator uses it for file/route naming).
• title: string
  • Short, human-readable title for the detail page and nav labels.
• overview: string
  • A tag-safe short narrative that can be placed into description fields or ## Overview.
• metadata: object
  • Canonical identifiers and source URLs.
  • Must be JSON-safe and should avoid large HTML blobs.
• raw: object (optional)
  • The unmodified or partially modified source object to support richer rendering later.

Per-report extras (optional)

Generators may also render extra fields inside the ExpandableGroup on detail pages. These fields should live either:

• inside each documents[] item (e.g. analysis, metrics, related), or
• inside metadata for strictly identifier/source information.

Open-comment parity

For open_comment:

• Use the existing FederalRegister-compatible shape already produced as FederalRegister/output/open_comment_report.json.
• In normalization, copy/merge into cfa-reports/docs/data/open-comment-report.json without changing the keys expected by the existing open-comment generator.

MDX safety requirement

If overview or title originates from FederalRegister HTML-like fields:

• strip tags before writing MDX,
• escape stray < characters so Documentation.AI does not interpret text as JSX/HTML.