Use JSON Schema for Structured Summarization: A Node.js GPT Endpoint for Media Archives

A developer has described a Node.js pattern for summarizing media-archive transcripts with a GPT-compatible endpoint, enforcing a JSON Schema contract at the model boundary and then validating meaning in application code. The approach separates structural failures, where output cannot be consumed safely, from semantic failures, where output is consumable but untrustworthy, and adds idempotency keys to prevent duplicate work on retries. The developer notes that JSON Schema checks shape rather than evidence, so provenance fields and cheap invariants such as matching sourceId are needed before persistence.

A media archive has a stricter constraint than ordinary summarization: the result must help a person and remain valid enough for the next system to trust. I use a JSON Schema contract at the model boundary, then validate meaning in application code. The model produces a candidate. The runtime decides whether it is acceptable. The before-and-after model is small: Keep the boundary boring. No guesswork. That separation matters for a private media knowledge base. A missing topics array is easy to detect. A confident summary that mixes two broadcasts is much harder, so the contract needs provenance fields and observable rejection reasons. Start with fields that support a real archive workflow. For one transcript, I want a concise abstract, a bounded list of key points, the source identifier, and an uncertainty signal. The schema below is deliberately boring. Boring contracts are easy to test. js const summarySchema = { type: "object", additionalProperties: false, required: "sourceId", "abstract", "keyPoints", "confidence" , properties: { sourceId: { type: "string", minLength: 1 }, abstract: { type: "string", minLength: 40, maxLength: 800 }, keyPoints: { type: "array", minItems: 2, maxItems: 6, items: { type: "string", minLength: 10, maxLength: 240 } }, confidence: { enum: "high", "medium", "low" } } }; This is a shape contract, not a truth detector. sourceId can still be wrong. An abstract can still claim that a guest said something that appears nowhere in the transcript. Keep that distinction visible in the design and in the metrics. Because JSON Schema checks structure, not evidence. A structural failure means the response cannot be consumed safely. A semantic failure means it can be consumed, but should not be trusted. Mixing them creates noisy alerts and encourages someone to disable useful ones. Here is a compact Node.js boundary using a generic GPT-compatible endpoint. The endpoint name is configuration. The validation policy belongs to your application. type Summary = { sourceId: string; abstract: string; keyPoints: string ; confidence: "high" | "medium" | "low"; }; type ModelResponse = { output text?: string }; async function summarizeTranscript transcript: string, sourceId: string, endpoint: string, apiKey: string : Promise<Summary { const response = await fetch endpoint, { method: "POST", headers: { "content-type": "application/json", authorization: Bearer ${apiKey} }, body: JSON.stringify { input: { role: "system", content: "Summarize only the supplied transcript and return one JSON object matching the schema." }, { role: "user", content: sourceId: ${sourceId}\n\n${transcript} } , response format: { type: "json schema", json schema: { name: "media summary", strict: true, schema: summarySchema } } } } ; if response.ok throw new Error model request failed:${response.status} ; const payload = await response.json as ModelResponse; if payload.output text throw new Error "missing structured output" ; const candidate = JSON.parse payload.output text as Summary; assertSummary candidate, sourceId, transcript ; return candidate; } The hard edge is intentional: parsing and validation happen before persistence. In production, use a standards-compliant JSON Schema validator rather than relying on the TypeScript cast. A cast changes the compiler's view; it does not inspect runtime data. I also give each request a stable idempotency key. A timeout can happen after the endpoint accepted the request; retrying without that key may create duplicate work or duplicate review items. The semantic check can begin with cheap invariants. Require the returned source identifier to equal the requested identifier. Reject an empty transcript before calling the model. For stronger evidence, compare extracted names or timestamps against retrieved chunks, and route low-confidence items to review. A string match narrows one known failure mode; it does not prove factual correctness. Think of the pipeline as a three-lane diagram in words: request lane, contract lane, evidence lane. The request lane records latency and transport failures. The contract lane records parse and schema failures. The evidence lane records grounding or policy failures. Each lane has a different owner and a different next action. A useful event is small and stable: summary validation failed , sourceId as a non-sensitive identifier, stage as parse , schema , or evidence , and a bounded reasonCode . Avoid logging the transcript by default. Private media text can contain personal data, licensing-sensitive material, or unreleased reporting. Metrics should answer operational questions. Track the rate of each rejection stage, the fraction routed to review, model request latency, and the age of the oldest review item. Alert on a change in structural rejection rate after a prompt or schema deployment. A rising evidence rejection rate may point to retrieval drift instead. Those are different investigations. A dashboard panel that says summary failed: 4.2% tells you almost nothing. Three panels saying parse: 0.1% , schema: 0.7% , and evidence: 3.4% tell you where the contract is doing its job and where the content path needs attention. These numbers are illustrative thresholds, not a benchmark; choose limits from your own baseline. For a 429 or another transient rate limit, retry with bounded exponential backoff and jitter. Do not retry validation failures as if they were network failures. The former needs a contract or prompt decision; the latter may need a later attempt. In a queue-backed importer, the retry record should retain the idempotency key, attempt count, and next eligible time; otherwise a worker restart can turn one transcript into several review items. “Strict output will make the summary less natural.” Sometimes it will. That is an acceptable trade when another service needs predictable fields. Keep prose quality inside abstract , and keep machine-facing fields narrow. If editors want richer language, render a human view from the validated object instead of letting downstream code parse prose. “Validation means the answer is correct.” It does not. Schema validation is a gate for shape and selected invariants. Retrieval quality, prompt injection resistance, source permissions, and human review remain separate controls. OWASP lists prompt injection and sensitive information disclosure among risks needing application-level treatment, so a valid object should not bypass access checks or publication policy. The limitation is real: this contract is a poor fit for exploratory notes where fields change every hour. A looser text workflow may be better there. The trade-off is worthwhile for archive search and publication because those consumers need stable boundaries. The decision rule is straightforward: use a JSON Schema contract when a summary crosses a service boundary or drives a workflow; add semantic checks when a wrong-but-valid field can harm archive search or publication; keep a review path when the evidence cannot be judged automatically. That is the operational boundary.