johnbillion / wp-json-schemas Goto Github PK

• /wp/v2/pages/{parent}/revisions
• /wp/v2/pages/{parent}/revisions/{id}
• /wp/v2/posts/{parent}/revisions
• /wp/v2/posts/{parent}/revisions/{id}

• /wp/v2/themes

/wp/v2/statuses

When the REST API is requested with ?_envelope the response is enveloped in an object containing properties that would otherwise be sent in HTTP headers etc.

A schema should be added for these.

Need to change the name of the existing WP_User_Role enum to something like WP_User_Assigned_Role. Or use a different naming convention for the enums.

Quite a few properties are typed but they're actually optional and default to null. Need to check them all.

When a request is sent to /wp-json without a route

/wp/v2/types

• /wp/v2/settings

Some new post types and taxonomies in core since this list was created:

• wp_global_styles
• wp_navigation
• wp_template
• wp_template_part

And

• wp_template_part_area
• wp_theme

/wp/v2/[posts|pages]/<id>/revisions

The REST API schemas provided currently are only valid for reads (GET) and for the view and edit contexts. This has some problems:

• The schemas aren't valid if you're trying to construct a create, update, or delete request
• The schemas have fewer constraints than they should have for both the view and edit contexts as they currently cover both
• The schemas are not valid for the embed context

Ideally separate schemas would be provided for each of the four request types (CRUD) and each of the three contexts (view, edit, and embed).

What I don't want to do though is maintain a bunch of schemas for each endpoint that are all similar. This needs to either use partials or be automated somehow.

Proposed version numbering strategy for this library, taking into consideration that I may want to change the schema structure outside any given release of WordPress (eg. in #40).

x.y.z where:

• x is the schema major version number, currently 2
• y is the WordPress branch without its decimal place, currently 58, soon to be 59
• z is the schema patch version, currently 0, although I'll use this for minors too which is currently 12

This allows for sane, semver-compatible version constraints while still allowing a WordPress branch version to be specified:

• ~2.58 for schema version 2 for WordPress 5.8
• ^3.0 for schema version 3 for the latest WordPress version
• 4.61.0 for schema version 4 for WordPress 6.1 without allowing patch releases to the schema (not recommended)

• /wp/v2/categories
• /wp/v2/tags

/wp/v2/[posts|pages]/<id>/autosaves

• /wp/v2/plugins

• /wp/v2/menus

• /wp/v2/search

The wp json-dump routes command reads all the routes registered with the REST API and dumps their schemas to files in the tests/data/rest-api/routes directory. These files aren't actually used during tests, the intention was to use them to implement a test which fails when a new endpoint is registered in a new version of WordPress so I can be alerted when a schema for it needs to be created.

/wp/v2/blocks

Should be able to add a test that compares the properties of WP_Taxonomy_Labels and WP_Post_Type_Labels with the labels property of real taxonomies and post types.

• /wp-json/oembed/1.0
• /wp-json/oembed/1.0/embed
• /wp-json/oembed/1.0/proxy

When fetching attachments or uploading a file via wp/v2/media,there are two similar fields in the schema: mime_type and media_type.

mime_type is the mime type
media_type is either image if it's an image, or file if it's something else (not really useful, but alas)

https://github.com/WordPress/wordpress-develop/blob/5ce8b1f9ed99004c73771ad00adc249c2b293a70/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php#L756-L762

https://github.com/WordPress/wordpress-develop/blob/5ce8b1f9ed99004c73771ad00adc249c2b293a70/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php#L915-L928

The schema here somehow mixes the two together and thinks that media_type is the mime type, and mime_type does not exist:

/wp/v2/taxonomies

They're useless when encoded as JSON, need to check exactly how they're represented and whether a better type could be used.

• /wp/v2/users/<id>/application-passwords

/wp/v2/block-renderer

The current schemas have only been tested with the view context. Need to check the responses when the edit context is used.

• /wp-json/wp-site-health/v1/...

Need to add a scheduled GitHub action workflow that periodically (eg once a day) runs the tests against WordPress nightly. This will allow changes in core to be detected.

Example: https://github.com/johnbillion/extended-cpts/blob/develop/.github/workflows/test-nightly.yml

Hi there 👋
thanks for setting up this package, I've extensively been working with wp-types. In fact, I'm currently finishing up a proper typescript wordpress-api-client, which builds upon wp-types.

So far it has been a blessing, but I have the issue that the typings sometimes are not 100% accurate (relates to #33):
Typings of REST responses include fields of all contexts as optional parameters – even if a response in the "view" context definitely does not contain certain fields of the "edit" context, the typings of responses in both contexts are the same – the context-specific fields are simply typed as optional, for both.

I will add an example to better illustrate the problem.

on a side note: I'm not going to open another issue for this, it's just a question: are you planning on including wp-api request DTOs, as well?

✊ keep it up

• /wp-json/batch/v1

• /wp/v2/block-directory/search

There are several compilation errors raised in wp-types/index.ts, and the compile error can be reproduced on lastest typescript version(Playground Link).

At first I thought it was an issue with json-schema-to-typescript but related issue indacated that the schema need some modifications to loosen these type definition.

The json scheme files involved in this issue are as follows:
https://github.com/johnbillion/wp-json-schemas/blob/master/schemas/rest-api/comment.json#L120
https://github.com/johnbillion/wp-json-schemas/blob/master/schemas/rest-api/post.json#L268
https://github.com/johnbillion/wp-json-schemas/blob/master/schemas/rest-api/media.json#L249

Should be able to add a test that compares the properties of WP_Http_Status_Code with the properties on WP_Http.

/wp/v2/block-types

The cd doesn't work across steps.