URL Field Values vs Menu Href

Editors and packages use a "URL" shape that shows up in two places: a custom field whose Type is `url`, and a MenuItem's `Href`. They look alike because they are the same stored-value shape, not two different rules.

The shared shape
A custom field of Type `url` (see Field Values and the `url` field type) and a MenuItem's `Href` may each store:

- A plain string, for example `"//example.com/path"` or `"/about"` — a custom address, not linked to a CMS entity.
- A compact entity-linked string `Entity|Type:Name|URL`, for example `"Entity|Article:About Us|//help.example.com/about"`.
- A structured object with `UrlType`, optional `ReferenceGUID`, and optional `Url`, for example `{ "UrlType": "Entity", "ReferenceGUID": "Article:About Us", "Url": "//help.example.com/about" }` or `{ "UrlType": "Custom", "Url": "/contact" }`.

`UrlType` values include `None`, `Custom`, `Entity`, `Image`, `Document`, `Email`, `Tel`, and `Javascript`. When the link targets a CMS object (`Entity`, `Image`, or `Document`), `ReferenceGUID` names that object. Liquid exposes the stored value as a `url` object (`url_type`, `reference_guid`, `.value`, and related members) — Field Values catalogs that runtime shape.

MenuItem Href may be either shape
In site packages, `MenuItem.Href` may be a plain string path or URL (such as `"/about/team"`) or the same structured object (`{ "UrlType": "Custom", "Url": "/about" }`). Both are valid, confirmed with the platform team; they support the same options and are just two serializations of the same destination. Do not flatten a structured `Href` to a string, and do not assume a package must use one shape over the other. MenuItem identity, nesting, and sibling Order live on MenuItem Identity and Order.

An entity-linked destination keeps the URL it was saved with
An entity-linked value (`Entity|…|URL`) stores the entity's URL as it was when the link was saved. Rendering uses that stored URL: the reference GUID identifies the entity but does not refresh the URL. After changing an entity's URL, check the menu items and url fields that point to it.

Do not cross-apply a stale rule
- Do not reject a structured Type `url` field value or a structured MenuItem `Href` as invalid — both accept the structured shape.
- Do not treat Article `URL` (the page-identity field on an Article or page-owning item) as either of the above — that is a separate CMS object rule (see Article URL and BrowserTitle).

What this topic does not cover
Offline validate's acceptance of structured url objects, CLI flags, and interchange maps stay in the site-package toolkit. Liquid rendering of menus stays on the Menu / Menu Item hubs.