This package provides well-documented JSON schemas that describe the shape of:

• WordPress core PHP objects such as WP_Post, WP_Term, and WP_User
• WordPress REST API responses such as those from /wp/v2/posts, /wp/v2/categories, and /wp/v2/users
• Various property types and values of both

The schemas in this library are used to generate the WordPress TypeScript definitions provided by the wp-types package.

The schemas were last updated for WordPress 6.5.

• WP_Post
• WP_Term
• WP_User
• WP_Comment
• WP_Error
• WP_Query
• WP_Block
• WP_Block_Type
• WP_Block_Template
• WP_Site
• WP_Locale
• WP_Taxonomy
• WP_Post_Type
• WP_Role
• WP_Network
• WP_Screen

The REST API schemas use JSON Hyper-Schema.

Schemas are provided for various properties:

• WP_Error_Data
• WP_Error_Messages
• WP_Post_Type_Caps
• WP_Post_Type_Labels
• WP_Post_Type_Rewrite
• WP_Taxonomy_Caps
• WP_Taxonomy_Labels
• WP_Taxonomy_Rewrite
• WP_User_Cap_Name
• WP_User_Caps
• WP_User_Data

Enums are provided for various values:

• WP_Comment_Status_Name
• WP_Comment_Type_Name
• WP_Post_Comment_Status_Name
• WP_Post_Format_Name
• WP_Post_Status_Name
• WP_Post_Type_Name
• WP_Taxonomy_Name
• WP_User_Role_Name
• WP_HTTP_Status_Code

npm install wp-json-schemas

This package is versioned so that you can specify both the schema version and the WordPress branch version in a way that's compatible with semantic versioning. Given version x.y.z:

• The major version number (x) indicates the schema version number, currently 3
• The minor version number (y) indicates the WordPress branch version number without its decimal place, eg. 65 for WordPress 6.5
• The patch version number (z) indicates the schema patch version number

Examples:

• ~3.65.0 - Schema version 3 for WordPress 6.5
• ~3.60.0 - Schema version 3 for WordPress 6.0
• ~3.57.0 - Schema version 3 for WordPress 5.7
• ^3.0.0 - Schema version 3 for the latest WordPress version

Usage depends on what you're doing with the schemas. You could use them for validation or just for understanding the shape of an object.

If you're using TypeScript, check out the TypeScript definitions provided by the wp-types package.

The PHP object schemas apply whenever a supported PHP object is encoded to JSON. For example:

printf(
	'let wpPost = %s;',
	wp_json_encode( get_post() )
);

The REST API object schemas apply to the response to a REST API request. For example:

const api = wp.apiFetch( {
	path: '/wp/v2/categories/'
} );

The schemas also apply outside of an HTTP request, for example if you're saving data as a JSON file and reading it in a Node application.

An object in a REST API response is not the same as its corresponding object in PHP, in fact they are substantially different.

Schemas are available via an OPTIONS request to the REST API endpoints, but the schemas do not adhere strictly to the JSON Schema standard. Here's an article by Timothy B. Jacobs with more info.

No. I started down that path (using wp-parser-lib) but realised it's quicker to generate them manually and then copy most of the documentation from core, especially as I'm adding extra documentation and schemas for properties when I can.

They're all tested against actual output from WordPress core.

To run the tests:

• nvm use
• npm install
• composer install
• composer test

MIT