What Is JSON Schema? Why Are OpenAI, Gemini, Claude And MCP Increasingly Relying On JSON Schema?

This guide explains why JSON Schema has become the contract layer for AI Agent outputs, tool parameters, and MCP tools. We compare provider-specific support, separate structural validation from business validation, and show how to maintain an internal schema with controlled adapters.

JSON Schema should be treated as the shared contract for AI Agent data, not as a universal copy-and-paste format. We recommend maintaining one internal canonical schema, then generating provider-specific versions for OpenAI, Gemini, Claude, and MCP.

This guide is for:

• AI application developers defining structured outputs and tool parameters.
• Platform engineers reusing contracts across multiple models and APIs.
• Test engineers building validation, compatibility, and regression checks.

Why JSON Schema matters inside an AI Agent

An AI Agent moves data through several boundaries:

• User request to model output.
• Model decision to tool arguments.
• Tool executor to external API.
• API response to model context.
• Model result to application code.

Each boundary can fail differently. A field can be missing. A number can arrive as text. An enum can contain an unsupported value. A valid identifier can point to the wrong account. A tool can receive structurally correct arguments but still lack permission to perform the operation.

JSON Schema handles the structural part.

The JSON Schema specification defines a machine-readable way to describe JSON structure, validation rules, annotations, and reusable references. The current specification family includes Draft 2020-12, but AI platforms often support only selected parts of the broader standard.

The important distinction is simple:

Valid JSON only proves that a parser can read the syntax. Schema validation checks whether the data follows the expected contract.

For example, this payload is valid JSON:

{
  "status": "paid",
  "amount": "120"
}

It may still fail a schema requiring:

• status to be one of pending, paid, or refunded.
• amount to be a number.
• orderId to be present.
• No unknown properties.

That distinction matters because downstream code rarely consumes “any valid JSON.” It expects a known object shape.

What the main keywords do in an Agent pipeline

For AI workloads, the most useful schema concepts are operational rather than encyclopedic.

• type controls the basic data type.
• properties describes object fields.
• required identifies fields that must exist.
• enum limits a value to an approved set.
• items describes array elements.
• additionalProperties controls unknown object fields.
• $ref and $defs support reusable definitions.
• description gives the model and developers semantic context.
• format can describe syntax such as dates, but it does not automatically verify that a real business object exists.

The JSON Schema getting-started guide demonstrates the basic workflow: define a schema, validate an instance, and inspect the result.

A practical AI contract should answer three separate questions:

• What fields may exist?
• What values are structurally allowed?
• What must the application verify separately?

The third question is where many Agent systems fail.

First step: use Schema for structured model output

Structured output is the simplest place to see the value of a schema.

Suppose an Agent extracts an incident from an email. The application may require:

{
  "type": "object",
  "properties": {
    "severity": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    },
    "summary": {
      "type": "string"
    },
    "affectedServices": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": ["severity", "summary", "affectedServices"],
  "additionalProperties": false
}

The schema does not make the model’s conclusion correct. It makes the result predictable enough for application code to parse.

OpenAI Structured Outputs supports JSON Schema-based output formats, but strict mode supports only a provider-defined subset. The OpenAI Structured Outputs documentation describes the supported approach and its limitations.

Gemini Structured Output also exposes a documented subset rather than the entire JSON Schema vocabulary. The Gemini structured output documentation describes supported types, fields, enums, and other constraints.

This creates a useful engineering rule:

A schema that is valid under Draft 2020-12 is not automatically valid for a model provider’s structured-output interface.

The model endpoint may reject the request before generation. It may ignore an annotation. It may accept the schema but provide weaker guarantees than the application assumes.

Structured output is not business truth

Consider an invoice extraction task.

Schema validation can confirm:

• invoiceDate is a string.
• currency is an allowed enum.
• total is a number.
• lineItems is an array.
• Required fields are present.

Application validation must still confirm:

• The date actually exists on the calendar.
• The invoice belongs to the expected customer.
• The total matches the line-item calculation.
• The currency is accepted for that account.
• The invoice state can legally move from draft to paid.

Schema validation describes structure. It does not perform every semantic or domain check.

A passing schema result means “the payload has an acceptable shape.” It does not mean “the payload is safe, authorized, or factually correct.”

Second step: use Schema for Function Calling parameters

Function Calling and tool use introduce a different contract.

The schema no longer describes the final answer. It describes the arguments that the model may request from an executor.

Example:

{
  "name": "get_order",
  "description": "Retrieve an order visible to the authenticated account.",
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "description": "The order identifier supplied by the application context."
      }
    },
    "required": ["orderId"],
    "additionalProperties": false
  }
}

The data flow becomes:

• The model selects a tool.
• The model generates arguments.
• The gateway validates those arguments.
• The executor checks identity and permissions.
• The executor calls the real API.
• The result is returned to the model or application.

Schema is essential at the third step. It is not sufficient for the fourth.

A schema cannot:

• Grant an API token.
• Confirm that an order exists.
• Confirm that the current user owns the order.
• Prevent a destructive action by itself.
• Prove that the tool description is honest.
• Guarantee that the model selected the correct tool.

Claude’s tool interface uses an input_schema object to describe expected parameters. The Claude tool-use documentation also separates tool selection from execution. The client or host is responsible for running the requested tool and returning the result.

This separation is valuable for architecture. We can keep the model-facing contract stable while placing authorization, rate limits, resource checks, and audit logging inside the executor.

A reliable tool gateway should reject at least four classes of failure:

• Missing required arguments.
• Wrong primitive types.
• Unsupported enum values.
• Unknown properties that the executor does not understand.

The gateway should then run business checks after structural validation. These checks belong in code or service policy, not in the schema alone.

Third step: understand MCP inputSchema and outputSchema

The Model Context Protocol uses JSON Schema as part of its tool model. The MCP tools specification defines tool discovery, invocation, input schemas, output schemas, and structured content.

For an MCP tool, inputSchema describes the expected arguments:

{
  "name": "search_documents",
  "description": "Search documents available to the current workspace.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string"
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 20
      }
    },
    "required": ["query"]
  }
}

The client discovers the tool through tools/list. It then sends a tools/call request with the tool name and arguments.

outputSchema serves a different purpose. It describes the structure of a structured result. The server places that result in structuredContent. The client can validate it before passing it to later Agent steps.

A typical result may include:

{
  "content": [
    {
      "type": "text",
      "text": "{\"matches\":[{\"documentId\":\"doc-17\"}]}"
    }
  ],
  "structuredContent": {
    "matches": [
      {
        "documentId": "doc-17"
      }
    ]
  }
}

The protocol can carry human-readable content and structured machine-readable content at the same time. This supports clients with different parsing capabilities.

MCP does not replace model-side tool selection. It defines discovery, metadata, invocation, and result transport. The host still decides which model receives the tool definitions. The model still decides whether a tool is relevant, unless the host applies its own policy.

The distinction matters when an Agent supports both native provider tools and MCP tools. The same internal tool definition may need two adapters:

• A provider adapter for model-side tool selection.
• An MCP adapter for protocol-level discovery and execution.

OpenAI, Gemini, Claude, and MCP are not identical

The phrase “supports JSON Schema” hides the most important implementation detail: supported subsets vary by interface.

OpenAI Structured Outputs focuses on making generated output follow a supplied schema under strict mode, but strict mode is not the same as unrestricted Draft 2020-12 validation.

Gemini Structured Output documents a provider-specific subset and distinguishes structured output from Function Calling. Structured output formats the final response. Function Calling lets the model request an action during a conversation.

Claude tool definitions place the schema inside input_schema. Tool descriptions also influence model decisions, so a syntactically correct schema with a vague description can still produce poor tool routing.

MCP uses schemas at the protocol layer. inputSchema describes tool arguments. outputSchema describes structured results when supplied. structuredContent carries the structured result.

These are related concepts, but they are not interchangeable interfaces.

What this means for compatibility

A portable common subset usually favors:

• Objects.
• Arrays.
• Strings.
• Numbers and integers.
• Booleans.
• Null where the target interface supports it.
• Required fields.
• Simple enums.
• Basic descriptions.
• Explicit property definitions.

Compatibility becomes less predictable when a contract depends heavily on:

• Deep $ref graphs.
• Complex composition.
• Recursive definitions.
• Conditional subschemas.
• Provider-specific format behavior.
• Unions with different nullability rules.
• Advanced unevaluated-property controls.
• Keywords ignored by the target API.

That does not mean the advanced features are useless. It means they belong in the canonical contract unless a provider adapter can safely translate them.

Build a provider adapter instead of weakening the core contract

The safest architecture has three layers.

Layer A: canonical schema

This is the internal source of truth. It should contain:

• Stable field names.
• Explicit primitive types.
• Required fields.
• Enumerated states.
• Reusable definitions.
• Version metadata.
• Representative valid and invalid fixtures.
• Business validation notes outside the schema.

This layer can use the full schema vocabulary supported by the organization’s validator and runtime.

Layer B: provider schema

This is a generated version for a specific interface.

Examples include:

• OpenAI strict structured output.
• Gemini structured output.
• Claude tool input.
• MCP inputSchema.
• MCP outputSchema.

The adapter may remove unsupported keywords, flatten references, simplify unions, or change optional-field handling. Every transformation must be recorded. Silent changes create debugging problems later.

Layer C: runtime policy

This layer performs checks that Schema cannot safely own:

• Authentication.
• Authorization.
• Tenant isolation.
• Resource ownership.
• Date existence.
• Amount limits.
• State transitions.
• Idempotency.
• Rate limits.
• Confirmation for destructive operations.

This is also where the system decides whether to retry, reject, ask for clarification, or fall back to a human.

A useful compatibility record should include:

• Canonical schema identifier.
• Provider name.
• Interface name.
• Model or API version.
• Generated schema identifier.
• Removed or transformed keywords.
• Fixture results.
• Validation library version.
• Review date.

We recommend treating the provider adapter as production code. It deserves pull requests, test coverage, and rollback support.

Schema governance for production Agents

A working contract needs more than a JSON file in a repository.

Naming and ownership

Use names that describe domain meaning rather than model behavior. OrderLookupRequest is more durable than ClaudeToolInput or GeminiResponse.

Assign an owner to every high-value schema. The owner reviews changes, maintains fixtures, and confirms whether a field can be removed.

Versioning

Use explicit schema identifiers. A breaking change may include:

• Removing a required field.
• Changing a field type.
• Renaming an enum value.
• Changing an object from open to closed.
• Altering the meaning of a status.
• Making an optional field required.

Adding an optional field is often easier to roll out, but it still needs consumer review. A provider adapter can also introduce a breaking change even when the canonical schema remains stable.

Compatibility fixtures

Every important schema should have:

• A minimal valid payload.
• A complete valid payload.
• A missing-required-field case.
• A wrong-type case.
• An invalid-enum case.
• An unknown-property case.
• A business-invalid case that passes structural validation.

The last fixture is important. It proves that structural and business validation are separate gates.

Continuous validation

A CI pipeline should validate:

• The schema against its meta-schema.
• All fixtures against the canonical version.
• All generated provider versions.
• Tool arguments before execution.
• Structured tool results before downstream processing.
• Old payloads against the new consumer.
• New payloads against supported older consumers.

Teams maintaining schema tests, generation scripts, or macOS-specific build automation can also review ZekVPS Mac support when a stable remote execution node is part of the test plan.

A decision table for choosing the right contract

The table below is our engineering recommendation. The ratings are decision guidance, not vendor benchmarks.

The correct selection is conditional:

• If the problem is parser stability, start with structured output.
• If the model must request an action, define tool parameters.
• If tools must be discoverable across hosts, expose MCP metadata.
• If several providers consume the same object, create a canonical schema and adapters.
• If money, identity, permissions, or state transitions are involved, add runtime validation.

A practical implementation sequence

First: define the object independently of the model

Write the schema around the domain object. Avoid provider-specific field names. Decide which fields are required and which values are enumerated.

Second: mark business rules separately

For each field, state whether the rule is structural or semantic. For example, amount being a number is structural. The amount being below an account limit is semantic.

Third: generate provider versions

Create one adapter per interface. Do not assume that a schema accepted by one model endpoint will be accepted by another.

Fourth: validate before execution

Tool arguments should pass schema validation before entering the executor. The executor should then perform authorization and resource checks.

Fifth: validate results twice

First validate the returned JSON against the output schema. Then validate domain meaning. This is essential for order systems, deployment tools, billing operations, and account administration.

Sixth: record interface changes

When a provider changes its supported subset, update the adapter and fixtures. Keep the model, API version, dialect, and test date in the compatibility record.

Our rule is simple: if a schema conversion cannot be explained in a review, it should not be deployed automatically.

What JSON Schema cannot solve

A schema is a contract. It is not an authority system.

It cannot prove that:

• The model understood the user’s intent.
• The selected tool was appropriate.
• The requested resource exists.
• The caller owns the resource.
• A date is real in the business calendar.
• A payment has settled.
• A deployment is safe.
• A returned document is factually accurate.
• A tool description matches actual behavior.

For those cases, add explicit controls:

• Policy checks.
• Permission checks.
• Database lookups.
• Idempotency keys.
• Human confirmation.
• Audit logs.
• Rate limiting.
• Rollback procedures.
• Domain-specific validators.

MCP tool execution should also support human review when an operation can change an external system. Tool metadata can inform a client, but metadata should not be treated as a security guarantee.

That boundary should be visible in the architecture diagram. Otherwise, teams tend to place too much trust in a passing validation result.

Final recommendation for multi-model teams

JSON Schema is worth adopting when an AI Agent crosses application, model, tool, API, and test boundaries. The value is not the syntax. The value is a shared contract that lets each layer reject malformed data early.

The implementation choice is clear:

• Keep a canonical internal schema.
• Generate simpler provider versions.
• Record every transformation.
• Validate tool inputs before execution.
• Validate structured outputs before reuse.
• Run business checks after structural checks.
• Pin provider and protocol versions in regression tests.

A single schema copied directly into every interface is attractive but fragile. OpenAI, Gemini, Claude, and MCP expose different schema surfaces. Treating them as identical will eventually produce rejected requests, ignored constraints, or false confidence in validation.

For teams running continuous schema generation, compatibility tests, and macOS build workflows, a local machine can create three recurring problems: shared hardware contention, inconsistent developer environments, and limited access to a clean rollback state. A remote Mac setup can make those jobs easier to isolate and repeat.

Teams evaluating that option can review ZekVPS Mac VPS environments, then decide based on workload duration, required physical interfaces, and whether the test runner needs a persistent macOS node. For short-lived validation jobs and parallel CI experiments, renting a Mac from ZekVPS can be more practical than purchasing dedicated hardware before the workload is stable.