# (NEW!) Update Metadata Cascade

Update an existing cascade's name, nameVisible, and/or its full value tree. levels and featured can never be changed through this endpoint — levels because restructuring which attributes back a level could invalidate the existing value tree, and featured because it exists specifically to protect a cascade from deletion and would mean nothing if it could simply be toggled off here.

Business Rules:
- At least one of name, nameVisible, values is required.
- When values is provided, it fully replaces the existing tree — nodes omitted from the request are removed. Same depth and duplicate-id rules as create.
- usedIn is not enforced or checked on this endpoint — a value may be updated or removed even while referenced on assets; asset reconciliation is handled by a separate downstream process, out of scope here.
- A new name colliding with an existing cascade's name/searchField is rejected with 409.
- An optional expectedLastUpdatedEpoch concurrency check protects against clobbering another admin's concurrent edit. If it doesn't match the cascade's current lastUpdatedEpoch, the request is rejected with 409 and the response includes currentLastUpdatedEpoch.

The user submitting the request must have the Metadata Template Management admin privilege.

Endpoint: PATCH /metadata/cascades/{id}
Version: 1.5
Security: ApiKeyAuth, BasicAuth

## Header parameters:

  - `Authorization` (string, required)
    Provided by Authentication Token creation operation.

  - `Content-Type` (string, required)
    Enum: "application/json"

## Path parameters:

  - `id` (string, required)
    The unique ID of the cascade to update.
    Example: "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61"

## Request fields (application/json):

  - `name` (string)
    New display name for the cascade.
    Example: "Global Region Cascade"

  - `nameVisible` (boolean)
    Whether the cascade name is visible when rendered on an asset.

  - `values` (array)
    Full replacement of the value tree — not a diff. Nodes omitted from the request are removed. Same shape, depth, and duplicate-id rules as create.

  - `values.id` (string, required)
    Client-generated id for this value node, unique within the submitted tree.
    Example: "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74"

  - `values.name` (string, required)
    Display value.
    Example: "North America"

  - `values.children` (array)
    Nested child values at the next level. Omit or leave empty for a leaf node.

  - `expectedLastUpdatedEpoch` (integer)
    Optional optimistic-concurrency check. If provided and it does not match the cascade's current lastUpdatedEpoch, the update is rejected with 409.
    Example: 1771432800000

## Response 200 fields (application/json):

  - `id` (string)
    Unique ID of the cascade.
    Example: "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61"

  - `name` (string)
    Display name of the cascade.
    Example: "Region Cascade"

  - `searchField` (string)
    System-generated slug. Permanent once created.
    Example: "region_cascade"

  - `levels` (array)
    Ordered levels, fixed at creation. Always present here — unconditional, unlike the list endpoint where it's only included via ?include=levels.

  - `levels.attributeId` (string)
    Id of the controlled-vocabulary attribute backing this level's dropdown values.
    Example: "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70"

  - `levels.attributeName` (string)
    Denormalized display name of the backing attribute.
    Example: "Continent"

  - `levels.order` (integer)
    Zero-based level position; kept as an explicit field rather than implied by array order, since asset metadata can store level references out of order.

  - `nameVisible` (boolean)
    Whether the cascade name is visible when rendered on an asset.
    Example: true

  - `featured` (boolean,null)
    System-assigned. null if never set. Blocks deletion when true.

  - `createdBy` (string)
    User-profile id of the cascade's creator.
    Example: "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45"

  - `createdEpoch` (integer)
    Unix timestamp (ms) of creation.
    Example: 1770714900000

  - `createdDate` (string)
    ISO 8601 creation date.
    Example: "2026-02-10T09:15:00Z"

  - `lastUpdatedBy` (string)
    User-profile id of the last user to update the cascade.
    Example: "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45"

  - `lastUpdatedEpoch` (integer)
    Unix timestamp (ms) of the last update.
    Example: 1771432800000

  - `lastUpdatedDate` (string)
    ISO 8601 last-updated date.
    Example: "2026-02-18T16:40:00Z"

  - `usedIn` (object)
    Where the cascade is currently referenced. A cascade's only direct relationship is being used as a column inside a Table. metadataGroups is a derived, transitive rollup of every group reached through that table's own group membership (Table → group). metadataTemplates is a further derived, transitive rollup of every template reached through that group's own template membership (group → template).

  - `usedIn.metadataTables` (array)
    Tables that directly use this cascade as a column.

  - `usedIn.metadataTables.id` (string)
    Example: "e91a4c7d-3f8b-4e26-9a1d-7c5b0e9f2a83"

  - `usedIn.metadataTables.name` (string)
    Example: "Store Locations Table"

  - `usedIn.metadataGroups` (array)
    Groups that transitively reach this cascade through a table that uses it.

  - `usedIn.metadataTemplates` (array)
    Templates that transitively reach this cascade through a table that uses it.

  - `values` (array)
    Full nested value tree, returned untruncated — always present here (unconditional, same as levels; the list endpoint only includes it via ?include=values). Depth is bounded at 4 levels, but breadth is not — a level with hundreds of sibling values can still make this a large payload.

  - `values.id` (string)
    Value node id.
    Example: "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74"

  - `values.name` (string)
    Display value.
    Example: "North America"

  - `values.source` (string,null)
    Present only when this level's attribute is a Dynamic Controlled Vocabulary (a CV composed from other CVs) — holds the search field of the underlying source CV this value was copied from. null for a value sourced from an ordinary controlled vocabulary. System-computed only; never client-supplied.

  - `values.children` (array)
    Nested child values at the next level. Empty array for a leaf node.

## Response 400 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 401 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 403 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 404 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 409 fields (application/json):

  - `message` (string)

  - `currentLastUpdatedEpoch` (integer)
    Present only for a stale-update conflict — the cascade's actual current lastUpdatedEpoch.