# Metadata Registry

> **Generic metadata model.** Unlimited future keys — no schema changes required for new keys.  
> Contract version: `metadata-registry.v1`  
> ADR: [ADR-023](../architecture/adr/ADR-023.md) (v1.2)

---

## 1. Purpose

Every commercial registry object MAY carry a **MetadataBag** referenced by `metadata_ref` / attached `metadata`.

Metadata is descriptive and commercial-contextual. It is **not** pricing, **not** entitlement truth, and **not** implementation payload.

---

## 2. Metadata targets (open)

| `target_kind` | Examples |
| --- | --- |
| `product` | PlatformProduct |
| `bundle` | BusinessBundle |
| `capability` | CapabilityDefinition |
| `extension` | ExtensionDefinition |
| `automation_pack` | AutomationPack |
| `asset` | AssetDefinition |
| `theme` | Theme-oriented assets / packs |
| `template` | Template-oriented assets |
| `policy` | PolicyDefinition |
| `pricing_item` | Optional |
| `subscription_plan` | Optional |
| *(future)* | Any new registry kind |

---

## 3. MetadataBag

| Field | Type | Meaning |
| --- | --- | --- |
| `registry_object_id` | uuid | Universal ID of this bag |
| `target_kind` | string | Open |
| `target_id` | uuid | Target's `registry_object_id` |
| `version_code` | string | Metadata bag version |
| `attributes` | map | Open key → value (JSON-compatible) |
| `ext` | object | Additive |

### Reserved / common attribute keys (examples — not exclusive)

| Key | Meaning |
| --- | --- |
| `slug` | URL-safe identifier |
| `tags` | string[] |
| `labels` | localized label map |
| `industry` | |
| `locale` | |
| `country` | |
| `language` | |
| `currency` | |
| `timezone` | |
| `brand` | |
| `owner` | |
| `support_level` | |
| `release_channel` | `stable` \| `beta` \| `preview` \| … |
| `icon` | |
| `color` | |
| `seo` | object |
| `marketing` | object |
| `visibility` | object / string |
| `documentation` | ref/url |
| `beta` | bool |
| `deprecated` | bool |
| `custom_attributes` | object | Escape hatch for unlimited keys |

**Unlimited future keys** MAY appear under `attributes` or `custom_attributes` without architecture or schema contract changes (additive JSON).

---

## 4. Metadata Matrix (illustrative)

| Target | Typical keys |
| --- | --- |
| Product | slug, tags, industry, release_channel, icon, documentation |
| Bundle | slug, tags, marketing, visibility, industry |
| Capability | labels, documentation, deprecated |
| Extension | icon, tags, support_level |
| Automation Pack | tags, locale, language |
| Asset | slug, brand, locale, country, marketing, seo |
| Theme / Template | color, icon, industry, locale |
| Policy | visibility, documentation, beta |

---

## 5. Invariants

1. Unknown keys MUST be accepted by consumers (ignore-unknown).
2. Metadata MUST NOT store payment credentials or entitlement grant rows.
3. Visibility in metadata is advisory; Policy Engine / TenantVisibility remain authoritative when both exist.