Add `widget.json` metadata schema

[retrofox]

Part of the Dashboard Overview #77616.

Widget types need a single source-of-truth metadata file, just as blocks have block.json. The schema has three consumers:

• @wordpress/build (to emit the widget manifest)
• Core PHP (to register widget types on init)
• JS (to type-check consumers).

This issue formalizes the shape of that file and publishes the JSON Schema at schemas/json/widget.json (mirrored to schemas.wp.org/trunk/widget.json).

A minimal widget.json already exists as a fixture in #77347 (widgets/hello-world/widget.json) to keep the build pipeline honest; this issue turns that implicit contract into a public, validated schema and aligns it with the broader widget-types work.

Proposed shape

Baseline with the minimum fields to register a widget type end-to-end:

{
    "$schema": "https://schemas.wp.org/trunk/widget.json",
    "apiVersion": 1,
    "name": "core/on-this-day",
    "title": "On this day",
    "description": "Surface posts published on this day in previous years.",
    "icon": "calendar",
    "category": "dashboard",
    "textdomain": "default",
    "attributes": [ /* DataViews Field<>[] — see notes below */ ]
}

The attributes array contains entries shaped like Field<> from @wordpress/dataviews (packages/dataviews/src/types/field-api.ts). Each entry declares an attribute that DataForm can render as the right control automatically — so any surface that hosts the widget gets attribute editing for free, without per-widget form code. The JSON schema validates the JSON-expressible subset of that type; runtime-only properties (React components, callbacks) are augmented from the widget's JS module at registration time.

Module entry points and style assets are discovered by convention from the widget directory — the build pipeline in #77576 picks up render.*, widget.*, and render.scss automatically. The schema intentionally does not declare pointers for these in its first iteration; the shape above is exactly what the build honors today. Overrides for non-convention cases can be added in a follow-up if real-world use cases emerge.

Divergences from block.json

Where widget.json mirrors block.json 1:1, no explanation is needed. The table below captures only what changes and why — it's the part of the schema worth debating.

block.json	widget.json	Reason
save	—	Widgets render dynamically; no serialized save function.
parent / ancestor / allowedBlocks	—	Widgets are not nested in a block tree.
providesContext / usesContext	—	Block-tree context is not applicable.
supports	—	Block supports API is block-specific; widget-specific supports can land as a follow-up.
editorScript	—	Widgets are not edited in a block editor; there is no equivalent authoring script.
render, script, style, viewScript	—	Module entry points and styles are discovered by convention from the widget directory (render.*, widget.*, render.scss).
attributes (block-style)	attributes (DataViews Field<>)	Declarative schema so any surface that hosts the widget can render attribute editing through DataForm without per-widget form code.

Tasks

• Publish JSON Schema at schemas/json/widget.json
• Add integration tests under test/integration/ covering schema validation
• TypeScript types (WidgetType, WidgetTypeMetadata) exported from @wordpress/widget-types
• Validate the existing widgets/hello-world/widget.json fixture against the new schema
• Document the shape in the schema README, including the divergences table above

Scope

The following are explicitly out of scope for this issue and land in separate follow-ups:

• Auto-discovery implementation in @wordpress/build (wp-build: Add automatic widget discovery and registration #77576)
• The PHP register_widget_type() API and manifest reader
• The Field[] attribute editor / rendering contract
• Optional overrides for module entry points and style assets (renderModule, widgetModule, style, editorStyle) — to be added once real-world cases require them
• Additional render types beyond developer-defined modules (for example, block compositions or saved entities) — the schema is designed to extend non-breakingly in that direction
• Promotion from __experimental once the shape is stable

Related

• wp-build: Add blocks folder support for automatic block discovery and registration #74542
• wp-build: Add automatic widget discovery and registration #77576

[im3dabasia]

@retrofox, Thanks for the issue! I'll be actively working on this. Once my PR is ready, I’ll tag you for quick feedback. Here is the PR in progress: #77640

[jameskoster]

How would a widget define it's grid dimensions? Many widgets will want to specify a default size, and others may like to specify min/max.

[retrofox]

How would a widget define it's grid dimensions? Many widgets will want to specify a default size, and others may like to specify min/max.

A widget is agnostic of where it's located. It would render the content of a Dashboard tile, in a sidebar, in a modal inserter, etc.

Specifically in the context of the dashboard, the size (and other props) of the dashboard tile is defined by its API.

Also, its definition will be tied to the grid that we use to organize the dashboard. Currently, we've implemented dashboard 2x, but switching to Masonry or another tiles configuration would be possible.

Props like width, height, and position are naturally expected.

Dashboard PR [wip]: #77770