Spots

How to Build 4-Field Structured Summary JSON Output (API Schema Included)

TL;DR: Build a structured summary JSON output API by sending the diff and an explicit four-field schema in one chat-completions request, then validate the response before it reaches your review UI. This gives a media engineering team a title, bullets, key takeaways, and action items without a second extraction service. Pick the model for instruction following first; count input tokens and measure the quality-versus-latency trade-off on your own diffs before standardizing the contract. Keep the boundary boring. That is the goal. How should a structured summary JSON API shape its output?

The before state is familiar: a model returns

The before state is familiar: a model returns three polished paragraphs, a dashboard tries to split them, and an email template quietly loses the action items. The after state has one request and four named fields: title, bullets, keyTakeaways, and actionItems. Rendering becomes mechanical. So does storage, alerting, and later analysis.

Here is the diagram in words: diff in

Here is the diagram in words: diff in -> chat request -> parsed contract -> review UI. The validator sits between the model and every downstream consumer. It is a gate, not cleanup.

That distinction matters for code review. A fluent

That distinction matters for code review. A fluent response can still omit a required finding or return an action item as a paragraph. Structured output does not make the review correct, and it does not shrink a large diff. It makes failures visible at a boundary where the caller can retry, reject, or send the change to a human.

Four fields are enough for this workflow. Resist

Four fields are enough for this workflow. Resist adding severity, ownership, file ranges, confidence, and remediation metadata until a real consumer needs them. Every extra field expands the ways a response can be incomplete. Build one copyable request

The example below uses the OpenAI client against

The example below uses the OpenAI client against Infrai's compatible surface. It sends one chat request, demands JSON in the prompt, removes Markdown fences if the model adds them, and rejects anything outside the contract. The model ID is explicit so a catalog change cannot silently alter behavior.

Install openai and zod, set INFRAI_API_KEY and INFRAI_BASE_URL

Install openai and zod, set INFRAI_API_KEY and INFRAI_BASE_URL to the account's API base, and run the file with a TypeScript runner. The SDK sends the bearer credential and handles transient retries, including rate limiting, with bounded retry behavior. The parser still owns the final decision: malformed JSON and wrong shapes fail loudly.

For production, record four observations around this call

For production, record four observations around this call: model ID, input token count, end-to-end latency, and validation outcome. Do not log the source diff or raw finding text by default; media repositories can contain embargoed titles, access tokens, or unpublished copy. Aggregate the observations into a validation-failure rate and latency percentiles. Alert on a sustained change, not one odd response.

Token counting deserves its own preflight when diffs

Token counting deserves its own preflight when diffs vary wildly. Structured fields organize the output; they do not reduce the input cost or make an oversized patch easier to reason about. Split large reviews at coherent file or subsystem boundaries, then merge validated findings under the same contract. Which provider fits this boundary?

There is no universal winner. The useful comparison

There is no universal winner. The useful comparison is operational fit after every candidate passes the same held-out review set.

News

How to Build 4-Field Structured Summary JSON Output (API Schema Included)

TL;DR: Build a structured summary JSON output API by sending the diff and an explicit four-field schema in one chat-completions request, then validate the response before it reaches your review UI.

@spots #dev
Source: Dev.to
See more like this