Discussion

I'd like to discuss if this could still be considered for WP 6.9. I realize that introducing an addition to block.json so late in the cycle could be controversial. However:

• "Format" is a fairly established concept, and one that we might've introduced sooner or later anyway for more granular "typing" of attributes. (Maybe there could be some connection to the new Fields API and components?)
• Special attention needs to be paid when choosing what kinds of formats to allow. However, some standardization exists for those; we can take inspiration from other places in WP -- e.g. this.

Size Change: +23 B (0%)

Total Size: 2.58 MB

_{compressed-size-action}

I see you found the reference docs for REST API schema. format is part of JSON schema spec, so there is no risk adopting the list that comes from v4 and WP REST API supports.

It’s exactly what I had envisioned and also aligns with what @chriszarate shared in his feedback.

I would love to see this exact bug fix included in WordPress 6.9 as it’s the most elegant fix possible and at the same time perfectly scalable solution for the future. Newer versions of JSON schema spec added more possible options, but even what we have in place covers the most important string values that have expected structure: date, email, url, color.

If necessary, in the future we could mix it with other concepts from the schema like patterns, and build validation in UI on top of it.

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ockham <[email protected]>
Co-authored-by: gziolo <[email protected]>
Co-authored-by: youknowriad <[email protected]>
Co-authored-by: oandregal <[email protected]>
Co-authored-by: cbravobernal <[email protected]>
Co-authored-by: fabiankaegy <[email protected]>
Co-authored-by: t-hamano <[email protected]>
Co-authored-by: ntsekouras <[email protected]>
Co-authored-by: hanneslsm <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Thanks a lot @gziolo! Really appreciate your feedback ❤️

I'll open this PR for wider review, including by Editor Tech Leads for 6.9 and other interested parties.

Y'all -- would you be okay with getting this into 6.9? I realize it's late in the cycle, but see @gziolo's points:

format is part of JSON schema spec, so there is no risk adopting the list that comes from v4 and WP REST API supports.

It’s exactly what I had envisioned and also aligns with what @chriszarate shared in his feedback.

I would love to see this exact bug fix included in WordPress 6.9 as it’s the most elegant fix possible and at the same time perfectly scalable solution for the future. Newer versions of JSON schema spec added more possible options, but even what we have in place covers the most important string values that have expected structure: date, email, url, color.

Flaky tests detected in a11a96d.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/18868605397
📝 Reported issues:

• [Flaky Test] Should insert content using the global inserter #57525 in /test/e2e/specs/widgets/editing-widgets.spec.js

It's by far the cleanest way to solve incompatibilities when your attribute type is a string, but stills requires a format.
This way you can prevent to bind urls on datetimes, for example, same for email, phone number, and several other cases.

It's somewhat risky to edit block schema in a Beta, but is not the first time it happens, for the Interactivity API we did the same for block supports.

I like this a lot! Solves several similar headaches I've had before trying to infer the format of a string in block extensions.

The attributes are (or should be) the exact same things as the "fields" API in dataviews. I know we're also looking at introducing "format" for dataviews. So let's make sure this is the exact same API in both before moving forward. cc @oandregal

• The REST API and the Ability API use it to declare the shape of the data they work with.
  • Both use the JSON Schema Draft 04 (published in 2013). This schema has several limitations, including not being able to declare date vs datetime.

The 2019-09 version seems to support those, though: https://json-schema.org/draft/2019-09/draft-handrews-json-schema-validation-02#rfc.section.7.3.1

• The REST API and the Ability API use it to declare the shape of the data they work with.

  • Both use the JSON Schema Draft 04 (published in 2013). This schema has several limitations, including not being able to declare date vs datetime.

The 2019-09 version seems to support those, though: https://json-schema.org/draft/2019-09/draft-handrews-json-schema-validation-02#rfc.section.7.3.1

Ah, I only just realized that there are two parts of the JSON Schema spec: Core and Validation. So the date and date-time formats are apparently defined in the Validation part of the 2019-09 version.

• I haven't done a full compliant analysis, but in a quick look I've detected core has gaps with respect to the schema (lacking not, allOf validation keywords)

2019-09 Core has those keywords: https://json-schema.org/draft/2019-09/draft-handrews-json-schema-02#logic

• It seems difficult to change the schema for backward-compatible reasons (see), though I understand this is nuanced.

Reading that comment, it seems to me that the suggested change was rejected to avoid a collision with a future migration to a newer JSON Schema version, no?

(@ockham sorry I'm "hijacking" this PR to share my ongoing research — happy to post elsewhere).

Investigated this a bit more by comparing JSON Schema (the version in use in REST API and the latest), the current status of the Field API & Block Attributes, and the HTML standard.

The Field API needs to declare both data and UI. It sits in between a standard for data (JSON Schema) and a standard for UI (HTML). This explains why JSON Schema doesn't address rendering issues (format for date, locale for number, etc.), that the Field API and HTML need to handle.

@oandregal There's a lot of JSON Schema rendered tools which are the exact same level of abstraction as our Field API / DataViews, it might be good to check these for reference.

Comparison of JSON Schema properties and Field API ones. I'll look at validation separately.

Here's validation:

• Consumers of the Field API can actually implement any kind of validation via the isValid.custom (sync or async). We'd still want to expand the existing rules, so consumers don't have to write functions and the field is serializable. See some rules we've identified at Field API: Validation #71500 (but many of the ones in the table below are good candidates as well).
• JSON Schema only supports required for object types. This is because it's tailored to declare the whole data structure, not a single field.

This is what I've taken a look at and reported here:

• Types:
  • JSON Schema, Block attributes, Field API, HTML.
  • JSON Schema Draft 04 vs. REST API formats.
• Validation: JSON Schema, Field API, HTML Input.
• Properties: JSON Schema vs. Field API.
• JSON Schema usage in WordPress.

After this research, here's what I think:

• We still need something separate for display formats, the JSON Schema doesn't provide anything I could find. I've prepared a PR for the Field API at Field API: add format to date field type #72999, and I'll get it ready for landing soon. We could name the property displayFormat, to leave formats open. @ockham I wonder if display formats is also something that block bindings/block types would benefit from.
• It's doable to make the Field API look like the JSON Schema:
  • If we want to do it with the existing REST API's version (Draft 04) it takes a lot of basic custom stuff.
  • If we align with the last one (2020-12), we need to:
    • rename label to title
    • rename elements to enum (and getElements to getEnum)
    • examples is an array, but our placeholder is a string. I'd consider this separate things and would keep placeholder.
    • move all inValid.* rules to top-level
    • we need to support required for every field type
    • type becomes split between type and format: it is less ergonomic, and we'll need to support our own format keys for things the schema does not support (e.g., color or password).
• Whether or not the Field API is aligned to look more like JSON Schema, we may want to add schemas for it, ala theme.json or block.json so field authors can benefit from editor validation, etc..

The only advantage of migration is that things look the same. But

• Tooling: we cannot reuse the existing custom tooling from core. And for validation we also want to support a free-form custom sync/async validation function, so I'm not sure if switching to use external libraries for this would be worth the effort.
• Humans and LLMs. The Field API has extensive types, and it's well documented, so I don't think renaming/moving properties would bring much value.

There are other aspects to look at: block bindings / block types cc @ockham, the media roles experiment by @ntsekouras, etc. so I'll let other folks share their thoughts.

That's very helpful research @oandregal! 💯

After reading all these, I'm not sure we can end up eventually using format like core does in fields API, because it would mean tons of extra code to support the things we want for that API, by also having the limitations of an old JSON Schema for back compat. Unless I've misunderstood that we cannot upgrade the JSON Schema version and that might change plans.

Maybe the format for block attributes in this PR is fine and could be helpful for some cases, but of course not all. What would be our plan for format in block attributes, if we add it in this PR for date-time?

Regarding my media roles experiment, it seems it's also a different thing from JSON format and types. In general it tries to add semantic info in some attributes, which I cannot see how they fit in these format+type approaches. Sure, we could have some kind of convention that for example a mediaAlt prop should always be type:string and use that info for whatever we'd need.

Unless I've misunderstood that we cannot upgrade the JSON Schema version and that might change plans.

JSON Schema is versioned by design. You do it by providing:

"$schema": "http://json-schema.org/draft-04/schema#",

That's the version that WordPress supports on the server at the moment. Using a different, more up-to-date version can be (and probably should be) supported. The detection mechanism is based on $schema value provided. It only requires additional handling added in PHP to enable whatever JSON schema version is needed. That would benefit REST API and Abilities API, too.

I’ve rebased this PR and would like to request reviews.

Note that in the meantime, format has been introduced for the Fields API (in #72999). However, conversely to the format concept found in this PR, it is more of a display format that allows specifying how e.g. a given date is formatted when rendered:

{
	id: 'publishDate',
	type: 'date',
	label: 'Publish Date',
	format: {
		date: 'F j, Y',
		weekStartsOn: 'monday',
	},
}

This is a different problem from what this PR is concerned with, where “format” is perhaps best described as a more granular data type. For example, the url attribute that’s found in many blocks (e.g. Button, Image, Navigation Link) currently has ”type”: “string”, as has the Date block’s datetime. We’d like to add a format field to state the the former is a URL, and the latter is a datetime etc.