Why JSON shape is not historical accuracy
A museum label often needs a title, a concise visitor-facing statement, an object identifier, and a source-review status. A freeform assistant can place those elements in unpredictable order or omit one entirely. The Responses API exposes text.format so a compatible model can return output shaped by a JSON Schema. That reduces parsing ambiguity; it does not establish that an artifact date, attribution, donor name, or interpretation is true. Use the feature to prepare a review packet, never to bypass an approved collections record.
Imagine a fictional ceramic vessel with an accession number in a local catalog. The desired draft is a structured proposal with fields for public text, provenance references, uncertainty, and a human approval flag that stays false. Build the schema around these editorial decisions rather than around whatever wording the model happened to produce. If an attribute is unknown, make that absence visible to reviewers instead of requesting an attractive invented value.
Use text.format instead of a legacy response_format setting
OpenAI documents the Responses API structured-output configuration under text.format, with type json_schema, a short schema name, a schema object, and a strict option. Older Chat Completions examples place response formatting elsewhere. Mixing the two request shapes can cause errors or silent assumptions in a hand-built integration. Pin an actual model that supports the required structured-output behavior, consult its current compatibility notes, and keep model selection separate from label content rules.
The application should treat the request configuration as a versioned editorial interface. Record the schema version, model identifier, prompt revision, source-record version, and generation timestamp in a private audit record. Do not publish the prompt, private accession metadata, or raw completion as a public proof artifact. A successful HTTP response is merely the beginning of the editorial review.
Design fields reviewers can actually check
Use straightforward properties such as accession_id, proposed_title, label_text, source_record_ids, uncertainty_note, and approved_for_publication. Keep public prose separate from internal identifiers so a publishing template cannot accidentally expose catalog-only data. For strict Structured Outputs, OpenAI requires every declared field to appear in required and additionalProperties to be false on each object. If a field can genuinely be missing, model it as a nullable value instead of relying on an omitted property.
Limit the permitted output to a short label and a compact evidence inventory. You may use string lengths in your downstream validator, but do not assume every JSON Schema constraint is supported by the model-side strict subset. Apply operational word limits, catalog-ID formats, link allowlists, and disallowed personal information rules in ordinary application code after the model returns. Keep the schema human-readable enough for an editor to inspect.
Connect each claim to a source, not just a plausible URL
Ask the generator to cite identifiers from a deliberately selected list of approved catalog records rather than to fabricate web citations. The application must cross-check each returned identifier against that same list and inspect the underlying record for the supported assertion. A source ID can be syntactically valid while pointing to a document that says something different. Structured output improves the handoff format, not the truth of a description.
For the hypothetical vessel, a material claim might use one catalog record while a historical attribution requires a separate conservation note. If no approved document resolves the attribution, carry an explicit unknown or disputed status into the draft. Do not infer authenticity, ownership, permissions, or intellectual property rights from the fact that a JSON object contains complete fields.
Handle refusals, partial output, and parsing errors
A strict schema request can still need error handling for content-policy refusals, incomplete outputs, transport failures, or unavailable models. Do not present any refused or truncated output as a complete label. Check the response status and output types before parsing text; then perform JSON parsing and application-level validation as separate steps. The safest failure state is a visible draft error with no automatic public update.
Keep rejected records in a restricted review queue with enough diagnostic information to reproduce the issue without retaining unnecessary personal material. Avoid an endless retry loop that sends the same sensitive catalog record repeatedly. A retry should follow an understood error with an explicit budget, not treat every schema mismatch as permission to ask the model to invent missing fields.
Separate display copy from controlled catalog metadata
The final exhibit label may be shorter and more approachable than the technical catalog record, but it must not replace that source record. Maintain separate fields for verbatim source statements, a proposed paraphrase, and a reviewer decision. The source record remains authoritative for measurements, dates, titles, and ownership. If a label includes a quote, verify it against the primary document and preserve necessary attribution.
Keep sensitive donor and location fields outside the model input whenever the public label does not need them. When a gallery team needs a location description, use an approved public location, not an internal storage locator. Scope the application account and data handling policy to the actual deployment. JSON shape cannot itself enforce permissions or prevent private information from appearing in a generated sentence.
Create a curator gate that cannot be filled by the model
Represent approval as a separate database action performed by an authorized editor after reviewing the proposed fields. The model may return approved_for_publication: false as a constant-like draft value, but that is not a security control. The publishing pipeline should require a trusted approval record tied to the exact reviewed content hash. Editing the label later must invalidate the previous approval or start a new revision.
A curator should inspect the label at visitor reading distance, cross-check identity and chronology, and ensure that uncertainty survives simplification. Another reviewer can check accessibility language and whether the display uses captions and alt text appropriately. This division of duties makes the structured draft useful without confusing machine conformance with human authorization.
Compare three distinct output states before release
The first state is unconstrained prose: perhaps readable but difficult to integrate into a template. The second state is a schema-valid object whose fields can be mapped into a mock exhibit card. The third state is a curator-reviewed version in which provenance, wording, and permissions have been checked. These are conceptual stages, not measured outputs from a live OpenAI call. The improvement is a cleaner review path, not a claim of increased factual accuracy.
Use a local fixture containing a deliberately missing date, a disputed attribution, and an accession ID with punctuation. Check that no field disappears, the uncertain fact remains uncertain, and the publishing layer refuses an unapproved record. Add a separate test for schema evolution: a new required field should not silently convert old cached drafts into reviewed records.
Release checklist and limitations
Before release, confirm the exact model and supported schema features; validate all parsed fields; resolve each source pointer; redact protected information; obtain human approval; and preview the displayed label on mobile and desktop. Retain an approved version and a rollback route. The JSON object is an intermediate editorial artifact rather than a public historical source.
No API request, museum collection, or production editor was used in this illustrative workflow. Costs, supported models, strict-schema behavior, request fields, and service data policies can change. Verify the official API contract and the actual organization’s collection policy before implementing a system that publishes externally.
How We Research
Official primary documentation consulted November 11, 2026: OpenAI Responses create API reference; OpenAI Structured Outputs guide; OpenAI Responses migration guide. We compared the named API or runner setting with the provider documentation and designed a hypothetical museum workflow to expose failure states, permissions, data provenance, and release checks. We did not call a production API, query a customer account, execute a live workflow, or measure performance. The accompanying illustrations are editorial diagrams, not screenshots or experimentally observed outcomes. Confirm current versions, supported features, charges, privacy rules, and organizational authorization in the real deployment before relying on this guide.
Frequently Asked Questions
No. It constrains the output structure when supported; a curator still has to confirm historical claims against approved records.
Use the Responses text.format configuration with a compatible json_schema format, not an outdated Chat Completions response_format example.
Strict schema fields must be required. A nullable type can represent genuinely unknown information without silently omitting a required key.
No. An independent trusted reviewer and a version-specific release record must authorize publication.
Mark the draft unsuccessful, inspect status and errors, and prevent publishing until a complete validated output and human review exist.