WordPress 7.1 JSON Schema Preparation for AI Clients

🇹🇷 Türkçe: Bu yazının Türkçesini oku →

In 1993 I was hand-cutting rubylith masks for a print shop in Istanbul and arguing with a Mac Plus about whether QuarkXPress and Aldus FreeHand agreed on what a colour actually was. They did not. Every hand-off between two pieces of software of that era was a small negotiation, and the negotiation was almost never written down. Thirty-plus years on, most of the industry has learned the lesson: if two systems have to talk, the shape of what they exchange belongs in a machine-readable contract, not a phone call.

Which is why the dev note that landed on Make/Core last Friday is worth ten minutes of your afternoon even if you have never once thought about JSON Schema. WordPress 7.1 is quietly adding the layer that lets its own internal schemas be handed to the outside world — REST clients, AI providers, MCP integrations — without a phone call, and without shipping half of PHP by accident.

The change is small. The implication is large. Here is what actually shipped, and what I would do about it before the beta cycle closes.

What is actually new

Milana Cap’s dev note JSON Schema preparation for client compatibility in WordPress 7.1, published July 31 and peer-reviewed by Aaron Jorbin, documents a new function that lives in wp-includes/json-schema.php:

wp_prepare_json_schema_for_client(
    array $schema,
    string $schema_profile = 'draft-04'
): array

The function converts a WordPress internal schema into a portable, client-facing representation. Concretely it does four things. It moves per-property required => true declarations into the object-level required array where JSON Schema Draft 4 expects them. It strips server-only keywords — sanitize_callback, validate_callback, arg_options — that would leak PHP callbacks the moment they left the process. It walks the schema recursively, so properties, patternProperties, definitions, dependencies, items, additionalItems, additionalProperties, anyOf, oneOf, allOf and not all get the same treatment. And it converts empty PHP arrays into the {} that JSON validators actually expect for empty objects.

Two schema profiles ship in the box. draft-04 is the default and preserves the broader vocabulary — $ref, definitions, allOf, not, dependencies, additionalItems — for standalone consumers like AI tool declarations, MCP endpoints, and frontend validators. rest-api is the narrower profile that matches WordPress REST API conventions. If you need something in between, the new wp_json_schema_allowed_keywords filter (with wp_get_json_schema_allowed_keywords() as its helper) lets you customise the keyword set per profile without patching core.

Two internal consumers are already wired up on your behalf. The /wp-json/wp-abilities/v1/abilities endpoint now returns prepared schemas in its REST responses (changeset [62591]), while WP_Ability::get_input_schema() and WP_Ability::get_output_schema() keep returning the original schema to server-side PHP — this is strictly an output-boundary transformation. And the AI Client that ships with core now prepares input schemas with the draft-04 profile before converting them into function declarations for the model provider. All of this is tracked under Trac ticket #64955 (Abilities API: Add schema compiler for AI tool calling compatibility), with earlier changesets [62449] and [62549] laying the groundwork.

What is explicitly not shipping in 7.1: provider-specific schema adaptation. OpenAI’s strict mode wants additionalProperties: false on every object and refuses oneOf; Anthropic normalises oneOf into anyOf. Cap and the reviewers put that work into a follow-up (WordPress/php-ai-client#256) rather than baking vendor quirks into the core function. That is the right call, and it is worth naming — this API is generic, not opinionated about any one model provider.

WordPress 7.1 GA is still August 19, 2026, with RC1 on August 5 and RC2 on August 12. So you have two weeks to test this on staging before it lands under every site you run.

Why it matters for WordPress and WooCommerce people

WordPress has accumulated its own JSON Schema dialect over the last decade. It is not portable, and everyone who has ever tried to hand a REST schema to a frontend validator or an AI tool has hit the same wall — the property-level required => true shorthand blows up in Draft 4 parsers, and callback keywords sail out of the response and confuse consumers that expect them to be data. Every agency I know has a little helper somewhere in the toolbox that walks a WordPress schema and strips these before shipping. Core has now written that helper, upstream, once, and it will be maintained by the same team that maintains the schemas themselves.

That matters more than the code diff suggests. When the layer that produces the schema and the layer that prepares it for clients are the same team, drift stops. The moment a WordPress convention changes on the server side, the client-side preparation moves with it. Compare that to the current situation, where every plugin doing this work is on its own release schedule, catches drift months late, and inherits none of the review that a Make/Core dev note gets.

The AI angle is the load-bearing one. WordPress 7.1’s Abilities API improvements dev note, also published July 31 by the same author, is worth reading alongside this one — it names the endpoints, the validation hooks (wp_ability_validate_input, wp_ability_validate_output), and the invocation lifecycle action (wp_ability_invoked) that will be feeding schema-typed calls into models. If those schemas are not portable, the tool-calling story falls apart at the first provider. With wp_prepare_json_schema_for_client() in place, the tool-calling story starts working the day 7.1 hits GA.

For WooCommerce specifically, this is the plumbing you will not think about until the day you try to expose an ability like “list the last twenty orders” to an internal agent, a customer-service assistant, or an MCP-compatible client, and the schema round-trip finally does not need a custom PHP shim to survive contact with the outside world. Core doing this work upstream also means WooCommerce extensions — the ones exposing Store API endpoints, the ones registering abilities, the ones layering B2B logic on top of checkout — get portable schemas for free the moment they consume the Abilities API surface.

What I would do (or not do) about it

Four practical moves for the two weeks between now and RC1.

First, if you maintain any plugin or custom endpoint that exposes a WordPress schema to a client — REST response, JavaScript config, MCP declaration, AI function declaration — grep it for the private helpers you wrote to strip sanitize_callback and rewrite required. Every one of those is now a candidate for a five-line diff that calls wp_prepare_json_schema_for_client() and deletes the helper. Do the grep now on staging, ship the diff on a WordPress 7.1 Beta 4 or Playground blueprint, keep a version-guarded fallback for 7.0 users, and stop maintaining code the platform has taken over.

Second, keep Cap’s critical rule pinned above your monitor: keep the canonical WordPress schema for server-side use; prepare only a copy for clients. The prepared schema is a projection. It is not the truth. If you mutate the original in place because it is the same array reference, server-side validation loses the callbacks it needs and you spend a weekend narrowing why permission checks stopped firing. Copy before you prepare. Every time.

Third, do not build a provider-specific compiler on top of this yet. The upstream follow-up for OpenAI strict mode and Anthropic normalisation is tracked on the php-ai-client repo, and the shape of it will land in a release after 7.1. Anything you write today to bolt additionalProperties: false onto every object will be technical debt the day core ships its own vendor-aware profile. Register a profile of your own via wp_json_schema_allowed_keywords if you must, but do not rewrite the whole pipeline.

Fourth, do not stack the 7.1 upgrade cycle on top of the WooCommerce 11.0 window. WooCommerce 11.0 GA is currently re-scheduled for August 4 after RC1 surfaced a fatal in a new performance feature, and WordPress 7.1 GA is August 19. Two weeks apart, on the same production estate, is comfortable. In the same triage queue on the same afternoon is how you spend a Saturday narrowing which one broke your Store API responses. Keep the change windows sequential.

One thing not to do: do not install any plugin whose pitch is “adds a UI to configure JSON Schema preparation profiles”. The whole surface is one function call and a filter. Wrapping that in a settings screen creates exactly the technical debt this dev note was written to retire — and thirty years of watching this pattern repeat says the plugin will still be on the shelf in 2029 while the platform has moved on twice.

The unglamorous plumbing releases are the ones that hold up five years later. This is one of them. Put ten minutes on Wednesday’s calendar, run the grep, and let core carry the code you were carrying yourself.