Two Machine-Readable Worlds

The schism you have to plan around

Your catalog is data (2.1); your statements are human-authored and traceable (2.2). Now the package has to leave home — and here the field hands you a genuine mess, best stated plainly: there are two machine-readable compliance worlds, and they are not converging.

World one: OSCAL — NIST’s Open Security Controls Assessment Language. A family of models (catalog, profile, component definition, SSP, assessment plan/results, and — newer — control mapping) representing the whole authorization package as structured data. It’s the lingua franca of the RMF/DoD lineage and a healthy open ecosystem (NIST stewardship with GSA participation, community tooling under CNCF including compliance-trestle). Current release: 1.2.x as of this writing — the exact pin lives in the callout below, where dated facts belong (and where yours should live in your own docs too).

World two: FedRAMP-JSON. FedRAMP — the program you might have expected to be OSCAL’s flagship customer — walked away for its rewritten certification lane, defining its own purpose-built JSON schemas around Key Security Indicators and Security Decision Records (Lesson 4.1 covers the program mechanics). Not OSCAL-derived. Not translatable by wishful thinking.

And the reality check under both: most authorization packages in circulation are still Word and Excel. Hand-authored OSCAL is effectively nonexistent in the wild — structured formats are emitted by platforms, not typed by ISSOs. Which points at the strategy.

Structured-data-first, emit both

The shops that handle the schism well share one architecture: your internal source of truth is your own structured data (the Lesson 2.1 catalog), and every external format — OSCAL for one consumer, FedRAMP-JSON for another, Word for the AO who reads on paper (Lesson 3.3) — is a generated export. Format churn then costs you an exporter, not a migration. The formats are wire protocols; the catalog is the database — or, for the non-engineer: keep one master copy of the truth, and let every form the outside world demands be printed from it. A new form is then a new print job, never a rewrite. (Commercial readers: the compliance-automation platforms you may already use work this way internally; the difference here is that you own the master copy, so changing platforms costs an exporter rather than a full migration.)

                      ┌── export: OSCAL 1.2.x SSP + component defs
  catalog (YAML,      ├── export: FedRAMP-JSON (when that consumer appears)
  schema-gated,  ─────┼── export: Word/PDF package        (Lesson 3.3)
  Lesson 2.1)         └── export: control-docs site       (Lesson 3.3)

Determinism is the feature

The reference implementation’s sharpest idea: exports are deterministic by construction — same catalog in, byte-identical package out. Identifiers are derived from the content itself rather than generated at random (UUIDv5 — a hash-derived ID — in the reference implementation); no generation timestamps, no ordering wobble, no network calls at export time. Enforced by the simplest gate imaginable: regenerate in CI and fail unless the output is byte-equal when inputs are unchanged.

Why this earns a whole section: with deterministic export, git diff on the generated package is the change review. A one-line catalog change produces a small, legible package diff an ISSO can approve in minutes; nondeterministic output produces a thousand-line diff of churned UUIDs in which the real change hides — so reviewers stop reading, and the export becomes unreviewed. Determinism isn’t fastidiousness. It’s what makes generated compliance artifacts reviewable at all — in leadership terms, it is the difference between an ISSO approving a package change in minutes and a package nobody reads, which is a package nobody should sign — and Lesson 6.2 will lean on it as the release gate for the self-updating package.

Prompt first: the export scaffold

Build an exporter from our control catalog (schema attached) to an
OSCAL 1.2.x component-definition and SSP fragment. Requirements:
1) DETERMINISTIC: UUIDs seeded from control-id + component name via
   UUIDv5; no generation timestamps; stable key ordering; assert no
   network access at export time;
2) statements pass through VERBATIM from the catalog - no template
   prose, no summarization: the human-authored text (Lesson 2.2) is
   the narrative, exactly as written;
3) a CI job that regenerates and diffs: unchanged inputs must yield
   byte-identical output, and any change must fail with the diff shown;
4) map catalog fields to OSCAL properly and list every field that has
   NO clean OSCAL home - do not smuggle them into misc props silently.

Requirement 2 is Lesson 2.2’s boundary surviving contact with tooling: the exporter assembles, humans author. Requirement 4 keeps the schema honest — every format migration starts with knowing what doesn’t map.

Practice status — among mature regulated delivery programs, commercial and federal

(a few rows carry a more specific status - principle, canon, suspended - where one of the five would mislead)

Scale: required | common baseline | strong optional | reference-shop (seen only at organizations that publish their own practice) | emerging

Key takeaway

Two machine-readable worlds — OSCAL for the RMF/DoD lineage, FedRAMP-JSON for FedRAMP’s rewritten certification lane — with no convergence in sight and Word still ruling in practice. Don’t pick a side: keep your own catalog as the source of truth and emit every format as a deterministic export, byte-equality-gated in CI, statements passing through verbatim. Determinism is what keeps generated artifacts reviewable — and ask early which system of record your package must actually land in. Next module: evidence, and the machinery that makes verdicts honest.

LEADERSHIP DECISION   fund the catalog as the master copy and exporters as the
                      product - never a bet on one package format
PRACTITIONER ACTION   build deterministic exporters (OSCAL, FedRAMP-JSON,
                      Word) from the catalog with a byte-equality gate in CI;
                      ask the receiving ISSO which system of record
SUCCESS MEASURE       a package change reviewable as a small diff in minutes;
                      a new consumer format costs one exporter; zero format-
                      migration projects