Proposal: separate Navigation resource data from Navigation block presentation

[Jiwoon-Kim]

Proposal: separate Navigation resource data from Navigation block presentation

This is a follow-up to:

• The Navigation block may be the biggest bottleneck holding back the block theme ecosystem #81282, which describes the current theming and component-contract problems.
• Navigation with a top-level Page List produces invalid ul > ul markup #82207, a concrete example where a top-level Page List can produce invalid list markup because Navigation infers list membership from rendered HTML.

This proposal is intentionally longer-term. It should not block a fix for #82207 or a near-term, stable rendering contract for Navigation parts.

The distinction

Navigation currently has two different responsibilities:

1. A reusable menu resource: what destinations, groups, and generated sources belong to a navigation.
2. A Navigation block instance: how that resource is presented in a particular template location.

Core already separates these partially. A core/navigation block can use ref to point to a wp_navigation post, while the block instance retains layout, overlay, and style attributes. But the referenced menu itself is still a serialized block document. Consequently, the data model, editor tree, and renderer tree are tightly coupled.

I think the useful long-term distinction is:

Navigation resource = structured navigation data
Navigation block    = a view of that resource

This is not a proposal to immediately replace wp_navigation, revisions, or legacy serialized menus. It is a proposal to define the resource model independently, then provide adapters and a migration path.

A possible resource schema

The canonical form should be a versioned JSON schema, not JSON-LD. JSON-LD could be useful as an external projection, but it is not a good fit for editor state, WordPress permissions, or dynamic sources.

{
  "version": 1,
  "items": [
    {
      "id": "home",
      "kind": "link",
      "label": "Home",
      "href": "/",
      "icon": "core/home"
    },
    {
      "id": "about",
      "kind": "group",
      "label": "About",
      "children": [
        {
          "id": "team",
          "kind": "link",
          "label": "Team",
          "href": "/team/"
        }
      ]
    },
    {
      "id": "site-pages",
      "kind": "source",
      "source": "core/pages",
      "query": {
        "parent": 0,
        "orderBy": "menuOrder"
      }
    }
  ]
}

id is a stable resource identifier, not a DOM id. It lets editor state, revisions, generated occurrences, migrations, and future extension data refer to an item without relying on a block client id or array position.

The source example is deliberately declarative. It should be an allowlisted Core source with a constrained schema, not a general-purpose WP_Query escape hatch. The renderer is responsible for expanding it into peer navigation items at the parent level.

Presentation remains in the template

The block instance should continue to own presentation and interaction policy:

{
  "ref": 123,
  "layout": {
    "orientation": "horizontal",
    "justifyContent": "space-between"
  },
  "overlayMenu": "mobile",
  "submenuVisibility": "click"
}

The same Navigation resource could therefore be used in a horizontal header, vertical footer, or sidebar with different overlay and layout settings. It answers what belongs in the navigation; the template answers how it appears there.

The same boundary applies to icons. A resource may carry a semantic icon identifier, while the Icon Registry resolves the glyph and the block/theme owns size, placement, color, and state styling. The existing Icon Registry work in #81225 and #82062 is a useful precedent for that separation.

Rendering contract first

The storage question should not be a prerequisite for better theming. A near-term public rendering contract could be defined and tested against the current block-backed storage.

Every rendered navigation destination, whether it comes from a static link, a submenu, or a generated source, should expose the same documented parts in both the editor and frontend:

• navigation item
• item link or submenu trigger
• submenu container
• generated/source item
• responsive overlay
• icon slot

The exact markup, classes, data-* names, or CSS custom properties are open for discussion. The important property is that themes can target semantic parts without depending on a particular nesting shape or SVG path.

Existing heterogeneous children and extensibility

Navigation does not contain only link-like items today. Its explicit allowedBlocks list includes Search, Social Links, Site Title, Site Logo, Buttons, Icon, Spacer, and others. A structured resource cannot simply discard that capability.

The schema therefore needs an extension boundary. One possible transitional representation is a provider item:

{
  "id": "site-search",
  "kind": "provider",
  "provider": "core/search",
  "attributes": {
    "buttonUseIcon": true
  }
}

Core and third parties could register providers with a JSON schema, editor component, renderer, and declared participation in the Navigation part contract. A compatibility adapter could initially preserve a parsed block representation for existing menus where no structured provider exists.

That is intentionally not the same as asserting every possible block is a navigation item. It makes the existing heterogeneous set explicit and gives extensions a supported route rather than relying on renderer heuristics.

Editor and compatibility costs

This model has real costs. The present Navigation editor is built on InnerBlocks, link UI, List View, block transforms, revisions, and a wp_navigation post entity. A resource model needs a dedicated editing adapter or a resource-aware editor; it cannot be introduced merely by changing a storage string.

Likewise, existing serialized wp_navigation content must remain readable and writable for a long time. A possible incremental path would be:

1. Define the editor/frontend Navigation part contract and fix concrete renderer defects such as Navigation with a top-level Page List produces invalid ul > ul markup #82207.
2. Define a versioned Navigation Resource REST schema and validation rules.
3. Build block-document-to-resource and resource-to-block-document adapters for the supported Core item types.
4. Let the Navigation editor operate on the resource entity while preserving legacy serialization where required.
5. Introduce a provider registry for heterogeneous and third-party navigation content.
6. Decide, only after the adapters are proven, whether the resource's canonical persistence should remain a post field, move to a dedicated REST property, or use another storage mechanism.

The wp_navigation CPT itself can remain useful: it already provides an identity, permissions, revisions, and the ref relationship. The question is the representation of its menu data, not whether a reusable menu resource should continue to exist.

Questions for discussion

1. Would a stable renderer contract for Navigation parts be a useful first step independently of storage?
2. Is a versioned structured resource schema a reasonable direction for saved Navigation data, with block adapters for compatibility?
3. What extension mechanism could represent the current heterogeneous allowed children without turning the schema into arbitrary markup again?
4. Could a declarative, allowlisted source model replace the special structural position of Page List?

I am interested in feedback on the boundary and migration strategy, not in prescribing an immediate rewrite.

[Jiwoon-Kim]

A capability that the resource/view boundary could make possible

One longer-term consequence deserves to be explicit: a structured Navigation resource could make renderer replacement possible.

Today a menu's data is represented as the same block tree that Core renders. A block theme can style the resulting DOM, but it cannot choose a different structural renderer for the same saved navigation resource. In practice that means adapting a design system to Core's <li><a>-oriented output and its implementation details.

If Navigation data has an independent resource schema, a public view/renderer interface could deliberately offer a different choice:

Navigation resource
  -> Core list renderer
  -> theme-provided Material 3 Navigation Bar renderer
  -> theme-provided Material 3 Navigation Rail renderer
  -> another platform-specific renderer

The same resource would still provide the destinations, hierarchy, source items, stable IDs, and semantic icon identifiers. The selected renderer would determine the component tree, interaction markup, and visual implementation.

This is not a claim that JSON alone provides renderer replacement. It requires an explicit, public renderer/view API with accessibility, interaction, extension, and fallback contracts. The point is that the resource/view separation creates a coherent place to introduce that API; the current serialized-inner-block model makes the menu data and Core renderer the same object.