MenuItem Identity and Order

A MenuItem is a navigation entry: a visible label and a destination, optionally nested under another MenuItem in the same Menu. Editors hit collisions and blank links when those rules are confused with Article fields or with structured url custom fields.

Label and destination are Name and Href
Use `Name` for the visible label and `Href` for where the item goes. Do not author Article-style `Title` / `URL` on a MenuItem instead. Extra Title/URL properties can sit harmlessly on a package record and still import live with an empty label and empty link. Validate warns when Title/URL appear without Name/Href; treat that warning as a real defect to fix before import.

Nesting is parentage, not a second Name
Every MenuItem belongs to a Menu (`MenuGUID`). A nested item also names its parent MenuItem (`ParentMenuItemGUID`). In the CMS UI the item still has its own label — nesting only places it under that parent in the tree. Sibling groups are items that share the same Menu and the same parent (or the same Menu with no parent, for root items).

Order is unique per sibling group
`Order` only ranks items inside one sibling group: the same `MenuGUID` and the same `ParentMenuItemGUID` (including the "no parent" root group). Two root items with the same Order, or two children of the same parent with the same Order, collide. A duplicate Order is a defect offline validate catches; fix it by giving each sibling a distinct Order in its own group. Order values in a different Menu, or under a different parent, do not compete with each other.

Href may be a plain string or the structured object
In site packages, `Href` is either a plain string path or URL (for example `/about/team`) or the same structured object a custom `url` field stores — `{ "UrlType": "...", "Url": "...", "ReferenceGUID": "..." }`. Both are valid and support the same options (an internal reference, a custom address, and so on); they are just two serializations of the same destination. A developer-tools CMS menu export commonly shows the structured form (confirmed with the platform team). Pick either shape when authoring; do not flatten a structured `Href` to a string, and do not assume a plain string must be rewritten as an object.

Structured url fields use the same shape
A custom field whose Type is `url` stores a plain string or that same structured object (`UrlType`, optional `ReferenceGUID`, `Url`) — see URL Field Values vs Menu Href. MenuItem `Href` and a `url` field's value are the same stored-value shape; they differ only in which object owns the property.

A parent item with children may omit Href
A MenuItem that exists only to group other MenuItems under it — a dropdown-parent with no destination of its own — may omit `Href`. A MenuItem with no children still requires one; a menu label with nowhere to go and nothing under it is a defect, not a group heading.

What this topic does not cover
Interchange serialization after split or combine — for example rewriting nested MenuItem identity Names on disk, `.guid-map.json`, stamp sidecars, or CLI flags — belongs to the site-package toolkit, not to editor-facing CMS concepts. Liquid rendering of menus (`menu`, `menu_item`, related methods) lives on the Menu / Menu Item reference hubs.