JSON Schema Preparation for Client Compatibility in WordPress 7.1

WordPress 7.1 introduces a native, shared JSON Schema preparation layer designed to bridge the gap between internal server-side schema conventions and external schema standards. WordPress has long utilized custom internal schema conventions that are highly effective for server-side validation, such as property-level boolean requirements and PHP callbacks. However, these patterns are not portable JSON Schema draft-04.

Passing raw WordPress schemas directly to external validators, custom JavaScript frontends, Model Context Protocol (MCP) integrations, or AI tool-calling declarations can trigger validation errors or accidentally expose PHP execution details. To solve this, WordPress 7.1 introduces the wp_prepare_json_schema_for_client() function, ensuring client-facing schemas remain secure, consistent, and strictly compliant with standard specifications.

The Core Problem: Internal Conventions Versus Portable Standards

Server-side validation within WordPress relies on expressive, flexible array structures. Developers frequently include execution logic directly inside schema arrays using keys like sanitize_callback, validate_callback, and arg_options. Additionally, WordPress schemas historically permitted property-level boolean flags to declare required fields, such as setting 'required' => true directly on a property array.

While these patterns streamline backend processing via functions like rest_validate_value_from_schema() or WP_Ability::validate_input(), external consumers cannot process PHP callbacks. Furthermore, strict JSON Schema draft-04 parsers reject property-level boolean requirement flags, demanding instead a top-level required array containing property name strings. Exposing unstripped schemas to REST clients or AI tool declarations risks breaking third-party parsers and leaking server implementation logic.

Introducing wp_prepare_json_schema_for_client()

The new core function wp_prepare_json_schema_for_client() acts as a serialization boundary. It accepts an internal WordPress schema array and generates a clean, portable copy intended exclusively for external consumption. The function signature is straightforward:

/**
 * Prepares a JSON Schema for clients.
 *
 * @param array<string, mixed> $schema The schema array.
 * @param string $schema_profile Optional. Name of the schema profile whose keywords should be preserved. Default 'draft-04'.
 * @return array<string, mixed> The prepared schema.
 */
wp_prepare_json_schema_for_client( array $schema, string $schema_profile = 'draft-04' ): array

Crucially, this function must never be used to overwrite the canonical schema stored on server-side objects. Plugin developers should retain the original WordPress schema for backend validation and generate a prepared copy only when transmitting data across an external boundary.

Choosing the Right Schema Profile

The preparation function accepts an optional profile argument, allowing developers to target specific validation environments. WordPress ships with two built-in profiles:

• draft-04 (Default): Designed for general-purpose external clients, frontend validation libraries, Model Context Protocol (MCP) integrations, and AI tool declarations. It preserves structural composition and reference keywords like $ref, definitions, allOf, not, dependencies, and additionalItems.
• rest-api: Restricts the retained keyword set to match the narrower vocabulary supported natively by WordPress REST API route schemas. Use this profile when preparing schemas that must align strictly with core REST endpoint conventions.

Both profiles generate valid JSON Schema draft-04 output, differing only in the permitted keyword whitelist.

// General client-facing or Ability schema preparation
$prepared_schema = wp_prepare_json_schema_for_client( $schema );

// Schema strictly matched to WordPress REST API conventions
$prepared_rest_schema = wp_prepare_json_schema_for_client( $schema, 'rest-api' );

Automatic Schema Transformations

Schema preparation runs recursively across nested object properties, array items, composition keywords, and definitions. Two primary structural transformations occur during this process: required property normalization and the removal of server-only callbacks.

For required properties, property-level boolean flags are translated into a standard Draft 4 array structure:

// Input WordPress Schema
$schema = array(
    'type' => 'object',
    'properties' => array(
        'title' => array(
            'type' => 'string',
            'required' => true,
            'sanitize_callback' => 'sanitize_text_field',
        ),
        'content' => array(
            'type' => 'string',
            'validate_callback' => 'is_string',
        ),
    ),
);

$prepared_schema = wp_prepare_json_schema_for_client( $schema );

The resulting prepared schema moves the required fields to the parent object level and strips out the PHP callback functions entirely:

// Output Prepared Schema
array(
    'type' => 'object',
    'required' => array( 'title' ),
    'properties' => array(
        'title' => array(
            'type' => 'string',
        ),
        'content' => array(
            'type' => 'string',
        ),
    ),
);

Server-side validation routines remain completely unaffected. Functions like rest_validate_value_from_schema() continue to evaluate callbacks using the original canonical schema stored on the server.

Handling Empty Object Defaults

PHP data types present a unique serialization challenge when dealing with empty arrays and objects. In PHP, an empty array serializes to an empty list [] in JSON, even if its schema declares it to be an object type:

array(
    'type' => 'object',
    'default' => array(),
)

If passed unadjusted to strict client validators, this mismatch causes validation errors. The preparation layer automatically normalizes empty object defaults so that JSON serialization produces a true empty object structure instead of an array:

{
    "type": "object",
    "default": {}
}

Abilities API and AI Client Integration

WordPress 7.1 integrates this preparation layer automatically into core subsystems, most notably the Abilities API and the AI Client module.

For the Abilities API, schemas exposed through REST endpoints under /wp-json/wp-abilities/v1/abilities now automatically deliver portable client schemas. Meanwhile, underlying methods like WP_Ability::get_input_schema() continue to return untouched server schemas for internal processing. Custom ability validation should rely on the runtime filters wp_ability_validate_input and wp_ability_validate_output introduced in WordPress 7.1 rather than schema callbacks.

Similarly, when the WordPress AI Client converts registered abilities into LLM function declarations, it automatically runs the input schema through wp_prepare_json_schema_for_client(). This guarantees that non-portable required flags and backend validation callbacks never enter AI provider function specifications.

Extending Allowed Keywords via Filters

The preparation layer determines which properties to retain by consulting an allowed keyword whitelist via wp_get_json_schema_allowed_keywords(). Developers can safely extend this list using the wp_json_schema_allowed_keywords filter if custom integrations require proprietary schema extensions:

add_filter( 'wp_json_schema_allowed_keywords', function ( $keywords, $schema_profile ) {
    if ( 'draft-04' === $schema_profile ) {
        $keywords[] = 'x-custom-extension-key';
    }
    return $keywords;
}, 10, 2 );

Custom keywords should only be injected when receiving frontend clients or downstream tools are explicitly programmed to parse them.

Primary reference: Review the original announcement for exact release details. This article is an independent explanation and does not reproduce the source text.