- md5
- a832931e83b3683e38ae6498a9e75501
- sha1
- b56be1fdca82c5a560b01f6510ba7314a925055c
- sha256
- f4dee25f01f2050d3e7e365c6b984e06284101a1cecf98cf8786ebc6f7744e28
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369
<?php
/**
* JSON Schema API: shared functions for working with JSON Schema.
*
* @package WordPress
* @subpackage JSON_Schema
* @since 7.1.0
*/
/**
* Gets the JSON Schema keywords allowed for a given schema profile.
*
* Use this when preparing a schema that will be consumed outside of
* WordPress's server-side validation, such as by REST clients, frontend code,
* or AI providers.
*
* The 'rest-api' profile returns the subset of JSON Schema draft-04 keywords
* that the REST API has historically exposed. The 'draft-04' profile preserves
* the larger draft-04 vocabulary used by clients that can consume standalone
* schemas.
*
* Allowing a keyword to be exposed does not make WordPress validate or
* sanitize values against it.
*
* @since 7.1.0
*
* @param string $schema_profile Optional. Name of the schema profile to get keywords for.
* Accepts 'rest-api' or 'draft-04'. Any other value falls
* back to the 'rest-api' profile. Default 'rest-api'.
* @return string[] Allowed JSON Schema keywords.
*/
function wp_get_json_schema_allowed_keywords( string $schema_profile = 'rest-api' ): array {
$rest_keywords = rest_get_allowed_schema_keywords();
$keywords_by_profile = array(
'rest-api' => $rest_keywords,
'draft-04' => array_merge(
array(
'$schema',
'id',
'$ref',
),
$rest_keywords,
array(
'required',
'allOf',
'not',
'definitions',
'dependencies',
'additionalItems',
)
),
);
$allowed_keywords = $keywords_by_profile[ $schema_profile ] ?? $rest_keywords;
/**
* Filters the JSON Schema keywords allowed for a given schema profile.
*
* Use this to decide which keywords may be exposed to clients for a profile.
* It does not make WordPress validate or sanitize values against the keyword.
*
* @since 7.1.0
*
* @param string[] $allowed_keywords Allowed JSON Schema keywords.
* @param string $schema_profile The schema profile the keywords are for.
*/
return apply_filters( 'wp_json_schema_allowed_keywords', $allowed_keywords, $schema_profile );
}
/**
* Prepares a JSON Schema for clients.
*
* Converts WordPress-specific schema conventions and removes unsupported
* keywords so clients can interpret the schema using the selected profile.
*
* Applies the same preparation to nested schemas. Existing default values
* are normalized according to their schemas so empty objects encode as `{}`
* rather than `[]`, including within nested default values.
*
* @since 7.1.0
*
* @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.
*/
function wp_prepare_json_schema_for_client( array $schema, string $schema_profile = 'draft-04' ): array {
$allowed_keywords = array_fill_keys( wp_get_json_schema_allowed_keywords( $schema_profile ), true );
return _wp_prepare_json_schema_for_client_with_allowed_keywords( $schema, $allowed_keywords );
}
/**
* Prepares a JSON Schema for clients using a given keyword lookup.
*
* Normalizes schema conventions and default values throughout nested schemas
* while retaining only the allowed keywords.
*
* @since 7.1.0
* @access private
*
* @param array<string, mixed> $schema The schema array.
* @param array<string, true> $allowed_keywords Lookup map of allowed JSON Schema keywords.
* @return array<string, mixed> The prepared schema.
*/
function _wp_prepare_json_schema_for_client_with_allowed_keywords( array $schema, array $allowed_keywords ): array {
if ( array_key_exists( 'default', $schema ) ) {
$schema['default'] = wp_prepare_json_value_for_client( $schema['default'], $schema );
}
$schema = array_intersect_key( $schema, $allowed_keywords );
/*
* Collect draft-03 per-property `required: true` flags into a draft-04
* `required` array of property names on the parent object schema.
*
* This mirrors rest_validate_object_value_from_schema(), where a draft-04
* `required` array takes precedence: when one is present, per-property
* booleans are ignored during validation. They are therefore left out of
* the array here as well (but still stripped from the output) so the
* published schema describes exactly what gets enforced.
*/
if ( isset( $schema['properties'] ) && is_array( $schema['properties'] ) ) {
$has_required_array = isset( $schema['required'] ) && is_array( $schema['required'] );
$required = array();
foreach ( $schema['properties'] as $property => &$property_schema ) {
if ( is_array( $property_schema ) && ! wp_is_numeric_array( $property_schema ) && isset( $property_schema['required'] ) && is_bool( $property_schema['required'] ) ) {
if ( ! $has_required_array && true === $property_schema['required'] ) {
$required[] = (string) $property;
}
unset( $property_schema['required'] );
}
}
unset( $property_schema );
/*
* Property keys are unique, so the collected list needs no deduplication.
* When a draft-04 array is already present, leave it untouched.
*/
if ( ! $has_required_array && count( $required ) > 0 ) {
$schema['required'] = $required;
}
}
/*
* A boolean `required` outside of an object's property list has no draft-04
* equivalent, so drop it rather than emit an invalid keyword.
*/
if ( isset( $schema['required'] ) && is_bool( $schema['required'] ) ) {
unset( $schema['required'] );
}
/*
* Sub-schema maps: keys are user-defined, values are sub-schemas.
* Note: 'dependencies' values can also be property-dependency arrays
* (numeric arrays of strings) which are skipped via wp_is_numeric_array().
*/
foreach ( array( 'properties', 'patternProperties', 'definitions', 'dependencies' ) as $keyword ) {
if ( isset( $schema[ $keyword ] ) && is_array( $schema[ $keyword ] ) ) {
foreach ( $schema[ $keyword ] as $key => $child_schema ) {
if ( is_array( $child_schema ) && ! wp_is_numeric_array( $child_schema ) ) {
$schema[ $keyword ][ $key ] = _wp_prepare_json_schema_for_client_with_allowed_keywords( $child_schema, $allowed_keywords );
}
}
}
}
// Single sub-schema keywords.
foreach ( array( 'not', 'additionalProperties', 'additionalItems' ) as $keyword ) {
if ( isset( $schema[ $keyword ] ) && is_array( $schema[ $keyword ] ) && ! wp_is_numeric_array( $schema[ $keyword ] ) ) {
$schema[ $keyword ] = _wp_prepare_json_schema_for_client_with_allowed_keywords( $schema[ $keyword ], $allowed_keywords );
}
}
// Items: single schema or tuple array of schemas.
if ( isset( $schema['items'] ) && is_array( $schema['items'] ) ) {
if ( ! wp_is_numeric_array( $schema['items'] ) ) {
$schema['items'] = _wp_prepare_json_schema_for_client_with_allowed_keywords( $schema['items'], $allowed_keywords );
} else {
foreach ( $schema['items'] as $index => $item_schema ) {
if ( is_array( $item_schema ) && ! wp_is_numeric_array( $item_schema ) ) {
$schema['items'][ $index ] = _wp_prepare_json_schema_for_client_with_allowed_keywords( $item_schema, $allowed_keywords );
}
}
}
}
// Array-of-schemas keywords.
foreach ( array( 'anyOf', 'oneOf', 'allOf' ) as $keyword ) {
if ( isset( $schema[ $keyword ] ) && is_array( $schema[ $keyword ] ) ) {
foreach ( $schema[ $keyword ] as $index => $sub_schema ) {
if ( is_array( $sub_schema ) && ! wp_is_numeric_array( $sub_schema ) ) {
$schema[ $keyword ][ $index ] = _wp_prepare_json_schema_for_client_with_allowed_keywords( $sub_schema, $allowed_keywords );
}
}
}
}
return $schema;
}
/**
* Prepares a value for JSON encoding according to its schema.
*
* Preserves the distinction between JSON objects and arrays by converting
* empty PHP arrays to objects where the schema identifies them as objects.
* Nested properties and items are prepared according to their schemas.
* Empty arrays remain arrays when a matching schema allows them.
*
* Prepares the representation of existing values without inserting defaults
* or performing full JSON Schema validation.
*
* @since 7.2.0
*
* @param mixed $value The value to prepare.
* @param array<string, mixed> $schema The schema describing the value.
* @return mixed The value prepared for JSON encoding.
*/
function wp_prepare_json_value_for_client( $value, array $schema ) {
if ( $value instanceof JsonSerializable ) {
$value = $value->jsonSerialize();
}
if ( ! is_array( $value ) && ! $value instanceof stdClass ) {
return $value;
}
foreach ( array( 'anyOf', 'oneOf' ) as $keyword ) {
if ( ! isset( $schema[ $keyword ] ) ) {
continue;
}
$matching_schema = null;
/*
* Prefer an array schema for PHP lists. An empty PHP array also matches an
* object schema, but should remain [] when an array schema accepts it.
*/
if ( is_array( $value ) && array_is_list( $value ) ) {
foreach ( $schema[ $keyword ] as $candidate_schema ) {
if ( ! isset( $candidate_schema['type'] ) && isset( $schema['type'] ) ) {
$candidate_schema['type'] = $schema['type'];
}
if ( _wp_json_schema_matches_type( $value, $candidate_schema, 'array' ) ) {
$matching_schema = $candidate_schema;
break;
}
}
}
// Like rest_filter_response_by_context(), use the first matching oneOf branch.
if ( null === $matching_schema ) {
$matching_schema = 'anyOf' === $keyword
? rest_find_any_matching_schema( $value, $schema, '' )
: rest_find_one_matching_schema( $value, $schema, '', true );
}
if ( is_wp_error( $matching_schema ) ) {
continue;
}
if ( ! isset( $schema['type'] ) && isset( $matching_schema['type'] ) ) {
$schema['type'] = $matching_schema['type'];
}
$value = wp_prepare_json_value_for_client( $value, $matching_schema );
}
$is_array_value = is_array( $value );
$types = isset( $schema['type'] ) ? (array) $schema['type'] : array();
$allows_object = in_array( 'object', $types, true );
$allows_array = in_array( 'array', $types, true );
if ( $is_array_value && empty( $value ) && $allows_object && ! $allows_array ) {
return (object) $value;
}
$is_object_value = $value instanceof stdClass || ( $is_array_value && $allows_object && ( ! $allows_array || ! array_is_list( $value ) ) );
if ( $allows_object && $is_object_value ) {
if ( $value instanceof stdClass ) {
$value = clone $value;
}
foreach ( $value as $property => $property_value ) {
$property_schema = null;
if ( isset( $schema['properties'][ $property ] ) && is_array( $schema['properties'][ $property ] ) ) {
$property_schema = $schema['properties'][ $property ];
} else {
$property_schema = rest_find_matching_pattern_property_schema( $property, $schema );
if ( null === $property_schema && isset( $schema['additionalProperties'] ) && is_array( $schema['additionalProperties'] ) ) {
$property_schema = $schema['additionalProperties'];
}
}
if ( null === $property_schema ) {
continue;
}
$property_value = wp_prepare_json_value_for_client( $property_value, $property_schema );
if ( is_array( $value ) ) {
$value[ $property ] = $property_value;
} else {
$value->$property = $property_value;
}
}
} elseif ( $allows_array && $is_array_value && isset( $schema['items'] ) && is_array( $schema['items'] ) ) {
foreach ( $value as $index => $item ) {
$value[ $index ] = wp_prepare_json_value_for_client( $item, $schema['items'] );
}
}
return $value;
}
/**
* Determines whether a value matches a JSON Schema through a given type.
*
* Combining schemas must have a matching branch that allows the requested type.
* Finding the type in one branch and validating the value against another branch
* is not sufficient.
*
* @since 7.2.0
* @access private
*
* @param mixed $value The value to validate.
* @param array<string, mixed> $schema The schema to inspect.
* @param string $type The type to match.
* @return bool Whether the value matches the schema through the requested type.
*/
function _wp_json_schema_matches_type( $value, array $schema, string $type ): bool {
if ( isset( $schema['type'] ) && ! in_array( $type, (array) $schema['type'], true ) ) {
return false;
}
foreach ( array( 'anyOf', 'oneOf' ) as $keyword ) {
if ( ! isset( $schema[ $keyword ] ) ) {
continue;
}
foreach ( $schema[ $keyword ] as $sub_schema ) {
if ( ! is_array( $sub_schema ) ) {
continue;
}
// Match rest_find_any_matching_schema(), which applies the parent type to untyped branches.
if ( ! isset( $sub_schema['type'] ) && isset( $schema['type'] ) ) {
$sub_schema['type'] = $schema['type'];
}
if ( _wp_json_schema_matches_type( $value, $sub_schema, $type ) ) {
continue 2;
}
}
return false;
}
if ( ! isset( $schema['type'] ) && ! isset( $schema['anyOf'] ) && ! isset( $schema['oneOf'] ) ) {
return false;
}
// Explicit and inferred types must both validate through the requested type only.
$schema['type'] = $type;
return ! is_wp_error( rest_validate_value_from_schema( $value, $schema ) );
}
The same content is in 5 releases, WordPress 7.2-beta1 to 7.2-beta5. See them all, or every version of this file.