The JSON layer architecture for AI-generated files

The JSON layer is an intermediate representation between model intent and document bytes. The model produces bounded, typed data; application code validates and normalizes it; a format engine compiles it into PPTX, DOCX, XLSX, or PDF; and independent checks decide whether the artifact is acceptable. The layer improves observability and control, but it does not by itself guarantee fidelity, visual quality, or compatibility.

What the JSON layer is

AI document generation has two very different problems:

1. deciding what the document should contain; and
2. constructing a file that satisfies a format, product, and release contract.

The first problem is semantic. It includes selecting facts, organizing sections, choosing chart data, drafting narrative, and applying user intent. The second is systems engineering. It includes type checking, layout, package relationships, font handling, archive construction, validation, artifact identity, and compatibility testing.

The JSON layer separates those problems with a typed intermediate representation (IR):

user request + trusted data
  -> model-authored intent
  -> schema validation
  -> semantic normalization
  -> format compilation
  -> structural validation
  -> application/visual inspection
  -> candidate artifact
  -> review and release

“JSON” describes the serialization, not the whole architecture. A JSON object with no schema, semantics, version, or validation is just untyped data. The useful boundary is a versioned contract that defines what each field means, which combinations are allowed, and how failures and losses are reported.

Why raw document bytes are the wrong model boundary

PPTX, DOCX, and XLSX are Open XML packages. Microsoft’s Open XML SDK overview describes them as ZIP-based Open Packaging Conventions packages made from multiple parts, content types, and explicit relationships. A presentation can include slides, layouts, masters, notes, charts, media, and embedded workbooks.

That package graph is a poor interface for an agent. A text model asked to author raw XML parts must coordinate identifiers, targets, content types, schema ordering, namespace declarations, and archive membership across many files. Even if every XML part parses, the package can still contain a missing relationship target or a viewer-specific incompatibility.

The safe conclusion is not “models can never emit valid OOXML.” A sufficiently constrained system could generate, validate, and repair such output. The architectural conclusion is narrower: raw package parts expose the model to low-level invariants that deterministic application code can enforce more directly and test more thoroughly.

The same reasoning applies beyond Open XML. PDF serialization has object references, cross-reference structures, fonts, graphics state, and optional semantic tagging. A model should usually decide document meaning and layout intent, while a renderer owns the byte-level format.

The seven layers of the pattern

1. Intent capture

The system first converts the user request and trusted application data into a bounded task. This stage establishes audience, artifact type, required sections, source records, brand or policy references, and acceptance criteria. It should also identify decisions the model is not authorized to make.

A weak prompt says “make a board deck.” A stronger intent contract says:

{
  "artifactKind": "presentation",
  "audience": "board",
  "requiredSections": ["summary", "revenue", "risks", "actions"],
  "sourceRecordIds": ["q3-ledger-v4", "risk-register-v2"],
  "reviewRequired": true
}

This object is not yet a presentation schema. It is the bounded job the model must satisfy.

2. Structured model output

The model produces an instance of a document IR. The schema should favor explicit structures over prose conventions: an array of slides rather than “use five slides,” chart series rather than Markdown tables hidden in a string, and source references rather than unsupported footnote syntax.

{
  "schemaVersion": 1,
  "kind": "presentation",
  "title": "Quarterly operating review",
  "slides": [
    {
      "id": "summary",
      "layout": "title-and-body",
      "elements": [
        { "type": "heading", "text": "Q3 summary" },
        { "type": "bullets", "items": ["Revenue increased", "Risk review remains open"] }
      ]
    }
  ]
}

The example is illustrative. The live engine schema, not this article, defines valid Runstamp input.

3. Schema validation

Schema validation establishes that the object has the expected shape: required fields exist, values have the right types, enum values are recognized, and extra fields are handled according to policy. It prevents an invalid object from reaching a serializer, but it does not establish that the content is correct.

For example, a chart series can be valid JSON with numeric points while citing the wrong quarter. A hyperlink can match the schema while pointing to an untrusted domain. A table can be structurally valid while exceeding a layout limit. Those are semantic and policy concerns, not JSON parsing concerns.

4. Semantic normalization

Normalization resolves accepted shorthand into one canonical model. It may apply defaults, normalize colors, resolve layout tokens, bind data references, allocate stable IDs, or convert a date into the format required by the document policy.

This stage needs an audit trail. If "layout": "standard" becomes "layout": "board-content-v3", the receipt should record the effective version. If a missing optional value receives a default, diagnostics can explain it. If the system substitutes or drops something the user asked to preserve, that is a loss, not a harmless normalization.

5. Format compilation

The renderer compiles the canonical model into format-specific structures and bytes. For PPTX, that includes slide and relationship parts. For DOCX, it includes document stories, numbering, styles, and media. For XLSX, it includes sheets, cells, formulas, styles, and related parts. For PDF, it includes pages, objects, fonts, and drawing instructions.

This layer should own deterministic identifier allocation, package assembly, escaping, part ordering, and resource limits. It should return a typed operation result rather than throw for normal document conditions. A byte array is an output, not enough evidence that the job succeeded.

6. Verification

Verification asks multiple questions because no single oracle covers every claim:

Passing one row does not imply the others. The validation model explains why a structural validator cannot stand in for a repair-dialog observation in PowerPoint.

7. Candidate, review, and release

Generation produces a candidate. Release is a separate transition that should bind the approved decision to the exact artifact bytes. If the candidate changes after review, its hash changes and the approval should no longer apply.

This boundary prevents a common architecture error: treating render() returning bytes as authorization to send the file. An agent can generate, inspect, and revise; a release policy determines whether the reviewed candidate may leave the system.

The result contract is as important as the input schema

Many JSON-layer explanations stop at “JSON in, document out.” That hides what downstream automation needs to know. A useful result includes at least:

• success or a stable, typed error;
• diagnostics that do not represent fidelity loss;
• a loss ledger for substitutions, degradations, and dropped content;
• artifact media type, byte length, and cryptographic hash;
• an operation receipt with input, effective options, engine identity, and output identity;
• locators that let a reviewer find the affected slide, cell, paragraph, shape, or part.

The distinction between diagnostics and losses is essential. Normalizing an accepted alias can be informational. Replacing a missing font may change appearance and should be recorded as a substitution. Dropping a macro or unsupported shape property is more severe. A caller can then choose a policy such as collect all losses, fail on any dropped content, or fail on any loss.

The evidence model develops this result contract with repository-backed examples and explicit scope limits.

What the JSON layer does not guarantee

The pattern is valuable partly because its limitations are explicit.

It does not guarantee factual correctness

The schema can require a number, but it cannot prove that the number came from the correct source. Preserve source record IDs, citations, and evidence references, then validate them separately.

It does not guarantee good layout

A valid document model can still overflow, create unreadable charts, or use poor hierarchy. Layout checks and visual review remain necessary.

It does not guarantee viewer compatibility

An artifact can pass structural checks and still behave differently in PowerPoint, LibreOffice Impress, Google Slides, a browser preview, or a mobile viewer. Compatibility claims require named viewer oracles and exact environments.

It does not guarantee determinism

JSON is diffable, but a renderer can still consume the clock, random values, network assets, locale, fonts, or non-deterministic traversal. Determinism must be defined and tested at the layer being claimed: identical IR, identical semantic structure, identical bytes, or equivalent appearance.

It does not eliminate prompt injection or authorization risk

Structured output constrains syntax. It does not make untrusted source text safe, authorize a network fetch, or grant release permission. Security and policy checks belong around the model and tool boundary.

Versioning the intermediate representation

Treat the IR as a public API even when it is initially internal.

• Include a schema version in every document request.
• Make unknown fields and unknown enum values fail predictably.
• Separate additive changes from semantic changes.
• Pin renderer and brand/policy versions in receipts.
• Retain migrations when old stored IR must be re-rendered.
• Build nominal, boundary, and hostile fixtures for every stable operation.
• Keep examples generated from or checked against the actual schema.

A schema without fixtures drifts. A fixture without a receipt cannot explain which renderer interpreted it. A receipt without the exact artifact hash cannot prove which bytes were reviewed.

Choosing the right level of abstraction

The IR should express user intent without exposing every OOXML element, but it should not be so high-level that important decisions become hidden renderer guesses.

Too low-level:

{ "relationshipId": "rId7", "xmlOrder": 4, "partName": "/ppt/slides/slide1.xml" }

Too vague:

{ "instruction": "make this look executive" }

More useful:

{
  "layout": "executive-summary",
  "headline": "Operating margin improved",
  "evidenceRefs": ["metric:margin:q3"],
  "riskLevel": "review-required"
}

The exact abstraction varies by product. A slide-generation API may expose layout and chart semantics. A template hydrator may expose placeholders and repeats. A document-operations API may expose parse, validate, repair, convert, diff, and extract contracts. The architecture remains the same: typed intent crosses the model boundary; deterministic code owns the format-specific invariants it can enforce; evidence records what actually happened.

A production checklist

Before calling a JSON-to-document workflow production-ready, verify that it:

• separates task intent from the document IR;
• uses a versioned exact schema;
• validates semantics and policy, not only syntax;
• normalizes into a canonical model with observable defaults;
• compiles through a format-specific engine with bounded resources;
• distinguishes diagnostics, losses, and hard errors;
• records exact artifact identity and effective versions;
• runs structural, inventory, visual, and application checks appropriate to the claim;
• requires review and exact-byte approval before release when the workflow demands governance;
• keeps benchmark and compatibility claims bounded to published evidence.

The JSON layer does not generate files by itself. It is a control boundary. Its value is that model intent becomes inspectable before serialization, format code becomes testable without prompting a model, and the final artifact can carry evidence rather than an unsupported promise.