[wp-trac] [WordPress Trac] #64955: Abilities API: Add schema compiler for AI tool calling compatibility

[WordPress Trac]

#64955: Abilities API: Add schema compiler for AI tool calling compatibility
-------------------------+---------------------------------
 Reporter:  gziolo       |      Owner:  (none)
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  AI           |    Version:  6.9
 Severity:  normal       |   Keywords:  abilities ai-client
  Focuses:  rest-api     |
-------------------------+---------------------------------
 The [https://developer.wordpress.org/apis/abilities-api/ Abilities API]'s
 `input_schema` and `output_schema` use WordPress's draft-04-style JSON
 Schema conventions. When these schemas are consumed by AI agents — via the
 [https://make.wordpress.org/core/2026/03/24/introducing-the-ai-client-in-
 wordpress-7-0/ AI Client], the [https://github.com/WordPress/mcp-adapter
 MCP adapter], or browser-based agents — they must conform to the
 constrained JSON Schema subset that AI providers accept for strict tool
 calling / structured outputs.

 AI providers like [https://developers.openai.com/api/docs/guides
 /structured-outputs OpenAI], [https://platform.claude.com/docs/en/build-
 with-claude/structured-outputs Anthropic], and [https://cloud.google.com
 /vertex-ai/generative-ai/docs/reference/rest/v1beta1/FunctionDeclaration
 Google] implement constrained decoding — they compile tool schemas into a
 grammar that restricts token generation at inference time. This means they
 only accept **structural** keywords (`type`, `properties`, `required`,
 `enum`, `anyOf`) and reject or strip **validation** keywords (`minimum`,
 `maxLength`, `pattern`, `format`). No provider conforms to any single JSON
 Schema draft; their supported subset is roughly "draft-04 structural
 keywords plus `$defs` and `const` from later drafts, minus all value-level
 assertion keywords."

 WordPress's JSON Schema conventions diverge from this subset in six areas:

  1. `required` predominantly uses draft-03 per-property syntax
 (`'required' => true`); AI providers only understand the draft-04 array
 syntax. The client-side AJV validator also does not enforce draft-03
 syntax.
  2. `additionalProperties` defaults to `true` when absent; OpenAI requires
 `false` on every object in strict mode.
  3. `oneOf` is used; OpenAI rejects it (only `anyOf` accepted), Anthropic
 normalizes it to `anyOf`.
  4. Validation keywords (`minimum`, `maxLength`, `pattern`, `format`) are
 stripped or rejected by AI providers, though they remain enforced by
 WordPress's validators.
  5. WordPress-only keywords (`context`, `readonly`, `arg_options`) are
 meaningless to AI consumers.
  6. `definitions` and `$ref` (draft-04 schema composition keywords) are
 not in the
 [https://developer.wordpress.org/reference/functions/rest_get_allowed_schema_keywords/
 allowed keywords list], preventing their use in ability schemas.

 Currently, no component in the WordPress AI stack transforms schemas for
 provider compatibility. The AI Client passes ability schemas verbatim to
 the [https://github.com/WordPress/php-ai-client PHP AI Client SDK], which
 treats them as opaque payloads. The three featured provider plugins
 ([https://github.com/WordPress/ai-provider-for-openai OpenAI],
 [https://github.com/WordPress/ai-provider-for-anthropic Anthropic],
 [https://github.com/WordPress/ai-provider-for-google Google]) handle
 authentication and API formatting but do not transform schemas. This means
 ability schemas authored by plugin developers flow through to AI provider
 APIs unchanged, where they may be rejected or silently degraded.

 Server-side abilities are validated on both client (AJV draft-04, with no
 type coercion) and server (`rest_validate_value_from_schema`, with type
 juggling), creating a natural strictness gradient: AI compiled schema
 (strictest) → client-side AJV (strict) → server-side PHP (most
 permissive). Because the compiler's transformations only narrow what's
 accepted, values conforming to the compiled schema automatically pass both
 existing validators without any changes to either validation layer.

 == Proposed solution ==

 Introduce `wp_compile_ability_schema_for_ai()` — a public function that
 transforms a canonical ability schema into an AI-compatible variant at the
 output boundary:

  * Normalizes `required` from draft-03 per-property to draft-04 array
 syntax.
  * Sets `additionalProperties: false` on all object nodes.
  * Converts `oneOf` to `anyOf`.
  * Relocates validation keywords (`minimum`, `maxLength`, etc.) into
 property `description` text as soft guidance for the model, while
 WordPress's validators continue to enforce them.
  * Strips WordPress-only keywords (`context`, `readonly`, `arg_options`).
  * Maps `definitions` → `$defs` in output for AI providers that expect the
 modern keyword name.
  * Accepts a `$target` parameter for provider-specific behavior (`openai`,
 `anthropic`, `google`, `default`).
  * Is filterable via `wp_ability_schema_compiled`.

 The compiler is a server-side concern, invoked at AI-facing boundaries:
 the AI Client (before PHP AI Client SDK hand-off), and optionally by
 standalone adapters like the MCP adapter. The canonical schema remains
 unchanged for REST API consumers. The compiled schema never reaches the
 client-side store.

 Additionally:

  * Add a `wp_rest_allowed_schema_keywords` filter to
 [https://developer.wordpress.org/reference/functions/rest_get_allowed_schema_keywords/
 rest_get_allowed_schema_keywords()].
  * Add `definitions` and `$ref` to the allowed keywords list for output
 passthrough.
  * Integrate the compiler into the AI Client with the `$target` derived
 from the active provider plugin.

 No changes to existing validation behavior on either client or server.

 == Related ==

  * #64591 — Add WP AI Client and corresponding connectors screen
  * #56152 — `readonly` vs `readOnly` casing
  * #51025 — `anyOf` and `oneOf` support (landed in WP 5.6)
  * #48818 — `required` v4 array syntax support (landed in WP 5.5)
  * #38531 — Array/object schema validation and sanitization
  * [https://developer.wordpress.org/rest-api/extending-the-rest-
 api/schema/ REST API Schema Handbook]
  * [https://developers.openai.com/api/docs/guides/structured-outputs
 OpenAI Structured Outputs] — Supported schemas and strict mode
 requirements
  * [https://platform.claude.com/docs/en/build-with-claude/structured-
 outputs Anthropic Structured Outputs] — JSON Schema limitations
  * [https://cloud.google.com/vertex-ai/generative-
 ai/docs/reference/rest/v1beta1/FunctionDeclaration Google Gemini Function
 Declarations] — Schema support
  * [https://modelcontextprotocol.io/docs/concepts/tools MCP Tools
 Specification] — Tool schema format

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64955>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform