View config schema: centralize in schemas/json by oandregal · Pull Request #81168 · WordPress/gutenberg

oandregal · 2026-08-04T16:13:22Z

Alternative to #81169
Core backport at WordPress/wordpress-develop#12854

What?

This PR centralizes the schema for the view config API into schemas/json. Then, everything is derived from it (docs, rest endpoint schema).

Why?

To have a single place to define the schema.

How?

Centralize the schema into schema/json.
Generate the docs (view config reference) from the schema.
Generate a PHP file to be used by the REST endpoint from the schema.

Testing Instructions

Read generated view config reference.
Automated tests should pass.
Smoke test the site editor screens that use the view config API (pages, templates, patterns&parts).

github-actions · 2026-08-04T16:19:01Z

Size Change: 0 B

Total Size: 7.81 MB

_{compressed-size-action}

oandregal · 2026-08-04T18:10:51Z

+		$descriptions = array(
+			'kind'            => __( 'Entity kind.', 'gutenberg' ),
+			'name'            => __( 'Entity name.', 'gutenberg' ),
+			'version'         => __( 'The schema version of the configuration.', 'gutenberg' ),
+			'default_view'    => __( 'Default view configuration.', 'gutenberg' ),
+			'default_layouts' => __( 'Default layout configurations.', 'gutenberg' ),
+			'view_list'       => __( 'List of default views.', 'gutenberg' ),
+			'form'            => __( 'Default form configuration.', 'gutenberg' ),


The source JSON schema has descriptions, but the generated PHP one does not and they won't be picked up for translation by WordPress. This is something we may want to change.

Have translatable descriptions for every property exposed via the endpoint. These are a lot, and it creates work (and churn) for translators. I'm not sure how valuable this is.

Only make the top-level descriptions translatable (or any other subset).

The current endpoint does not offer a description for every property, but we want descriptions for the docs.

Though the alternative PHP approach documents (almost?) every property, as far as I could see.

Following up: the generator now wraps every description in __( …, 'gutenberg' ) when emitting view-config-schema.php (see toPhp() in tools/docs/gen-view-config-schema-php.mjs), so the generated schema has the same description coverage as the alternative PHP approach and all of them go through the translation pipeline. If translator churn becomes a concern, restricting the wrapping to a subset (e.g. top-level properties) is a one-line change in the generator.

oandregal · 2026-08-04T18:38:42Z

@@ -0,0 +1,915 @@
+{
+	"$schema": "http://json-schema.org/draft-04/schema#",


There's no way I know of for JSON to include translator's marks. I don't know that we need them here, but thought I'd share.

This ended up not being needed: the JSON stays plain, and the translation wrapping happens at generation time instead — the PHP generator wraps each description in __() when emitting view-config-schema.php, similar to how core wraps the icon-library manifest strings in _x().

oandregal · 2026-08-04T18:41:51Z

@@ -0,0 +1,206 @@
+/**


Generating a PHP file from a JSON schema is something core already does: script with json2php dep, blocks-json.php, icon-library-manifest.php wrapped with _x).

For the record, why this script doesn't reuse json2php: besides the plain JSON→PHP conversion, it needs to dereference the $ref pointers, drop the definitions map, and wrap each description in __() — and it's dependency-free on purpose so the --check mode can run in the integration test suite. If core adopts the endpoint, the script can be ported alongside the schema, or the generated file committed there like blocks-json.php.

github-actions · 2026-08-05T10:24:55Z

Flaky tests detected in d2745eb.
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/30995352848
📝 Reported issues:

[Flaky Test] displays edits to the post title and content in the preview #38826 in /test/e2e/specs/editor/various/preview.spec.js

github-actions · 2026-08-05T16:07:26Z

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: oandregal <oandregal@git.wordpress.org>
Co-authored-by: mcsf <mcsf@git.wordpress.org>
Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>

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

oandregal · 2026-08-05T16:11:00Z

Tweaked a bit the text, but happy to iterate on anything. I think this is ready.

The one question I have is whether to backport this to wp/7.1 or rather making it a 7.2 change (this would need changing the backport folder and give the backport WordPress/wordpress-develop#12854 a review to understand how it fits in core's flow).

I'd summon @t-hamano for thoughts: this is purely a refactor so that we have a single source of truth to generate the docs and the REST endpoint schema. Happy not to backport it to 7.1 and wait to merge the core backport until the 7.2 cycle as well.

Copilot

Pull request overview

Centralizes the view-config API schema in JSON and derives REST schema and documentation artifacts from it.

Changes:

Adds the canonical JSON schema and generators.
Updates the REST controller and reference documentation.
Adds schema validation and synchronization testing.

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`tools/docs/package.json`	Adds generation command.
`tools/docs/gen-view-config-schema-php.mjs`	Generates the PHP schema.
`tools/docs/gen-view-config-reference.mjs`	Generates reference sections.
`test/integration/view-config-schema.test.js`	Validates schema and generated PHP.
`test/integration/package.json`	Adds draft-04 validator.
`schemas/README.md`	Documents the canonical schema.
`schemas/json/view-config.json`	Defines the canonical schema.
`schemas/CHANGELOG.md`	Records the new schema.
`package.json`	Integrates generation into documentation builds.
`package-lock.json`	Locks the validator dependency.
`lib/compat/wordpress-7.1/view-config-schema.php`	Provides generated REST schema.
`lib/compat/wordpress-7.1/class-gutenberg-rest-view-config-controller-7-1.php`	Loads the generated schema.
`docs/reference-guides/view-config-reference.md`	Adds generated API reference sections.
`backport-changelog/7.1/12854.md`	Records the Core backport.

Adds schemas/json/view-config.json mirroring the REST controller's item schema, a docs generator (npm run docs:view-config-ref) that fills the property tables in view-config-reference.md between autogenerated tokens, a PHPUnit test keeping the PHP schema and the JSON schema in sync, and an Ajv draft-04 validity test. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Makes schemas/json/view-config.json the single structural source of truth for the /wp/v2/view-config endpoint schema: - tools/docs/gen-view-config-schema-php.mjs (dependency-free) dereferences the JSON Schema's local $ref pointers, drops the definitions map, strips documentation descriptions, and emits a committed PHP array file at lib/compat/wordpress-7.1/view-config-schema.php. A --check mode fails when the generated file is stale. - Gutenberg_REST_View_Config_Controller_7_1::get_item_schema() now requires the generated file and overlays its translatable top-level descriptions, replacing ~570 lines of hand-built schema methods. A stubbed comparison confirms the resulting schema is identical to the previous hand-written one. - The PHPUnit structural sync test (and its $ref/description helpers) is replaced by a jest freshness check in test/integration/view-config-schema.test.js, so drift is caught without a WordPress test environment. - npm run docs:view-config-ref now regenerates both the reference docs and the PHP schema file. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Address review feedback: the `s` flag is more self-explanatory than the `[^]` character class for matching across new lines. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ings Address review feedback: instead of stripping the canonical JSON Schema's description annotations when generating the PHP schema file, emit them wrapped in __( ..., 'gutenberg' ) calls so every property description is exposed via the REST endpoint and picked up by the plugin's translation pipeline. The controller no longer needs to overlay its own top-level descriptions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

This reverts commit 35c0fd2.

…cells

Building a file:// URL from process.argv[1] by string interpolation breaks on Windows paths, so the script would never detect it was run directly and both generation and --check would silently do nothing. Compare decoded filesystem paths instead. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Use node:util's parseArgs instead of scanning process.argv directly. As a bonus, unknown flags now fail loudly instead of being silently ignored. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

DataViews exposes pickerActivity as a valid view type, but the schema's new type enum omitted it and default_layouts had no entry for it, so a config using it would violate the schema it is served under. Add it to the enum and give it a default_layouts entry (list-type layout, like activity). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

t-hamano · 2026-08-06T13:45:55Z

I think that making the JSON the source of truth constrains what the View Config API can express. WordPress REST schemas can hold PHP callables — validate_callback, arg_options, and sanitize_callback when it isn't a plain function name — and there is no way to express those in JSON.

More broadly, this seems to run counter to the direction 7.1 just established with wp_prepare_json_schema_for_client(): the server-side schema is canonical, and the portable draft-04 representation is derived from it. This PR inverts that.

Given the above, I'd lean towards moving forward with #81169 instead.

The one question I have is whether to backport this to wp/7.1 or rather making it a 7.2 change (this would need changing the backport folder and give the backport WordPress/wordpress-develop#12854 a review to understand how it fits in core's flow).

I'd summon @t-hamano for thoughts: this is purely a refactor so that we have a single source of truth to generate the docs and the REST endpoint schema. Happy not to backport it to 7.1 and wait to merge the core backport until the 7.2 cycle as well.

Since RC1 has already been released, I want to avoid backporting major changes to 7.1 solely for the purpose of improving code quality.

oandregal mentioned this pull request Aug 4, 2026

View config schema: centralize in PHP #81169

Draft

mcsf reviewed Aug 4, 2026

View reviewed changes

Comment thread tools/docs/gen-view-config-reference.mjs Outdated

oandregal commented Aug 4, 2026

View reviewed changes

oandregal mentioned this pull request Aug 5, 2026

View config schema: generate from JSON WordPress/wordpress-develop#12854

Draft

mcsf reviewed Aug 5, 2026

View reviewed changes

Comment thread docs/reference-guides/view-config-reference.md Outdated

oandregal mentioned this pull request Aug 5, 2026

Markdownlint: disable the MD033 (no-inline-html) rule project-wide #81213

Open

oandregal self-assigned this Aug 5, 2026

oandregal added the [Type] Code Quality Issues or PRs that relate to code quality label Aug 5, 2026

oandregal mentioned this pull request Aug 5, 2026

DataViews: Make grid and table item preview aspect ratio configurable #79329

Merged

oandregal force-pushed the update/schema-from-json branch from d2745eb to eb7a8af Compare August 5, 2026 16:05

oandregal marked this pull request as ready for review August 5, 2026 16:07

oandregal requested review from ajitbohra, juanmaguitar, manzoorwanijk and spacedmonkey as code owners August 5, 2026 16:07

Copilot AI balanced review requested due to automatic review settings August 5, 2026 16:07

oandregal requested a review from fabiankaegy as a code owner August 5, 2026 16:07

Copilot started reviewing on behalf of oandregal August 5, 2026 16:07 View session

Copilot AI reviewed Aug 5, 2026

View reviewed changes

Comment thread tools/docs/gen-view-config-schema-php.mjs Outdated

Comment thread schemas/json/view-config.json

manzoorwanijk reviewed Aug 5, 2026

View reviewed changes

Comment thread tools/docs/gen-view-config-schema-php.mjs

oandregal and others added 4 commits August 6, 2026 13:20

docs: use the dotAll regex flag when replacing autogenerated blocks

7679907

Address review feedback: the `s` flag is more self-explanatory than the `[^]` character class for matching across new lines. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

oandregal and others added 11 commits August 6, 2026 13:20

Add Core backport changelog entry

e8938a2

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Test code span within a table cell

a1fb13a

Revert "Test code span within a table cell"

a61c4c3

This reverts commit 35c0fd2.

Code inline: use HTML code tag to prevent issues with | within table …

a779e2f

…cells

Use @link instead of @see in docblock

2bd3801

Revert changes to unit tests

304c9c4

Improve docs

772f755

Prepare a subsection per property

8cb3b86

Parse CLI flags with parseArgs

a4bd9f0

Use node:util's parseArgs instead of scanning process.argv directly. As a bonus, unknown flags now fail loudly instead of being silently ignored. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

oandregal force-pushed the update/schema-from-json branch from eb7a8af to 41ee309 Compare August 6, 2026 11:20

		@@ -0,0 +1,915 @@
		{
		"$schema": "http://json-schema.org/draft-04/schema#",

Uh oh!

Conversation

oandregal commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Uh oh!

github-actions Bot commented Aug 4, 2026

Uh oh!

Uh oh!

oandregal Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oandregal Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

oandregal Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

oandregal Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

oandregal Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

oandregal Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oandregal Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Aug 5, 2026

Uh oh!

github-actions Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oandregal commented Aug 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

t-hamano commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

oandregal commented Aug 4, 2026 •

edited

Loading

oandregal Aug 4, 2026 •

edited

Loading

oandregal Aug 4, 2026 •

edited

Loading

github-actions Bot commented Aug 5, 2026 •

edited

Loading

t-hamano commented Aug 6, 2026 •

edited

Loading