98 lines
3.0 KiB
Markdown
98 lines
3.0 KiB
Markdown
# 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.
|