PHPackages                             ironbound/wp-rest-api-schema-validator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. ironbound/wp-rest-api-schema-validator

ActiveLibrary[Validation & Sanitization](/categories/validation)

ironbound/wp-rest-api-schema-validator
======================================

Validate WP REST API requests using a complete JSON Schema validator.

122.8k↓80%2[2 issues](https://github.com/iron-bound-designs/wp-rest-api-schema-validator/issues)1PHPCI failing

Since Jul 26Pushed 4y ago2 watchersCompare

[ Source](https://github.com/iron-bound-designs/wp-rest-api-schema-validator)[ Packagist](https://packagist.org/packages/ironbound/wp-rest-api-schema-validator)[ RSS](/packages/ironbound-wp-rest-api-schema-validator/feed)WikiDiscussions master Synced 2w ago

READMEChangelogDependenciesVersions (1)Used By (1)

WP REST API Schema Validator
============================

[](#wp-rest-api-schema-validator)

Validate WP REST API requests using a complete JSON Schema validator.

WordPress ships with a validator, `rest_validate_request_arg()`, that supports a limited subset of the JSON Schema spec. This library allows the full JSON Schema spec to be used when writing endpoint schemas with minimal configuration.

This library relies upon the [justinrainbow/json-schema](https://github.com/justinrainbow/json-schema) package to do the actual schema validation. This simply bridges the gap between the two.

Requirements
------------

[](#requirements)

- PHP 5.3+
- WordPress 4.5+

Installation
------------

[](#installation)

`composer require ironbound/wp-rest-api-schema-validator`

Usage
-----

[](#usage)

Initialize a `Middleware` instance with your REST route `namespace` and an array of localized strings. This middleware should be initialized before the `rest_api_init` hook is fired. For example, `plugins_loaded`.

Additionally, schemas must be created with a `title` attribute on the top level. This title should be unique within the versioned namespace.

```
$middleware = new \IronBound\WP_REST_API\SchemaValidator\Middleware( 'namespace/v1', [
  'methodParamDescription' => __( 'HTTP method to get the schema for. If not provided, will use the base schema.', 'text-domain' ),
  'schemaNotFound'         => __( 'Schema not found.', 'text-domain' ),
] );
$middleware->initialize();
```

That's it!

Advanced
--------

[](#advanced)

### GET and DELETE Requests

[](#get-and-delete-requests)

Query parameters passed with GET or DELETE requests are validated against the `args` option that is passed when registering the route.

### Technical Details

[](#technical-details)

On `rest_api_init#100`, the middleware will iterate over the registered routes in the provided namespace. The default WordPress core validation and sanitization functions will be disabled.

Schema validation will be performed on the `rest_dispatch_request#10` hook.

`WP_Error` objects will be returned that match the format in `WP_REST_Request`. Mainly, an error code of `rest_missing_callback_param` or `rest_invalid_param`, a `400` response status code, and detailed error information in `data.params`.

For missing parameters, `data.params` will contain a list of the missing parameter names. For invalid parameters, a map of parameter names to a specific validation error message.

### Procedural Validation

[](#procedural-validation)

In the vast majority of cases, validation should be configured using JSON Schema definitions. However, this is not always the case. For example, verifying that a username is not taken requires making calls to the database that would be impossible to replicate in the schema definition. In these cases, a `validate_callback` can still be provided and will be executed before JSON Schema validation takes place.

```
return [
    '$schema'    => 'http://json-schema.org/schema#',
    'title'      => 'users',
    'type'       => 'object',
    'properties' => [
        'username' => [
            'description' => __( 'Login name for the user.', 'text-domain' ),
            'type'        => 'string',
            'context'     => [ 'view', 'edit', 'embed' ],
            'arg_options' => [
                'validate_callback' => function( $value ) {
                    return ! username_exists( $value );
                },
            ],
        ],
    ],
];
```

### Variable Schemas

[](#variable-schemas)

In most cases, the schema document should be the same for all HTTP methods on a given endpoint. In the rare case that a separate schema document is provided, a `schema` option can be provided to the route args for that HTTP method. The `title` for the separate schema document MUST be the same as the base schema.

```
register_rest_route( 'namespace/v1', 'route', [
    [
        'methods'  => 'GET',
        'callback' => [ $this, 'get_item' ],
        'args'     => $this->get_endpoint_args_for_item_schema( 'GET' ),
    ],
    [
        'methods'  => 'POST',
        'callback' => array( $this, 'create_item' ),
         // See WP_REST_Controller::get_endpoint_args_for_item_schema() for reference.
        'args'     => $this->get_endpoint_args_for_post_schema(),
        'schema'   => [ $this, 'get_public_item_post_schema' ],
    ],
    [
        'methods'  => 'PUT',
        'callback' => [ $this, 'update_item' ],
        'args'     => $this->get_endpoint_args_for_item_schema( 'PUT' ),
    ],
    'schema' => [ $this, 'get_public_item_schema' ],
] );
```

### Reusing Schemas

[](#reusing-schemas)

JSON Schema provides a mechanism to utilize a referenced Schema document for validation. This package allows you to accomplish this by using the `Middleware::get_url_for_schema( $title )` method.

For example, this Schema will validate the `card` property according to the Schema document with the title `card`.

```
[
    '$schema'    => 'http://json-schema.org/schema#',
    'title'      => 'transaction',
    'type'       => 'object',
    'properties' => [
        'card' => [
            '$ref' => $middleware->get_url_for_schema( 'card' )
        ],
    ],
];
```

But what if there is no `/cards` route? Or a more general schema is required? In this case, a shared schema can be used.

```
$middleware->add_shared_schema( [
    '$schema'    => 'http://json-schema.org/schema#',
    'title'      => 'card',
    'type'       => 'object',
    'properties' => [
        'card_number' => [
            'type'    => 'string',
            'pattern' => '^[0-9]{11,19}$',
        ],
        'exp_year'  => [ 'type' => 'integer' ],
        'exp_month' => [
            'type' => 'integer',
            'minimum' => 1,
            'maximum' => 12,
         ],
    ],
] );
```

### Schema Routes

[](#schema-routes)

After all routes have been registered, the middleware will register its own route.

```
namespace/v1/schemas/(?P[\S+])

```

This route returns the plain schema document for the given title. To retrieve a schema for a given HTTP method, pass the desired upper-cased HTTP method to the `method` query param.

```
GET https://example.org/wp-json/namespace/v1/schemas/transaction?method=POST
```

###  Health Score

23

—

LowBetter than 26% of packages

Maintenance17

Infrequent updates — may be unmaintained

Popularity25

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity29

Early-stage or recently created project

 Bus Factor1

Top contributor holds 92% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/c348d8c0ee55f04ab227c1084486ec12037713b2919f91f16c774625a33391b9?d=identicon)[TimothyBJacobs](/maintainers/TimothyBJacobs)

---

Top Contributors

[![TimothyBJacobs](https://avatars.githubusercontent.com/u/3460448?v=4)](https://github.com/TimothyBJacobs "TimothyBJacobs (23 commits)")[![thefrosty](https://avatars.githubusercontent.com/u/367897?v=4)](https://github.com/thefrosty "thefrosty (2 commits)")

---

Tags

json-schemawordpresswp-rest-api

### Embed Badge

![Health badge](/badges/ironbound-wp-rest-api-schema-validator/health.svg)

```
[![Health](https://phpackages.com/badges/ironbound-wp-rest-api-schema-validator/health.svg)](https://phpackages.com/packages/ironbound-wp-rest-api-schema-validator)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)