@adobe/design-data-spec 3.3.0 → 3.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -96,6 +96,41 @@
|
|
|
96
96
|
"items": { "$ref": "component.schema.json" },
|
|
97
97
|
"description": "Platform-local component specs, injected into the component catalog (add-or-replace by name)."
|
|
98
98
|
},
|
|
99
|
+
"fields": {
|
|
100
|
+
"type": "array",
|
|
101
|
+
"items": { "$ref": "field.schema.json" },
|
|
102
|
+
"description": "Platform-local field declarations, injected into the field catalog (add-or-replace by name)."
|
|
103
|
+
},
|
|
104
|
+
"relationships": {
|
|
105
|
+
"type": "array",
|
|
106
|
+
"items": {
|
|
107
|
+
"oneOf": [
|
|
108
|
+
{ "$ref": "relationship.schema.json#/$defs/relationship" },
|
|
109
|
+
{
|
|
110
|
+
"type": "object",
|
|
111
|
+
"required": ["op", "uuid", "value"],
|
|
112
|
+
"properties": {
|
|
113
|
+
"op": { "const": "override" },
|
|
114
|
+
"uuid": { "type": "string", "format": "uuid" },
|
|
115
|
+
"value": {
|
|
116
|
+
"$ref": "relationship.schema.json#/$defs/relationship"
|
|
117
|
+
}
|
|
118
|
+
},
|
|
119
|
+
"additionalProperties": false
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
"type": "object",
|
|
123
|
+
"required": ["op", "uuid"],
|
|
124
|
+
"properties": {
|
|
125
|
+
"op": { "const": "remove" },
|
|
126
|
+
"uuid": { "type": "string", "format": "uuid" }
|
|
127
|
+
},
|
|
128
|
+
"additionalProperties": false
|
|
129
|
+
}
|
|
130
|
+
]
|
|
131
|
+
},
|
|
132
|
+
"description": "Platform-local Component/Token Relationship (CTR) add/override/remove. Entries without \"op\" are added positionally; \"override\"/\"remove\" require a \"uuid\" to target an existing relationship."
|
|
133
|
+
},
|
|
99
134
|
"platformExtensions": {
|
|
100
135
|
"type": "array",
|
|
101
136
|
"items": {
|
|
@@ -103,6 +138,28 @@
|
|
|
103
138
|
},
|
|
104
139
|
"description": "Platform-local terminology extensions (e.g. iOS state vocabulary), annotating ids in an existing base registry."
|
|
105
140
|
},
|
|
141
|
+
"guidelines": {
|
|
142
|
+
"type": "array",
|
|
143
|
+
"items": { "$ref": "guideline.schema.json" },
|
|
144
|
+
"description": "Platform-local guideline docs, injected into the guideline catalog (add-or-replace by name)."
|
|
145
|
+
},
|
|
146
|
+
"namingExceptions": {
|
|
147
|
+
"type": "object",
|
|
148
|
+
"description": "Platform-local overlay on the base naming-exceptions set: names to add and/or remove for this platform's naming validation.",
|
|
149
|
+
"properties": {
|
|
150
|
+
"add": {
|
|
151
|
+
"type": "array",
|
|
152
|
+
"items": { "type": "string", "minLength": 1 },
|
|
153
|
+
"description": "Token names to add to the naming-exceptions set for this platform."
|
|
154
|
+
},
|
|
155
|
+
"remove": {
|
|
156
|
+
"type": "array",
|
|
157
|
+
"items": { "type": "string", "minLength": 1 },
|
|
158
|
+
"description": "Token names to remove from the base naming-exceptions set for this platform."
|
|
159
|
+
}
|
|
160
|
+
},
|
|
161
|
+
"additionalProperties": false
|
|
162
|
+
},
|
|
106
163
|
"formatting": {
|
|
107
164
|
"type": "object",
|
|
108
165
|
"description": "Rules for serializing structured name objects into platform-specific token name strings.",
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Spike: may a platform manifest override Layer-1 schemas?
|
|
2
|
+
|
|
3
|
+
**Status:** Decided — **No-go**. (bead spectrum-design-data-h890.23.5)
|
|
4
|
+
|
|
5
|
+
## Question
|
|
6
|
+
|
|
7
|
+
Layer 1 JSON Schemas (`packages/design-data-spec/schemas/*.schema.json`) validate every
|
|
8
|
+
foundation and platform artifact, **including the manifest itself**
|
|
9
|
+
(`manifest.schema.json`). Should a platform manifest be allowed to override or relax those
|
|
10
|
+
schemas for its own data?
|
|
11
|
+
|
|
12
|
+
## Why not
|
|
13
|
+
|
|
14
|
+
1. **Circularity.** The manifest that would carry a schema override is itself validated
|
|
15
|
+
against `manifest.schema.json` — a fixed Layer-1 document. Letting that same manifest
|
|
16
|
+
redefine the rules it and its sibling artifacts are checked by breaks the trust
|
|
17
|
+
direction the cascade depends on: Layer 1 is supposed to be the thing platforms
|
|
18
|
+
conform *to*, not a parameter platforms can tune.
|
|
19
|
+
2. **Conformance guarantees become meaningless.** The whole point of a shared schema set
|
|
20
|
+
is that "valid per Layer 1" means the same thing for every platform. A platform-local
|
|
21
|
+
override lets a platform mark its own non-conforming data as conforming, which
|
|
22
|
+
defeats the guarantee for every consumer that trusts "passed Layer 1 validation" as a
|
|
23
|
+
signal (CI, the MCP server, other tooling).
|
|
24
|
+
3. **No concrete need surfaced.** Nothing in the h890.22/h890.23 work (iOS
|
|
25
|
+
externalization, or the guidelines/fields/relationships/naming-exceptions cascade
|
|
26
|
+
additions) needed schema relaxation — every platform-local addition validates fine
|
|
27
|
+
against the existing schemas via `extensions.*`. The `extensions` object is already
|
|
28
|
+
`additionalProperties: true`, which covers "the platform wants to attach data the
|
|
29
|
+
schema doesn't know about" without touching the schema itself.
|
|
30
|
+
|
|
31
|
+
## Decision
|
|
32
|
+
|
|
33
|
+
**No-go.** The manifest cascade will not gain a schema-override mechanism. The capability
|
|
34
|
+
matrix in [`manifest.md`](manifest.md#capability-matrix) keeps schemas in the
|
|
35
|
+
"no manifest-level override mechanism" bucket.
|
|
36
|
+
|
|
37
|
+
If a concrete future need emerges (e.g. a platform genuinely needs a stricter, not
|
|
38
|
+
looser, local schema for its own additive fields), scope a narrow follow-up bead then —
|
|
39
|
+
additive-only, and never loosening what Layer 1 already requires. No such bead is opened
|
|
40
|
+
now.
|
package/spec/manifest.md
CHANGED
|
@@ -4,6 +4,28 @@
|
|
|
4
4
|
|
|
5
5
|
This document defines the **platform manifest**: how a platform implementation repository declares its relationship to **foundation** design data — version pin, inclusion filters, typed overrides, and extensions.
|
|
6
6
|
|
|
7
|
+
## Capability matrix
|
|
8
|
+
|
|
9
|
+
The manifest supports a fixed, enumerated set of operations against the foundation — it does **not** allow overriding, aliasing, or removing arbitrary foundation artifacts. Support is concentrated on tokens; translations and schemas have no manifest-level override mechanism at all.
|
|
10
|
+
|
|
11
|
+
| Operation | Supported? | Field | Applies to |
|
|
12
|
+
| -------------------------------------------------- | ------------------------------------------------------------ | ------------------------------- | --------------------- |
|
|
13
|
+
| Remove / exclude | Yes | `exclude` | Tokens only |
|
|
14
|
+
| Include / whitelist | Yes | `include` | Tokens only |
|
|
15
|
+
| Override value (type-preserving) | Yes | `overrides[].value` | Tokens only |
|
|
16
|
+
| Override → re-alias | Yes | `overrides[].$ref` | Tokens only |
|
|
17
|
+
| Add new tokens (may alias via `$ref`) | Yes | `extensions.tokens` | Tokens |
|
|
18
|
+
| Add / replace components | Yes | `extensions.components` | Components |
|
|
19
|
+
| Add / replace field declarations | Yes | `extensions.fields` | Fields |
|
|
20
|
+
| Add / replace guideline documents | Yes | `extensions.guidelines` | Guidelines |
|
|
21
|
+
| Add relationships/CTRs; override/remove by `uuid` | Yes | `extensions.relationships` | Relationships (CTRs) |
|
|
22
|
+
| Add / remove naming exceptions | Yes | `extensions.namingExceptions` | Naming validation |
|
|
23
|
+
| Annotate existing terminology (cannot add new ids) | Yes | `extensions.platformExtensions` | Existing registry ids |
|
|
24
|
+
| Restrict allowed mode-set values | Yes | `modeSetRestrictions` | Mode sets |
|
|
25
|
+
| Reformat name serialization | Schema-declared only, not yet applied by the reference SDK | `extensions.formatting` | Token name strings |
|
|
26
|
+
| Override/remove/alias translations | No | — | — |
|
|
27
|
+
| Override Layer-1 schemas | No (decided; see [spike](manifest-schema-override-spike.md)) | — | — |
|
|
28
|
+
|
|
7
29
|
## Manifest document
|
|
8
30
|
|
|
9
31
|
A manifest **MUST** conform to [`manifest.schema.json`](../schemas/manifest.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/manifest.schema.json`).
|
|
@@ -17,13 +39,13 @@ A manifest **MUST** conform to [`manifest.schema.json`](../schemas/manifest.sche
|
|
|
17
39
|
|
|
18
40
|
## Optional fields
|
|
19
41
|
|
|
20
|
-
| Field | Type | Description
|
|
21
|
-
| --------------------- | --------------- |
|
|
22
|
-
| `include` | array of string | Semantic **queries** selecting subsets of foundation tokens to materialize.
|
|
23
|
-
| `exclude` | array of string | Queries removing tokens from the included set.
|
|
24
|
-
| `overrides` | array of object | Typed overrides; each entry **MUST** preserve the target token’s **value type**.
|
|
25
|
-
| `extensions` | object |
|
|
26
|
-
| `modeSetRestrictions` | object | Mode set restrictions for this platform; see [Mode Sets — Platform restrictions](mode-sets.md#platform-restrictions).
|
|
42
|
+
| Field | Type | Description |
|
|
43
|
+
| --------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
44
|
+
| `include` | array of string | Semantic **queries** selecting subsets of foundation tokens to materialize. |
|
|
45
|
+
| `exclude` | array of string | Queries removing tokens from the included set. |
|
|
46
|
+
| `overrides` | array of object | Typed overrides; each entry **MUST** preserve the target token’s **value type**. |
|
|
47
|
+
| `extensions` | object | Platform-local additions layered on top of foundation — `tokens`, `components`, `fields`, `guidelines`, `relationships`, `namingExceptions`, `platformExtensions`, `formatting` (see `extensions` section below). |
|
|
48
|
+
| `modeSetRestrictions` | object | Mode set restrictions for this platform; see [Mode Sets — Platform restrictions](mode-sets.md#platform-restrictions). |
|
|
27
49
|
|
|
28
50
|
### `include` / `exclude`
|
|
29
51
|
|
|
@@ -43,6 +65,52 @@ Each override object **MUST** include enough information to identify a target to
|
|
|
43
65
|
|
|
44
66
|
**RECOMMENDED:** `extensions` follows the same structural conventions as foundation token files (tokens, mode sets) and **SHOULD** be validated with the same Layer 1 and Layer 2 rules.
|
|
45
67
|
|
|
68
|
+
#### `extensions.tokens`
|
|
69
|
+
|
|
70
|
+
Platform-local token definitions, in cascade-file format. Inserted at the platform layer alongside (not replacing) foundation tokens; entries **MAY** carry a `$ref` to alias an existing token instead of a literal value.
|
|
71
|
+
|
|
72
|
+
#### `extensions.components`
|
|
73
|
+
|
|
74
|
+
Platform-local component specs, injected into the component catalog. **NORMATIVE:** the reference SDK applies these add-or-replace by component `name` at the platform layer.
|
|
75
|
+
|
|
76
|
+
#### `extensions.fields`
|
|
77
|
+
|
|
78
|
+
Platform-local field declarations, injected into the field catalog. **NORMATIVE:** the reference SDK applies these add-or-replace by field `name` at the platform layer; each entry **MUST** validate against `field.schema.json`. Note: `extensions.formatting.conceptOrder` (if declared) references field names by string — a platform that renames or removes a field it also references there is self-inconsistent; that is a manifest-authoring concern, not enforced by the reference SDK.
|
|
79
|
+
|
|
80
|
+
#### `extensions.guidelines`
|
|
81
|
+
|
|
82
|
+
Platform-local guideline documents, injected into the guideline catalog. **NORMATIVE:** the reference SDK applies these add-or-replace by guideline `name` at the platform layer; each entry **MUST** validate against `guideline.schema.json`.
|
|
83
|
+
|
|
84
|
+
#### `extensions.relationships`
|
|
85
|
+
|
|
86
|
+
Platform-local Component/Token Relationship (CTR) entries. Relationships have no inherent
|
|
87
|
+
stable key — only an optional `uuid` — so add and override/remove use different identity
|
|
88
|
+
rules:
|
|
89
|
+
|
|
90
|
+
* **Add:** an entry with no `op` field is a full relationship object (validated against
|
|
91
|
+
`relationship.schema.json`), appended at the platform layer.
|
|
92
|
+
* **Override / remove:** relationships have no other stable identity, so targeting one
|
|
93
|
+
**MUST** carry a `uuid`. **NORMATIVE:** an `extensions.relationships` entry with `"op":
|
|
94
|
+
"override"` or `"op": "remove"` that omits `uuid` is a manifest error — the reference SDK
|
|
95
|
+
rejects it rather than silently skipping it. `"op": "override"` also carries a `value` (the
|
|
96
|
+
replacement relationship object); `"op": "remove"` drops the matching record.
|
|
97
|
+
|
|
98
|
+
#### `extensions.namingExceptions`
|
|
99
|
+
|
|
100
|
+
Platform-local overlay on the base naming-exceptions set used by naming validation.
|
|
101
|
+
**NORMATIVE:** the reference SDK applies `remove` before `add`, so a name listed in both
|
|
102
|
+
ends up present (add wins) rather than silently dropped. Absent this key, the base set
|
|
103
|
+
(embedded or file-loaded) is used unchanged.
|
|
104
|
+
|
|
105
|
+
| Field | Type | Description |
|
|
106
|
+
| -------- | --------------- | ------------------------------------------------------------ |
|
|
107
|
+
| `add` | array of string | Names to add to the naming-exceptions set for this platform. |
|
|
108
|
+
| `remove` | array of string | Names to remove from the base naming-exceptions set. |
|
|
109
|
+
|
|
110
|
+
#### `extensions.platformExtensions`
|
|
111
|
+
|
|
112
|
+
Platform terminology annotations layered onto **existing** foundation registry entries (for example, platform-specific state names). **NORMATIVE:** every `termId` **MUST** already exist in the referenced foundation registry — this mechanism annotates existing ids, it does **NOT** introduce new ones.
|
|
113
|
+
|
|
46
114
|
#### `extensions.formatting`
|
|
47
115
|
|
|
48
116
|
A platform **MAY** declare formatting rules that control how structured name objects are serialized into flat token name strings for that platform. See [Taxonomy — Platform formatting configuration](taxonomy.md#platform-formatting-configuration) for motivation and examples.
|
|
@@ -76,3 +144,4 @@ The platform manifest is the Layer 2 context document. For Layer 3 (product-laye
|
|
|
76
144
|
|
|
77
145
|
* [#715 — Distributed Design Data Architecture](https://github.com/adobe/spectrum-design-data/discussions/715)
|
|
78
146
|
* [#625 — Token Authoring Workflow](https://github.com/adobe/spectrum-design-data/discussions/625)
|
|
147
|
+
* [Schema-override spike](manifest-schema-override-spike.md) — why the manifest cascade does not allow platform overrides of Layer-1 schemas
|