MCP tool definition features in Apicurio Registry

The publication rule supports recursive properties, schema-valued or boolean additionalProperties, homogeneous items, boolean subschemas, type (including unions), required, enum, const, numeric bounds and multipleOf, string length bounds, array size and uniqueness, and object property counts. It recognizes drafts 4, 6, 7, 2019-09, and 2020-12; absent $schema uses draft 7. Keywords must be valid for the declared draft. In draft 4, const (which draft 4 does not define) and the boolean exclusiveMinimum and exclusiveMaximum modifiers are outside the supported subset. The checker compares most numbers as 64-bit floating-point values, so numbers must be exactly representable at that precision, such as 0.1 or integers up to 2⁵³. A value such as 9007199254740993.0, or an integer above 2⁵³ in a numeric bound or multipleOf, is outside the supported subset and returns HTTP 422 rather than comparing equal to a neighboring value. Integers of any size inside enum and const values are compared exactly.

Schema annotations (title, description, default, examples, $comment, deprecated, readOnly, and writeOnly) do not enforce compatibility constraints. Default values do not fill missing inputs.

References ($ref, $dynamicRef, $recursiveRef, identifiers and definition containers), composition (allOf, anyOf, oneOf, not), conditionals, dependencies, tuple schemas, prefixItems, contains, unevaluated*, pattern, patternProperties, format, and other unlisted keywords are outside this publication rule’s supported subset. They are not silently discarded. If either compared schema uses one, even unchanged, the comparison fails with HTTP 422. No reference is fetched or resolved. This deliberately narrower contract does not change the JSON artifact checker or cross-tool chaining endpoint.

A known incompatible change returns HTTP 400 with a rule-violation context prefixed by /inputSchema or /outputSchema. For example, narrowing an input string reports /inputSchema/properties/query/maxLength. Input BACKWARD contexts point into the new schema; output BACKWARD contexts point into the old schema because its accepted outputs are the comparison target. FORWARD reverses those locations; FULL can report both. Invalid or unsupported schemas return HTTP 422. Neither rejection creates the candidate version or changes previously accepted content.

The engine can conservatively reject changes that accept the same values, especially when several constraints interact. A passing schema check is not proof of behavioral equivalence, runtime conformance, successful invocation, or compatibility between two different tools.

Earlier MCP tool checking compared only top-level input types, property names, and requiredness; output changes and nested constraint changes were unchecked. Version 3.4 checks the supported subset above and changes those results. Making an input optional is now backward compatible. Adding a typed optional input to an open schema is no longer automatically accepted. Stored versions are not rewritten; unsupported schemas in existing versions can prevent subsequent publication under an enabled compatibility rule.

For a release-safety demonstration, publish a tool whose input query is a string with maxLength: 10, enable BACKWARD, and propose maxLength: 5. Expect HTTP 400 and unchanged old content. Propose maxLength: 20 and expect acceptance. For an output schema, the direction is reversed. Use a disposable registry and retain the rule configuration, exact versions, responses, and retrieved content as evidence for the agent-registry graduation work (#10294). This demonstrates publication-time schema enforcement only; it is not evidence of runtime admission, authenticated invocation, or full feature graduation.