Three layers are often called “schema”
An instance schema constrains data values. An API description adds operations, transport details and responses. An agent-tool contract adds descriptions intended to help a model decide when and how to call an operation. Treating all three as interchangeable produces conversions that look correct but omit essential behavior.
XSD and JSON Schema
Both describe instance structure and constraints, but their data models differ. XSD is built around XML elements, attributes, namespaces and ordered content. JSON Schema evaluates JSON instances using vocabularies and dialects.
OpenAPI
OpenAPI combines schema objects with paths, operations, parameters, media types, authentication and responses. OpenAPI 3.1 aligns its Schema Object with JSON Schema Draft 2020-12, while the surrounding API description remains its own model.
MCP tools
An MCP tool exposes a name, description and JSON-Schema-based input definition, with optional structured output. The quality of those descriptions matters because a model uses them to choose and populate a tool.
What maps cleanly—and what does not
| Concept | XSD | JSON Schema / OpenAPI | Conversion risk |
|---|---|---|---|
| Required value | minOccurs | required | Context differs |
| Reusable definition | Named type or group | $defs and $ref | Usually representable |
| Ordered mixed content | Native XML model | No direct JSON equivalent | Lossy |
| Namespace identity | Core mechanism | URI identifiers and references | Requires a policy |
Shape does not capture all meaning
A field can be a valid string while carrying the wrong identifier system, unit, timezone or lifecycle state. Defaults can be inserted by one validator and ignored by another. An API operation can have a valid request body while requiring authorization, idempotency or preconditions that are expressed outside the instance schema.
Write these semantics as close as possible to the enforceable boundary. Use schema annotations for stable human explanation, Schematron or application validation for contextual data rules, and the API description for transport and response behavior. Agent-facing descriptions should explain side effects and selection criteria, but they must not be the only place where safety policy exists.
A safer interoperability workflow
- Identify the source data model and schema version.
- List features with no direct equivalent before conversion.
- Convert into a draft contract and preserve a loss report.
- Generate valid and invalid examples for both sides.
- Compare behavior with real validators, not only syntax.
- Version the contract and test subsequent changes for compatibility.
Use the Schema Diff to inspect basic XSD or JSON Schema changes and the OpenAPI-to-MCP readiness analyzer to audit agent-facing operation design.
What to keep with a contract release
Store the schema or description, declared dialect, canonical examples, negative fixtures and validation commands together. Include a concise compatibility statement naming the producer and consumer assumptions. For a conversion, retain the feature inventory and every known lossy mapping rather than publishing only the generated destination file.
For OpenAPI and MCP, test more than schema acceptance. Exercise authentication failure, timeouts, rate limits, empty results, partial success and side-effecting operations. A contract becomes dependable when a reviewer can reproduce both its successful path and its failure boundaries without recovering undocumented behavior from application code.
Assign ownership at every boundary
A contract needs an owner for schema releases, example data, compatibility decisions and deprecation. Consumers need a way to report an ambiguous constraint or a field they cannot process. Record which source is authoritative when XSD, prose, generated code and an API description disagree; otherwise the first production incident becomes the real specification process.