2026 JSON Schema Compatibility Validation: Can Three Models Share One Definition?

The current JSON Schema specification identifies Draft 2020-12 as a published specification line, not proof that every model API accepts the entire dialect (JSON Schema specification overview). That distinction gives this week’s action: share one business-level core Schema, then validate a separate adapter for OpenAI, Gemini, and Claude before release. Do not assume that one unchanged source file is compatible with all three interfaces.

This guide is for platform engineers defining multi-model adapter boundaries, test engineers comparing identical inputs across APIs, and Schema authors who need to remove unnecessary nesting or vendor-specific extensions. It is not a single-provider configuration tutorial.

Start with the real compatibility boundary

A Schema can be valid according to JSON Schema and still fail at an API boundary. The reason is simple: the specification defines a broad vocabulary and dialect model, while each provider documents its own accepted subset, request wrapper, strictness behavior, and output constraints.

A reliable design therefore separates four layers:

• Business Schema: the fields, types, required values, enumerations, and relationships that the application actually needs.
• Provider adapter: the conversion from the core definition into the request shape required by a specific API.
• Execution contract: the permissions, resource scope, idempotency rules, and authorization checks applied before a tool runs.
• Consumer validation: database, policy, factual, and cross-field checks applied after parsing.

The first layer can be shared. The other layers must be tested independently.

A useful compatibility claim should always name the test date, API version or model endpoint, Schema dialect, adapter revision, and sample-set revision. “Works with all three models” is too vague to approve a production release.

Important: JSON Schema compatibility has at least two meanings. Syntactic compatibility asks whether an API accepts a definition. Semantic compatibility asks whether the resulting data means the same thing to the application. Passing the first test does not imply passing the second.

First step: define a deliberately small core Schema

The Schema author should begin with business meaning, not with the most expressive feature available in the specification. The core definition should contain only constraints that downstream systems will enforce or use.

The first review should cover these items:

• Dialect identification: record whether the source uses Draft 2020-12 or another dialect. Do not label a document as Draft 2020-12 merely because it contains familiar keywords. The dialect determines how vocabularies and references are interpreted. The official Draft 2020-12 documentation should be the authority for the source definition.
• Primitive types: use explicit string, number, integer, boolean, array, and object types where the application depends on them. Avoid accepting several types simply to accommodate inconsistent model output.
• Required fields: mark a field as required only when the consumer cannot operate safely without it. A required property checks presence; it does not confirm that the value is correct or complete.
• Enums: use enum for closed business vocabularies such as status values or operation types. Confirm that every provider preserves the exact spelling and case expected by the consumer.
• Arrays: define items and, where relevant, the expected uniqueness or ordering rule in business validation. An array Schema alone does not prove that repeated records are acceptable.
• References: use $ref only when the selected provider and adapter can resolve the reference reliably. A local reference may be safe in one request format but awkward after a provider-specific conversion.
• additionalProperties: set it for a business reason. Rejecting unknown properties can protect a strict database contract, while allowing them can support forward-compatible metadata. The choice should not be made only because a provider’s strict mode prefers it.

The JSON Schema validation guide explains the basic validator model: an instance is evaluated against a Schema and either passes or fails the declared assertions. That validator result remains useful even when a model API imposes additional restrictions.

Can one JSON Schema serve all three models?

Yes, if “one Schema” means one business-level source of truth that is transformed and tested for each provider. No, if it means one raw JSON file submitted unchanged to OpenAI, Gemini, and Claude with identical behavior guaranteed.

A core Schema is suitable for sharing when:

• the dialect is recorded;
• the required fields have the same business meaning in every adapter;
• enumerations are stable;
• references have a tested resolution strategy;
• unknown-property behavior is intentional;
• every transformation is reviewable;
• provider-specific restrictions do not remove a business-critical assertion.

A provider-specific Schema is safer when a provider rejects a keyword, interprets a wrapper differently, or exposes strict output behavior that cannot express the core contract. In that case, the adapter may simplify the transport Schema, but it must preserve the missing rule in a separate validator or block the integration.

The OpenAI Structured Outputs guide should be treated as the authority for OpenAI’s documented structured-output behavior. The Gemini Structured Output documentation should be checked independently rather than inferred from OpenAI terminology. Claude tool calls use an input_schema contract documented in the Claude tool-use overview, which is not automatically interchangeable with another provider’s request wrapper.

Second step: build the provider adapter contract

The adapter is not a convenience function that silently edits a Schema. It is a compatibility boundary with its own source, tests, and release history.

For each provider, record the following:

• the request field that carries the output or tool definition;
• the field name used for the Schema itself;
• the field name used for the operation or tool;
• whether strict mode exists and how it is enabled;
• how the response is extracted;
• how refusal, blocked content, malformed output, and transport errors are represented;
• which keywords are accepted, rejected, ignored, or transformed;
• whether references are expanded before submission;
• whether property order, optional fields, or null values need special handling.

OpenAI’s API reference is the appropriate source for request and response parameters rather than a third-party example (OpenAI API reference). Gemini’s content-generation reference should be checked for the provider’s request and response structure (Gemini generate-content reference). Claude’s tool-use documentation should be used for tool input and result handling, not a generic OpenAI-compatible client assumption.

A conversion rule needs one of three outcomes:

1. Preserve: the keyword and its business meaning remain intact.
2. Move: the rule is removed from the transport Schema but enforced by a post-parse validator.
3. Block: the integration is rejected because the rule cannot be represented safely.

Silent deletion is never an acceptable fourth outcome.

The adapter should emit a machine-readable transformation report. That report can list the source path, target path, action, reason, and replacement validator. A code review can then identify whether a change affects business meaning or only transport syntax.

Third step: answer the full-dialect question before testing models

Does full JSON Schema 2020-12 work everywhere?

No general compatibility claim should be made without provider-specific evidence. Draft 2020-12 is a specification version, while model APIs may support only a documented subset or may expose structured output through a provider-specific wrapper.

This affects design in several ways:

• A valid keyword can still be rejected by the endpoint.
• A keyword may be accepted syntactically but have no demonstrated effect on generated output.
• A reference may validate in a local JSON Schema library but fail after conversion into a tool or response format.
• Strict output mode can constrain the accepted shape without guaranteeing business-level correctness.
• A provider may distinguish between structured response output and tool input, so the same Schema may need separate adapters.

The correct test is not “does the validator accept this file?” It is “does the intended API accept the adapted definition, return a parseable instance, and preserve every business-critical rule under the shared test set?”

For each keyword in the core definition, assign a support status:

• Required and verified: tested through the provider endpoint and local validation.
• Accepted but behavior unverified: the request succeeds, but the rule has not been proven through negative cases.
• Unsupported and moved: enforced outside model generation.
• Unsupported and blocking: cannot be reproduced without changing business meaning.
• Provider extension: used only inside one adapter and excluded from the shared source.

This classification prevents a common mistake: treating a successful API request as evidence that every Schema assertion is active.

Fourth step: create a shared test set for automated comparison

The test team should use the same logical samples for every provider. The prompt or tool description may need provider-specific wrapping, but the test intent must remain identical.

The minimum sample families should include:

• a normal valid request with all ordinary fields;
• a request missing each business-critical field in isolation;
• a wrong primitive type;
• an unknown property;
• an invalid enum value;
• an empty array or object where the business rule rejects emptiness;
• deeply nested data that exercises the supported structure;
• an overlong string or oversized input boundary;
• conflicting fields whose relationship must be checked after parsing;
• a request that should be refused because the operation is outside policy.

For each execution, store:

• provider and endpoint;
• model identifier;
• request API version, when exposed;
• core Schema version;
• adapted Schema version;
• adapter revision;
• test-set revision;
• request identifier;
• transport status;
• refusal or error category;
• raw response location;
• parsed JSON result;
• local Schema validation result;
• business validation result;
• final disposition.

How should cross-model JSON Schema testing be automated?

The test runner should compile the shared samples into provider-specific requests, execute them under controlled credentials, normalize the response envelope, and then run the same validation pipeline. The pipeline should not compare raw text because equivalent JSON can differ in formatting or property order.

A practical sequence is:

1. Load the pinned core Schema and verify its dialect declaration.
2. Generate the OpenAI, Gemini, and Claude adapter payloads.
3. Run a static compatibility check for unsupported or transformed keywords.
4. Send the same logical sample to each endpoint.
5. Classify transport success, refusal, timeout, malformed output, and provider error separately.
6. Extract the structured result without coercing invalid values into valid ones.
7. Run a standard JSON Schema validator against the result.
8. Run business-rule and database-contract checks.
9. Compare dispositions, not just generated content.
10. Store the full evidence bundle for the release report.

A malformed response should not be repaired silently with string replacement or permissive parsing. If a repair step exists, it must be recorded as a failure or separate transformation, because the model did not produce an instance that satisfied the declared contract.

Testing note: A passing happy-path sample proves very little. Negative cases reveal whether required, type constraints, enum boundaries, and unknown-property rules are actually enforced rather than merely present in the request.

Fifth step: separate structured output from agent authorization

The agent executor owns a different acceptance decision. A model can produce syntactically valid tool arguments that are still unsafe to execute.

Before any tool call reaches an execution system, verify:

• the caller’s identity and permission;
• the target resource identifier;
• the resource’s tenant, project, or account scope;
• whether the requested operation is allowed in the current environment;
• whether the amount, destination, or affected object is within a business limit;
• whether an idempotency key exists for a retryable mutation;
• whether the request is a duplicate or replay;
• whether the operation requires human approval;
• whether the tool result can expose sensitive information.

A destructive or externally visible tool should not execute solely because its arguments pass JSON Schema validation. The executor should resolve the resource independently, authorize the action, and apply an idempotency policy. A Schema validates shape; it does not authenticate the caller, prove ownership, or establish that a requested action is appropriate.

Claude’s tool-use model is useful as a reminder that tool input and tool execution are separate responsibilities, but the same boundary applies to every provider. Provider-specific tool calling does not remove application-level authorization.

Sixth step: validate the meaning after parsing

Why can Schema-compliant output still contain wrong data?

Because structural validation cannot prove facts or relationships that are not encoded in the Schema. A result may contain the correct property names and primitive types while still violating application rules.

Examples include:

• startDate occurring after endDate;
• a valid account identifier belonging to a different customer;
• a currency code that conflicts with the account’s settlement currency;
• a product status that is structurally valid but impossible after the current state transition;
• a quantity that is an integer but exceeds available inventory;
• a URL that is well-formed but points to an unauthorized destination;
• a generated citation that has the expected string type but does not support the claim.

The downstream consumer should therefore run several layers of checks:

• cross-field predicates;
• reference and ownership checks;
• database foreign-key and uniqueness constraints;
• state-machine validation;
• policy and permission checks;
• factual verification against an authoritative source;
• domain-specific normalization with an audit trail.

Do not weaken the core Schema just to make model output pass. If a business rule is difficult to express in JSON Schema, document it as a separate validator and include it in the same acceptance report.

The final result should distinguish at least these dispositions:

• structurally valid and semantically accepted;
• structurally valid but rejected by business rules;
• structurally invalid;
• refused or blocked before parsing;
• unavailable because of transport or provider failure.

That distinction helps teams identify whether a failure belongs to the model, adapter, validator, policy engine, or infrastructure.

Use decision conditions to choose the release path

Use the following branch rather than forcing every provider into a single compatibility label:

• If every business-critical keyword is preserved, every adapter transformation is traceable, shared positive and negative samples produce the expected dispositions, and downstream semantic checks pass, choose the shared core Schema with provider adapters.
• If a provider cannot carry a non-critical transport rule but the same rule is enforced by a tested local validator, choose a shared business Schema plus a provider-specific transport Schema.
• If a provider drops or changes a business-critical constraint, cannot resolve a required reference, or produces an ambiguous result that the executor cannot safely authorize, block that provider integration.
• If the workflow depends on several tightly related outputs that cannot be represented consistently across endpoints, split the workflow into smaller validated stages instead of accepting a weak universal Schema.
• If the same sample produces different business dispositions across providers, hold the release until the difference is explained and approved.

A compatibility report should end with one explicit decision: approved for shared use, approved with provider-specific Schemas, or blocked and requiring workflow changes. “Mostly compatible” is not an actionable production state.

Make the acceptance report reproducible

The report should pin the artifacts that determine the result:

• core Schema identifier and version;
• declared dialect;
• provider-specific Schema versions;
• adapter revision;
• endpoint and model identifiers;
• test-set revision;
• validator implementation and configuration;
• execution date;
• environment details;
• raw response retention policy;
• expected and observed dispositions;
• open exceptions and their owners.

When a provider changes its supported subset or response behavior, rerun the complete sample set rather than only the test that originally failed. A change that appears limited to one keyword can affect wrappers, parsing, refusal handling, or downstream semantics.

For teams running repeated cross-model tests, environment reproducibility matters as much as the Schema. A remote Mac test environment can provide a separate, repeatable execution node for API clients, local validators, command-line test runners, and integration scripts. The Vuncloud Help Center can be used to review available operating guidance, while Vuncloud’s company information provides service context before an infrastructure decision.

Current setup or remote Mac testing?

A local workstation is usually the better choice when the team needs a permanent development machine, stable physical peripherals, or sustained heavy workloads that justify ownership. It becomes less attractive for a distributed test team when several engineers need isolated environments, when test batches compete with development work, or when rebuilding a clean environment repeatedly consumes engineering time.

A shared cloud runner can offer convenience, but it may introduce queueing, opaque environment changes, limited control over the operating system, and weaker reproduction of Mac-specific client behavior. Renting a Mac through Vuncloud can be a more suitable option for temporary cross-model validation when the team needs an isolated macOS environment, repeatable test execution, and access for multiple engineers without purchasing another physical machine. The Mac rental options from Vuncloud should still be compared against local ownership and other infrastructure choices, especially for long-running workloads or tests that require direct hardware access.

The decision should follow the acceptance evidence: first pin the Schema, adapters, interfaces, and sample set; then choose the environment that can reproduce failures without hiding provider or business-layer differences.