Proposal: JSON Schema validation in Gutenberg

[senadir]

TL;DR: This discussion proposes a schema validation package in Gutenberg, why we need this, why we're not using an external package, and what would the scope of it. I'm intentionally leaving Woo's use cases out of this but might reference them in passing.

Why we need JSON Schema validation package

Luigi and Lourens are working on a DataForms, a form generation package that takes a JSON object of field definition, and build a form out of it. Every form need validation, and validation need go beyond required and optional, and have several needs.

One approach to such validation is have a JS function at each field definition. This system works fine but is severely limited:

• While you managed to get the form UI to be runtime-independent via JSON, validation (a crucial part of UI and submission) is now limited to the JS runtime, this means you can't safely render the form outside the site or in a different place.
• You end up either duplicating the validation logic in backend and frontend, or forgoing the frontend validation and relaying on backend validation.

For this, @joshuatf proposed we move our validation logic to JSON Schema, a standard vastly adopted everywhere, including WordPress and WooCommerce. WordPress is no stranger to Schema and exposes its own validation system for REST API.

JSON Schema is is an industry standard, adopting it will give us a safe, future proof, system to validate data and potentially conditionally render things.

Example of JSON Schema to validate a set of fields

JSON Schema validator would take a form data object like:

{
    "title": "Product",
    "slug": "product",
    "description": "A product in the store",
    "manage_stock": true,
    "stock_quantity": 100
}

And match it against user-defined schema:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "title": {
            "type": "string",
        },
        "slug": {
            "type": "string",
            "required": { "$data": "0/title" }
        },
        "description": {
            "type": "string",
        },
        "manage_stock": {
            "type": "boolean",
        },
        "stock_quantity": {
            "type": "integer",
            "minimum": 0,
            "required": { "$data": "0/manage_stock" }
        }
    }
}

And would return true, meaning there are no errors.

Or would take a faulty JSON object and return developer-oriented errors that should be mapped down to user-readable errors by consumers.

Consumers of DataForm would pass a separate schema , or just do the validation themselves and pass an errors object, to be figured out.

Why not use an external package

As it stands right now, there are some packages out there that implement schema validation, including the well known Ajv. Using an external package is not ruled out, but there are some limitations.

When it comes to public packages, they split into 2:

• They don't support the $data keyword, which allows you to use JSON pointers too reference values and keys from your JSON, sort of "minimum of this field is maximum of that, require this if that is checked" kind of the circular pointers. Prime examples include Cloudflare worker's package, exodus schemasafe, hyperjump validator, and jema.js (very alpha package)
• They're too large.

Using an external package as is probably wouldn't work for us, because we want both. So ideally we want to have a WordPress level package (@wordpress/validation) that consumes one of the packages (we figure out a way to reduce Ajv size, we extend one of the above packages with $data, we only support a single draft), or build our own parser. Thankfully, building a JSON validator is not a technically hard problem, and plenty of unit tests exists to ensure whatever we build is up to spec.

But I do think that a WordPress package is needed, part of it to enforce our own rules, add our own extensibility, and possibility some of WordPress sugar syntax (required is at properties level in WP schema, not at object level in drafts).

The scope of the package

as an initial problem, we want to support a single draft (draft 7), a limited set of keywords (whatever we conclude is needed to describe complex objects), for now, this is the scope we're looking to support:

• string
  • pattern
  • minlength
  • maxlength
  • format
• number
  • min
  • max
  • exclusiveMin
  • exclusiveMax
  • multipleOf
• array
  • items
  • contain
  • maxItems
  • minItems
• object
  • allOf
  • anyOf
  • noneOf
  • and validation of what's inside.
• boolean
• null
• $data for all types:
  • For comparative properties
  • Pointer - https://datatracker.ietf.org/doc/html/draft-bhutton-relative-json-pointer-00

Bonus: Conditional rendering

JSON Schema can also be used for conditional rendering, the logic to render or not would be to see if the schema returns errors or not. In conditional rendering, the equation is flipped, and you pass a schema against current document data, not your field, example:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "cart": {
            "type": "object",
            "properties": {
                "needs_shipping": {
                    "type": "boolean",
                    "const": true
                },
                "items": {
                    "type": "array",
                    "contains": {
                        "const": 254
                    }
                }
            },
            
        }
    }
}

Assuming the above schema is one set of a single field, it will be run against the document data, in which case it looks something like:

{
    "cart": {
        "needs_shipping": true,
        "items": [254, 12, 25],
        ...
    }
}

Feedback needed:

We would like to continue with this proposal and push said package, which we can make npm only like DataForms and DataViews.

Unlike #65171, this system is neither a DSL that we end up needing to maintain, nor to support a niche case that's yet to fully arise. Form validation is a current problem that we have right now, it would be great to solve.

The next are:

• Figure out if this is a good time to introduce such package to Gutenberg.
• Continue with external package selection/building one fully in-house.

cc @youknowriad @oandregal

[youknowriad]

Consumers of DataForm would pass a separate schema , or just do the validation themselves and pass an errors object, to be figured out.

This is the main thing I want to callout, we already pass fields to DataForm. fields is the JSON schema. There's no need to pass anything new, we can enhance the fields definition to match closely the JSON schema definition but we shouldn't be adding a new "schema".

I don't think we should be building a separate package to start with, if we have use-cases in Gutenberg/Core, we should start by just building this into the dataviews package.

The one thing that I want to call out, is that I think we should implement this with a core use-case in mind ideally. So where can we use DataForm and schema validation today in Core? Some things that come to mind where we need something like that:

• Forms that we have to create patterns, templates parts.
• The upcoming DataViews and QuickEdit for Categories and Taxonomies will require "creation forms" with validation

[joshuatf]

That works for me but I think it's important to consider a unique "fields" definition and avoid having two "schemas".

👍 I believe it will be a singular schema. I think @senadir's original comments around a separate schema refer to the validation schema which is not directly tied to the field schema or part of data forms.

And those two schemas (field and validation) should remain separate as the field schema represents a visual layout while the validation schema represents what a valid object looks like.

Creating packages has its own costs, so let's defer it after having working features.

We're kind of stuck here with another catch 22 as we need some kind of validation library in order to use data forms. Without validation, data forms aren't much value to consumers.

In this particular case, I'm fine if it's developed in Woo first since JSON Schema is widely adopted and the signature won't change much if we develop in Woo first and then core later decides to adopt it. But I am curious how this would work if that weren't the case. If we need feature B in order to work with feature A, but core does not want to release feature B, how do we allow consumers to start using feature A so that it can eventually become stable.

[senadir]

This is the main thing I want to callout, we already pass fields to DataForm. fields is the JSON schema. There's no need to pass anything new, we can enhance the fields definition to match closely the JSON schema definition but we shouldn't be adding a new "schema".

Wouldn't we be locking validation here to a single system? I have no strong preference there and I think that's an implementation detail that will surface once we decide to consume it. The biggest lock in we want to avoid is the messaging word. A validation library should provide standard errors names that you then map to human readable errors, and I think that should happen outside DataForm. We can probably still do inside DataForm by having some sort of callbacks, but an object of field_id => error_message is the simplest approach and allows server side validation if needed.

The one thing that I want to call out, is that I think we should implement this with a core use-case in mind ideally. So where can we use DataForm and schema validation today in Core?

It was to my understanding that DataForm is being built as a general purpose form creation package, and not trying to solve an exact problem right now, so it make sense to also support validation. Having it separate in a package right now might be too much, but I think agreeing on how optimal validation should be is good outcome to get here.

That works for me but I think it's important to consider a unique "fields" definition and avoid having two "schemas".

I think that at third party developer level, this distinction should not exist, but at an implementor level, such flexibility should be allowed.

[senadir]

In this particular case, I'm fine if it's developed in Woo first since JSON Schema is widely adopted and the signature won't change much if we develop in Woo first and then core later decides to adopt it. But I am curious how this would work if that weren't the case. If we need feature B in order to work with feature A, but core does not want to release feature B, how do we allow consumers to start using feature A so that it can eventually become stable.

Getting to this comment from Joshua. Would it make sense to bundle such validator directly into data forms for now? We can discuss if we want to make it exportable or not (and only useable inside DataForms). For me, picking up a standard (here JSON Schema, or Zod) is important, and we just go with it. We will duplicate work downstream for other efforts, and when other parts of GB need validation, like block bindings, we can pull that out.

[youknowriad]

Getting to this comment from Joshua. Would it make sense to bundle such validator directly into data forms for now? We can discuss if we want to make it exportable or not (and only useable inside DataForms)

I think the best path forward is to build it with a use-case in mind, we can discuss the details locations / package... in the PR, start small and iterate.

[senadir]

Okay! I'm keeping the discussion open to gather more use cases, I trust that @gigitux and @louwie17 will surface up any extra use cases.

We for example know that block bindings need validation, and they don't have anything right now for that.