Skip to content
Skills Library
Programming · Building & coding

wp-json-schema-api

/wp-json-schema-api

Prepare, expose, and audit WordPress-authored JSON Schemas with the WordPress 7.1 JSON Schema API. Covers wp_prepare_json_schema_for_client, wp_get_json_schema_allowed_keywords, draft-04 versus rest-api profiles, required-property conversion, recursive schema cleanup, empty-object defaults, the wp_json_schema_allowed_keywords filter, and the boundary between schema publication, REST validation, sanitization, and application authorization. Use when returning schemas through REST, Abilities, AI tools, JavaScript configuration, or converting WordPress REST-style schemas for external consumers.

Licence
MIT
Last repository change
20.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Prepare, expose, and audit WordPress-authored JSON Schemas with the WordPress 7.1 JSON Schema API. Covers wp_prepare_json_schema_for_client, wp_get_json_schema_allowed_keywords, draft-04 versus rest-api profiles, required-property conversion, recursive schema cleanup, empty-object defaults, the wp_json_schema_allowed_keywords filter, and the boundary between schema publication, REST validation, sanitization, and application authorization. Use when returning schemas through REST, Abilities, AI tools, JavaScript configuration, or converting WordPress REST-style schemas for external consumers.

Original author description

Prepare, expose, and audit WordPress-authored JSON Schemas with the WordPress 7.1 JSON Schema API. Covers wp_prepare_json_schema_for_client, wp_get_json_schema_allowed_keywords, draft-04 versus rest-api profiles, required-property conversion, recursive schema cleanup, empty-object defaults, the wp_json_schema_allowed_keywords filter, and the boundary between schema publication, REST validation, sanitization, and application authorization. Use when returning schemas through REST, Abilities, AI tools, JavaScript configuration, or converting WordPress REST-style schemas for external consumers.

How it works

  1. Use the public helpers
  2. Keep server and published schemas separate
  3. Understand what preparation changes
  4. Validation, sanitization, and authorization remain separate
  5. Filter safely
  6. Review checklist
  7. Related skills
  8. References
Original SKILL.md headings · 150 lines, 742 words
SKILL.md preview
---
name: wp-json-schema-api
description: >-
  Prepare, expose, and audit WordPress-authored JSON Schemas with the WordPress
  7.1 JSON Schema API. Covers wp_prepare_json_schema_for_client,
  wp_get_json_schema_allowed_keywords, draft-04 versus rest-api profiles,
  required-property conversion, recursive schema cleanup, empty-object
  defaults, the wp_json_schema_allowed_keywords filter, and the boundary
  between schema publication, REST validation, sanitization, and application
  authorization. Use when returning schemas through REST, Abilities, AI tools,
  JavaScript configuration, or converting WordPress REST-style schemas for
  external consumers.
license: GPLv2-or-later
metadata:
  wp-skills-author: "Soczó Kristóf"
  wp-skills-contact: "mailto:lonsdale201@hotmail.com"
  wp-skills-plugin: "wordpress"
  wp-skills-plugin-version-tested: "7.1"
  wp-skills-wp-version-tested: "7.1"
  wp-skills-php-min: "7.4"
  wp-skills-last-updated: "2026-08-20"
---

# WordPress JSON Schema API

WordPress 7.1 adds a shared API for preparing WordPress-authored schemas for
clients. Its job is compatibility and safe publication: it converts a few
WordPress conventions and removes keywords outside the selected profile. It
does not validate or sanitize a value and does not authorize an operation.

## Use the public helpers

Feature-detect when WordPress 7.0 or older remains supported:

```php
if ( function_exists( 'wp_prepare_json_schema_for_client' ) ) {
	$public_schema = wp_prepare_json_schema_for_client( $schema, 'draft-04' );
} else {
	// Keep a deliberately maintained compatibility schema; do not expose
	// callbacks or blindly return the server schema.
	$public_schema = $legacy_public_schema;
}
```

The two public functions have deliberately different defaults:

- `wp_get_json_schema_allowed_keywords()` defaults to `rest-api`;
- `wp_prepare_json_schema_for_client()` defaults to `draft-04`.

Choose `rest-api` for the historical REST-exposed keyword subset. Choose
`draft-04` for a standalone client, Ability description, or AI provider that
can consume the broader Draft 4 vocabulary. An unknown profile falls back to
the REST keyword set; do not rely on misspelled profile names failing closed
with an exception.

## Keep server and published schemas separate

```php
$server_schema = array(
	'type'       => 'object',
	'properties' => array(
		'post_id' => array(
			'type'              => 'integer',
			'minimum'           => 1,
			'required'          => true,
			'sanitize_callback' => 'absint',
		),
	),
);

$public_schema = wp_prepare_json_schema_for_client(
	$server_schema,
	'draft-04'
);
```

The published result moves the per-property `required: true` marker into the
parent object's `required` array and strips the callable. Keep the original
schema for WordPress execution and the prepared copy for transport.

If the parent already has a Draft 4 `required` array, it takes precedence:
per-property booleans are removed but are not merged into that array. Make the
server contract internally consistent before publishing it.

## Understand what preparation changes

Preparation recursively walks schema-bearing keywords, removes keys not
allowed by the profile, and normalizes WordPress-specific representations. In
particular:

- an empty array used as the default of an object schema becomes a JSON object;
- per-property boolean `required` flags are removed and, when no parent
  `required` array exists, the `true` properties are collected there;
- a stray boolean `required` without an object property list is removed;
- nested `properties`, `patternProperties`, `definitions`, `dependencies`,
  `items`, `not`, `additionalProperties`, `additionalItems`, `anyOf`, `oneOf`,
  and `allOf` schemas are prepared recursively when the chosen profile permits
  those keywords;
- unknown and WordPress-only keys, including PHP callbacks, are removed.

Numeric arrays used as data, such as property-dependency lists, are preserved
instead of being mistaken for schema maps.

Read `references/profiles-and-normalization.md` for the exact profile delta and
review probes.

## Validation, sanitization, and authorization remain separate

Never treat a prepared schema as evidence that input was checked:

1. validate inbound data with the API that owns the request, such as
   `rest_validate_value_from_schema()` or the registered REST argument schema;
2. sanitize/coerce only according to that server contract;
3. perform capability and object-ownership checks separately;
4. copy allowlisted fields into the write model rather than mass-assigning a
   request object.

Adding a keyword through `wp_json_schema_allowed_keywords` only allows that
keyword to survive publication. It does not teach WordPress validators or
sanitizers how to enforce it. A plugin that adds `const`, `if`, or a custom
keyword must also own and test the corresponding validation behavior.

## Filter safely

The filter receives the allowed keyword list and profile name:

```php
add_filter(
	'wp_json_schema_allowed_keywords',
	static function ( array $keywords, string $profile ): array {
		if ( 'draft-04' !== $profile ) {
			return $keywords;
		}

		$keywords[] = 'x-acme-ui';
		return array_values( array_unique( $keywords ) );
	},
	10,
	2
);
```

Only extend the list for a namespaced, documented consumer contract. A global
filter affects every schema prepared later in the request, including core and
other plugins. Keep it deterministic, avoid removing standard keywords, and
test for cross-plugin collisions.

## Review checklist

- Confirm the target consumer and select `rest-api` or `draft-04` explicitly.
- Keep the execution schema distinct from its prepared transport copy.
- Inspect the prepared output with `wp_json_encode()`, especially empty object
  defaults and nested schemas.
- Verify parent `required` arrays and per-property markers do not disagree.
- Confirm no callable, internal metadata, secret default, or implementation
  detail survives publication.
- Validate and authorize actual inputs independently of schema preparation.
- Test custom allowed-keyword filters with other plugins active.
- Feature-detect the helpers or require WordPress 7.1.

## Related skills

- `wp-rest-api` for server route schemas and request validation.
- `wp-abilities-api` for Ability input/output contracts.
- `wp-ai-client` for structured AI output and function declarations.

## References

- WordPress 7.1 core: `wp-includes/json-schema.php`.
- WordPress REST schema helpers: `wp-includes/rest-api.php`.
- <https://make.wordpress.org/core/2026/07/31/json-schema-preparation-for-client-compatibility-in-wordpress-7-1/>
Files in this package (3)
  • SKILL.md 6 KB
  • agents/openai.yaml 1 KB
  • references/profiles-and-normalization.md 2 KB

Versions

The database has no other skills named wp-json-schema-api.

Database snapshot: 13.11.2026 · package version 34bc14f9d3f0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100wp-abilities-api
    Register WordPress Abilities: machine-readable plugin operations with JSON Schema contracts, required permission callbacks, optional REST exposure, client-side abilities, and AI/MCP-friendly discovery. Covers categories, wp_register_ability, WP_Ability::execute, REST run…
  • 90wp-abilities-api
    Use when working with the WordPress Abilities API (wp_register_ability, wp_register_ability_category, /wp-json/wp-abilities/v1/*, @wordpress/abilities) including defining abilities, categories, meta, REST exposure, and permissions checks for clients.
  • 100wp-rest-api-development
    WordPress REST API review and development guidance. Use when reviewing custom REST routes, permission_callback logic, schema design, WP_REST_Request handling, response structure, versioning, controller classes, nonce or auth usage, or when user mentions "REST API review",…
  • 90wordpress-wp-rest-api
    Use when building, extending, or debugging WordPress REST API endpoints/routes: register_rest_route, WP_REST_Controller/controller classes, schema/argument validation, permission_callback/authentication, response shaping, register_rest_field/register_meta, or exposing…
  • 100validating-api-schemas
    Validate API schemas against OpenAPI, JSON Schema, and GraphQL specifications. Use when validating API schemas and contracts. Trigger with phrases like "validate API schema", "check OpenAPI spec", or "verify schema".
  • 100validating-api-schemas
    Validate API schemas against OpenAPI, JSON Schema, and GraphQL specifications. Use when validating API schemas and contracts. Trigger with phrases like "validate API schema", "check OpenAPI spec", or "verify schema".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.