Metadata

Definition & Purpose

UXDL uses open metadata dictionaries to hold project-specific context (such as Figma links, analytics event names, security requirements, and feature flags) without breaking graph schema validation.

Common Canonical Metadata Keys

While metadata is open to any key, the following standardized keys are recognized across the UXDL ecosystem, contextual linter, and integration tools:

• archetype (Screen) — Nature contract for contextual linter (public_static, data_view, auth_flow, form_input, sensitive_transaction).
• terminal (Screen) — Boolean set to true for intentional terminal screens (e.g. account deleted confirmation).
• security (Screen) — Access requirements (public, authenticated, mfa_required, admin_only).
• sensitive_data (Screen) — Data classification (none, pii, financial, credentials).
• figma_url (Screen) — Direct URL link to Figma frame.
• figma_component (Screen) — Corresponding Figma component name.
• prd_url (Screen/Doc) — URL link to prose Notion, Google Doc, or Confluence PRD.
• error_code (State) — Machine-readable error or gateway response code (e.g. CARD_DECLINED).
• analytics_event (State/Action) — Telemetry tracking event identifier (e.g. click_retry_payment).
• rate_limit (Action) — Throttling restriction (e.g. 5_per_minute).
• jira_key / linear_id (Slice) — Issue tracker key (e.g. PROJ-1042, ENG-891).

Metadata Attachment Points

Metadata can be attached to any element in the specification hierarchy:

• Document Root — Global security requirements, analytics namespaces, design systems.
• Screen — Figma frame URLs, route path guidelines, responsive viewport specs.
• State — Error codes, analytics event tags, localized copy strings.
• Action — Required permissions, rate limit rules, telemetry triggers.
• Relation — API endpoint targets, security encryption requirements.

Address Syntax & Examples

Metadata is accessed via the nearest element address plus .metadata:

1Address format:
2element_address.metadata.key
3
4Real-world domain address examples:
5- screens.checkout.metadata.figma_url
6- screens.checkout.states.payment_failed.metadata.error_code
7- screens.checkout.actions.submit.metadata.analytics_id

Complete Valid Example

Here is a document demonstrating metadata attached at screen, state, and action levels:

1screens:
2  checkout:
3    name: Order Checkout
4    metadata:
5      figma_url: "https://figma.com/file/abc123?node-id=101"
6      analytics_page_name: "checkout_view"
7    states:
8      payment_failed:
9        name: Card Declined
10        metadata:
11          analytics_event: "checkout_error_card_declined"
12          support_doc_id: "kb_declined_cards"
13    actions:
14      submit:
15        name: Submit Payment
16        metadata:
17          security_rule: "Requires CSRF token & PCI-compliant iframe"

What Metadata Does NOT Mean

Metadata is non-normative. It does NOT alter graph validation rules or relation routing. If a tool does not recognize a metadata key, it preserves it untouched.