Skip to content

Acknowledge undocmented options that can be set for args in a REST endpoint #215

@gursuj

Description

@gursuj

Issue Description

When creating a custom REST endpoint, you can specify the arguments it takes, as well as options for each argument. Currently, the options default, required, sanitize_callback and validate_callback are documented here in custom-endpoints.md

Seems you can specify other options too which are undocumented in that page (like type, enum, minLength). I guess these are coming from JSON-Schema documented here? Maybe the docs should at least show an alert that these options are unreliable for validation and you should always use validate_callback for validation, type-checking logic? Would like to hear what others have to say before making a PR.

Why is this a problem?

  • There seems to be a few code snippets online using these options or asking about them. LLMs (GPT, Google Search's AI Mode) will also suggest using options like type, minLength and enum for validation, which are not reliable (see gotchas below) and I don't think these are intended to be used for validation? People, especially beginners, may try to use these without realizing these are unreliable. I know people shouldn't be blindly pasting code but it might be better to warn them in the docs. Maybe LLMS will then pick up on it? They at least seem to acknowledge the risk after further prompting.
  • I found a few gotchas when trying a few of these options, that makes them unsuitable for validation:
    • type: No errors are thrown if you specify invalid types (like int instead of integer). Will not work if data is sent using a Content-Type other than application/json, like multipart/form-data, though I guess that is to be expected.
    • enum is ignored unless you set the type. Strange since that seems to work without the type when using JSON-Schema draft v4, which is what the docs say WordPress uses. Example JSON-Schema (The boilerplate was generated when selecting draft v4)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions