# METADATA CASCADES

Invoke the Metadata Cascades API to create, retrieve, update, and delete Cascading Attributes, a Metadata Attribute type whose available values depend on the value selected in a parent Attribute.

## (NEW!) List Metadata Cascades (Paginated)

 - [GET /metadata/cascades](https://api.tenovos.com/openapi/v1.5/metadata-cascades/listmetadatacascades.md): Retrieve a paginated, searchable list of metadata cascades for UI consumption. Response fields are lightweight by default (counts only); full level/value detail is available via GET /metadata/cascades/{id} or via the include query parameter.

Defaults:
- sortField defaults to name.
- order defaults to asc.
- from defaults to 0.
- limit defaults to 100 — or 20 if include contains values, regardless of the value requested.

Business Rules:
- searchTerm is a case-insensitive partial match on cascade name.
- inUse accepts a boolean (true/false — aggregate: used anywhere at all) or one of metadataTables, metadataGroups, metadataTemplates, filtering to cascades referenced in that specific usage category. Omitted applies no filter. inUse is also a valid sortField value.
- includeSystem defaults to false. When true, also returns read-only, platform-owned cascades used internally by various platform functionalities, alongside user-created ones. System cascades cannot be edited or deleted by users.
- include is a comma-separated list of levels, values. Omitted returns summary fields only (levelCount/valueCount); include=levels adds levels[] per row; include=values adds values[] per row and clamps limit to 20; include=levels,values returns both.
- usedIn is shaped { metadataTables: [], metadataGroups: [], metadataTemplates: [] } — metadataGroups is a derived, transitive rollup through Table → group, and metadataTemplates a further rollup through group → template; neither is a direct reference.

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

## (NEW!) Create Metadata Cascade

 - [POST /metadata/cascades](https://api.tenovos.com/openapi/v1.5/metadata-cascades/createmetadatacascade.md): Create a metadata cascade — its level schema and initial value tree — as one merged resource, in a single call. This replaces what was previously two separate writes (create the attribute, then create its value map); there is no longer a separate map/attribute split at all.

Defaults:
- nameVisible defaults to true.

Business Rules:
- levels must contain at most 4 entries. Each attributeId must reference an existing, single-select controlled-vocabulary attribute.
- values may be omitted to create an empty cascade. Nesting depth via children must not exceed levels.length (and therefore can never exceed 4). No two nodes in the submitted tree may share the same id.
- searchField is optional. Omitted, it is generated server-side. Supplied, it is used as-is and the cascade is created as featured (featured: true). Either way it is permanently fixed thereafter.
- A duplicate name/searchField is rejected with 409.

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

## (NEW!) Get Metadata Cascade

 - [GET /metadata/cascades/{id}](https://api.tenovos.com/openapi/v1.5/metadata-cascades/getmetadatacascade.md): Retrieve a single metadata cascade by its ID. This is the one place in the cascades API where everything is always returned unconditionally — no include option, no summary/lightweight mode.

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

## (NEW!) Update Metadata Cascade

 - [PATCH /metadata/cascades/{id}](https://api.tenovos.com/openapi/v1.5/metadata-cascades/updatemetadatacascade.md): 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.

## (NEW!) Delete Metadata Cascade

 - [DELETE /metadata/cascades/{id}](https://api.tenovos.com/openapi/v1.5/metadata-cascades/deletemetadatacascade.md): Permanently remove a metadata cascade. Deletion is blocked if the cascade is featured, and blocked if it is still referenced by a table (and, transitively, any template that reaches it through that table).

Business Rules:
- Checks run in this order: not found, then featured, then in-use.

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