Skip to content

Commit 581b8da

Browse files
TimothyBJacobsTimothyBJacobs
committed
Update the Schema documentation for 5.6
1 parent 0bf8f5d commit 581b8da

File tree

1 file changed

+163
-0
lines changed

1 file changed

+163
-0
lines changed

‎extending-the-rest-api/schema.md

+163
Original file line numberDiff line numberDiff line change
@@ -439,6 +439,28 @@ array(
439439
);
440440
```
441441

442+
#### multipleOf
443+
444+
The `multipleOf` keyword allows for asserting an integer or number type is a multiple of the given number. For example, this schema will only accept even integers.
445+
446+
```php
447+
array(
448+
'type' => 'integer',
449+
'multipleOf' => 2,
450+
);
451+
```
452+
453+
`multipleOf` also supports decimals. For example, this schema could be used to accept a percentage with a maximum of 1 decimal point.
454+
455+
```php
456+
array(
457+
'type' => 'number',
458+
'minimum' => 0,
459+
'maximum' => 100,
460+
'multipleOf' => 0.1,
461+
);
462+
```
463+
442464
### Arrays
443465

444466
Specifying a `type` of `array` requires data to be an array, but that is only half the validation story. You'll also want to enforce the format of each item in the array. This is done by specifying a JSON Schema that each array item must conform to using the `items` keyword.
@@ -798,8 +820,149 @@ While this would fail validation.
798820
}
799821
```
800822

823+
#### patternProperties
824+
825+
The `patternProperties` keyword is similar to the `additionalProperties` keyword, but allows for asserting the property matches a regex pattern. The keyword is an object where each property is a regex pattern and its value is the JSON Schema used to validate properties that match that pattern.
826+
827+
For example, this schema requires that each value is a hex color and the property must only contain “word” characters.
828+
829+
```php
830+
array(
831+
'type' => 'object',
832+
'patternProperties' => array(
833+
'^\\w+$' => array(
834+
'type' => 'string',
835+
'format' => 'hex-color',
836+
),
837+
),
838+
'additionalProperties' => false,
839+
);
840+
```
841+
842+
This would pass validation.
843+
844+
```json
845+
{
846+
"primary": "#ff6d69",
847+
"secondary": "#fecc50"
848+
}
849+
```
850+
851+
While this would fail validation.
852+
853+
```json
854+
{
855+
"primary": "blue",
856+
"$secondary": "#fecc50"
857+
}
858+
```
859+
860+
When the REST API validates the `patternProperties` schema, if a property doesn’t match any of the patterns, the property will be allowed and not have any validation applied to its contents. While this may be confusing, it behaves the same as the `properties` keyword. If this logic isn’t desired, add `additionalProperties` to the schema to disallow non-matching properties.
861+
862+
#### minProperties and maxProperties
863+
864+
The `minItems` and `maxItems` keywords can be used for the `array` type. The `minProperties` and `maxProperties` introduces this same functionality for the `object` type. This can be helpful when using `additionalProperties` to have a list of objects with unique keys.
865+
866+
```php
867+
array(
868+
'type' => 'object',
869+
'additionalProperties' => array(
870+
'type' => 'string',
871+
'format' => 'hex-color',
872+
),
873+
'minProperties' => 1,
874+
'maxProperties' => 3,
875+
);
876+
```
877+
878+
This would pass validation.
879+
880+
```json
881+
{
882+
"primary": "#52accc",
883+
"secondary": "#096484"
884+
}
885+
```
886+
887+
While this would fail validation.
888+
889+
```json
890+
{
891+
"primary": "#52accc",
892+
"secondary": "#096484",
893+
"tertiary": "#07526c"
894+
}
895+
```
896+
897+
The `exclusiveMinimum` and `exclusiveMaximum` keywords do not apply, they are only valid for the `number` and `integer` types.
898+
899+
### Type agnostic keywords
900+
901+
#### oneOf and anyOf
902+
903+
These are advanced keywords that allow for the JSON Schema validator to choose one of many schemas to use when validating a value. The `anyOf` keyword allows for a value to match at least one of the given schemas. Whereas, the `oneOf` keyword requires the value match _exactly_ one schema.
904+
905+
For example, this schema allows for submitting an array of “operations” to an endpoint. Each operation can either be a “crop” or a “rotation”.
906+
907+
```php
908+
array(
909+
'type' => 'array',
910+
'items' => array(
911+
'oneOf' => array(
912+
array(
913+
'title' => 'Crop',
914+
'type' => 'object',
915+
'properties' => array(
916+
'operation' => array(
917+
'type' => 'string',
918+
'enum' => array(
919+
'crop',
920+
),
921+
),
922+
'x' => array(
923+
'type' => 'integer',
924+
),
925+
'y' => array(
926+
'type' => 'integer',
927+
),
928+
),
929+
),
930+
array(
931+
'title' => 'Rotation',
932+
'type' => 'object',
933+
'properties' => array(
934+
'operation' => array(
935+
'type' => 'string',
936+
'enum' => array(
937+
'rotate',
938+
),
939+
),
940+
'degrees' => array(
941+
'type' => 'integer',
942+
'minimum' => 0,
943+
'maximum' => 360,
944+
),
945+
),
946+
),
947+
),
948+
),
949+
);
950+
```
951+
952+
The REST API will loop over each schema specified in the `oneOf` array and look for a match. If exactly one schema matches, then validation will succeed. If more than one schema matches, validation will fail. If no schemas match, then the validator will try to find the closest matching schema and return an appropriate error message.
953+
954+
> operations[0] is not a valid Rotation. Reason: operations[0][degrees] must be between 0 (inclusive) and 360 (inclusive)
955+
956+
To generate more helpful error messages, it is highly recommended to give each `oneOf` or `anyOf` schema a `title` property.
957+
801958
## Changelog
802959

960+
### WordPress 5.6
961+
- Support the `multipleOf` JSON Schema keyword. [r49063](https://core.trac.wordpress.org/changeset/49063)
962+
- Support the `minProperties` and `maxProperties` JSON Schema keywords. [r49053](https://core.trac.wordpress.org/changeset/49053)
963+
- Support the `patternProperties` JSON Schema keyword. [r49082](https://core.trac.wordpress.org/changeset/49082)
964+
- Support the `anyOf` and `oneOf` JSON Schema keywords. [r49246](https://core.trac.wordpress.org/changeset/49246)
965+
803966
### WordPress 5.5
804967
- Improve multi-type JSON Schema support. [r48306](https://core.trac.wordpress.org/changeset/48306)
805968
- Check required properties are provided when validating an object. [r47809](https://core.trac.wordpress.org/changeset/47809)

0 commit comments

Comments
 (0)