Repository navigation
Conversation
🤖 PR meta 🤖⚡ PerformanceShow the resultsClient side metrics exclude the server response time. front-end-block-theme
front-end-classic-theme
media-processing
media-upload
post-editor
site-editor
🏁 Flaky testsSome 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. Custom Completer: should allow newlines after multiple option completions in
|
ramonjd
force-pushed
the
update/theme.json-validation-api
branch
from
October 15, 2026 05:14
e94a3f3 to
7d044ae
Compare
Member
Author
TestingCheck out this branch and fire up a terminal in the root of the project (assumes you're running wp-env)
Command Unknown keys at every level {
"version": 3,
"settings": {
"color": { "palette": [], "invention": true },
"typografy": { "fontSizes": [] }
},
"styles": {
"typography": { "fontSize": "1rem", "fontSizes": [ "1rem", "2rem" ] },
"colour": { "text": "red" }
},
"styels": []
}Wrong types {
"version": 3,
"settings": {
"lightbox": { "enabled": "yes" },
"typography": { "fluid": "true" }
},
"styles": {
"color": "red",
"css": [ "body { margin: 0 }" ],
"elements": { "link": { "css": { "rules": "text-decoration: none" } } },
"spacing": { "padding": { "top": [ "1rem" ] } }
}
}Unregistered block and variations {
"version": 3,
"styles": {
"blocks": {
"acme/hero": { "color": { "background": "#000" } },
"core/button": { "variations": { "ghost": { "color": { "text": "#fff" } } } }
},
"variations": { "ghost": { "color": { "background": "#333" } } }
}
}Invalid viewport and root responsive key No version {
"settings": { "color": { "palette": [] } },
"styles": { "color": { "text": "#000" } }
} |
ramonjd
added
[Type] Experimental
ramonjd
force-pushed
the
update/theme.json-validation-api
branch
from
October 16, 2026 04:42
7d044ae to
293fc19
Compare
ramonjd
changed the title
Moves the theme.json sanitization logic out of WP_Theme_JSON_Gutenberg into a new WP_Theme_JSON_Sanitizer_Gutenberg class, without changing behaviour or the WP_Theme_JSON_Gutenberg interface. Moved as-is: sanitize(), remove_keys_not_in_schema(), schema_in_root_and_per_origin(), sanitize_viewport_settings() and its two private helpers, resolve_custom_css_format() and convert_custom_properties(). The method bodies are unchanged apart from reading constants through WP_Theme_JSON_Gutenberg:: instead of static::. WP_Theme_JSON_Gutenberg keeps sanitize(), remove_keys_not_in_schema() and schema_in_root_and_per_origin() as one-line delegations with their existing visibility, so the constructor, remove_insecure_properties() and any subclass are untouched. The two remaining callers of sanitize_viewport_settings() now call the sanitizer directly.
Adds an optional diagnostics collector to WP_Theme_JSON_Sanitizer_Gutenberg and a static WP_Theme_JSON_Gutenberg::get_sanitization_diagnostics() entry point that runs the constructor's migration, unwrapping and sanitization steps on a raw theme.json structure and returns a list of diagnostics instead of an object. sanitize() and remove_keys_not_in_schema() take an optional by-reference array. When it is null, which is what every existing caller passes, the walk is unchanged. When an array is given, a diagnostic is appended at each point a value is dropped or coerced: unknown keys, wrong types for the boolean markers and object schemas, unregistered blocks and block style variations, non-object styles or settings subtrees, viewport breakpoints replaced or normalized, and a missing version. The `$schema` key is exempt because every theme.json file carries it for editor tooling. Each diagnostic has `code`, `category` (structure or type), `severity` (dropped or coerced), `path` into the structure as given, `message` and `data`. Unregistered names are reported before the walk and removed the same way the walk would remove them, which the new equivalence test pins.
…eter Replaces the by-reference `$diagnostics` parameter on sanitize() and remove_keys_not_in_schema() with a static collector on the sanitizer that is null unless a `collect( callable )` callback is running. Call sites now pass a code, a path and optional data. Category and severity come from a DIAGNOSTIC_CODES table and the translated message is built inside add_diagnostic(), so outside collect() a drop costs one null check and no gettext call. Previously the sprintf( __() ) arguments were evaluated before the early return on every dropped key, which added a translation lookup per drop to ordinary construction. collect() restores the previous collector in a finally block, so nested calls and exceptions leave the state clean. get_sanitization_diagnostics() on the theme.json class wraps its pipeline in collect().
Removes WP_Theme_JSON_Gutenberg::get_sanitization_diagnostics() and adds gutenberg_validate_theme_json( $theme_json, $args ) next to the other public theme.json functions. It constructs a theme.json object inside the sanitizer's collect() window and returns what the pipeline dropped or coerced, so the theme.json class keeps only its delegating shims. The two reports the entry point used to make itself now come from the steps that drop the data: migrate() reports a missing version, or a non-object structure, where it replaces the input, and unwrap_shared_block_style_variations() reports a shared variation no block registers where it discards it. Outside collect() both are a null check.
The preset check added in #84534 removes items that are not objects, or whose slug is not scalar, without a trace. Route it through the diagnostics collector so each removed item is reported as theme_json_invalid_type at its index, or at its slug. The filter moves into remove_invalid_preset_items(), which keeps the same acceptance rule and re-indexes the list as before.
Removes the `category` key from each diagnostic. It was derivable from the code and nothing read it, so it was one more thing to keep stable for no benefit. DIAGNOSTIC_CODES now maps each code to its severity. Documents which keys callers can rely on: `code`, `path` and `severity`. `data` is documented per code and may gain keys, and `message` is display text. The function stays in the plugin until the shape has been exercised by real callers.
ramonjd
force-pushed
the
update/theme.json-validation-api
branch
from
October 26, 2026 01:54
77162fa to
eecd291
Compare
Each code already implies what happened to the value, so `severity` repeated information the consumer can derive, and was one more key to keep stable. The viewport message still says the breakpoints were replaced. Diagnostics are now `code`, `path`, `data` and `message`.
Nothing read it, and adding a key later is compatible while removing one is not. Each diagnostic is now `code`, `path` and `message`. The message builder used `data['expected']` to pick its wording, so `theme_json_invalid_type` becomes three codes that say it themselves: `theme_json_expected_object`, `theme_json_expected_boolean` and `theme_json_expected_scalar`. The type-name helper goes with the key it filled.
ramonjd
added
[Feature] Themes
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proof of concept. The first commit moves sanitization into its own class without changing behaviour. The later commits add the reporting. To be split into separate PRs once the approach is agreed.
What
A way to ask WordPress what it will ignore in a theme.json structure before saving it:
Returns a list of diagnostics. Each has a
code, apathand a message. An empty list means WordPress keeps the structure as given.Why
Sanitization drops silently. Generated theme.json, AI output included, invents keys, puts them in the wrong place, references blocks that do not exist and gets types wrong. WordPress discards all of it on read. The tool believes it succeeded, the user gets styles that do nothing, and wrong-typed leftovers have caused front-end fatals (#84523, #84534).
With this, a tool validates before it saves and gets back the exact paths WordPress will ignore. See #81313 and
schemas/README.md: a rejection should be explained where the author can see it.How
gutenberg_validate_theme_json()is running. Every existing construction on the front end and in the editor is unchanged. Outside that window each drop point is a singleif.stylesorsettingsthat are not objectsversionWP_Theme_JSON_Gutenbergkeeps its sanitization methods, which now call the newWP_Theme_JSON_Sanitizer_Gutenbergclass.Testing
Expect three diagnostics: unregistered block,
styles.colornot an object,settings.lightbox.enablednot a boolean. Passlib/theme.jsonand expect an empty list.Limits
Reports what sanitization drops, nothing more. WordPress does not yet know the expected type of most values, so an array
styles.cssor a stringtypography.fluidpasses silently. Teaching it those types is the next step, and this PR gives that check somewhere to report to. Kept does not mean rendered. Results depend on the blocks and block styles registered at call time.Shape
Codes today:
theme_json_missing_versiontheme_json_unknown_keytheme_json_unregistered_blocktheme_json_unregistered_variationtheme_json_expected_objecttheme_json_expected_booleantheme_json_expected_scalartheme_json_invalid_viewportSmall on purpose and not final. Rely on
codeandpath.messageis display text, never something to branch on. Anything structured a consumer needs later is added as a new key or a more specific code, never by changing these. The function stays in the plugin, with no core backport, until a real consumer has used it. From #73116: no positional results, no matching on message text, no numbered severity scale.Example return object:
[ { "code": "theme_json_expected_object", "path": [ "styles", "color" ], "message": "\"styles.color\" must be an object." }, { "code": "theme_json_expected_boolean", "path": [ "settings", "lightbox", "enabled" ], "message": "\"settings.lightbox.enabled\" must be a boolean." } ]Not in this PR
core/validate-global-styles, over this function, separate from saving.remove_insecure_properties(), and movingis_safe_css_declaration()towards the style engine.