@adobe/design-data-spec 4.8.0 → 4.9.0

package/schemas/component-changelog.schema.json

@@ -0,0 +1,306 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component-changelog.schema.json",
+  "title": "Component changelog (draft)",
+  "description": "Per-component changelog generated by `design-data changelog` and committed as changelog/<component>.json. Releases are append-only. The component version is derived from the entries (see spec/component-changelog.md); it is never authored.",
+  "type": "object",
+  "required": ["specVersion", "component", "releases"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "specVersion": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "description": "Component name, the `name` of its component file."
+    },
+    "baseline": {
+      "description": "Present when the component already existed before the first recorded release; its version is the starting 1.0.0.",
+      "$ref": "#/$defs/baseline"
+    },
+    "releases": {
+      "type": "array",
+      "description": "Oldest first. A release already recorded is never rewritten.",
+      "items": {
+        "$ref": "#/$defs/release"
+      }
+    }
+  },
+  "$defs": {
+    "baseline": {
+      "type": "object",
+      "required": ["release", "version", "commit"],
+      "additionalProperties": false,
+      "properties": {
+        "release": {
+          "type": "string"
+        },
+        "version": {
+          "$ref": "#/$defs/semver"
+        },
+        "commit": {
+          "type": "string"
+        }
+      }
+    },
+    "semver": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "release": {
+      "type": "object",
+      "required": ["release", "version", "date", "commit", "commits"],
+      "additionalProperties": false,
+      "properties": {
+        "release": {
+          "type": "string",
+          "description": "The package release the changes shipped in, e.g. a package version. `unreleased` holds changes not yet in a release; the next release takes them over."
+        },
+        "version": {
+          "$ref": "#/$defs/semver",
+          "description": "Component semver after this release. 1.0.0 at the component's first release."
+        },
+        "bump": {
+          "$ref": "#/$defs/bump",
+          "description": "The highest bump among the entries; absent for the first release."
+        },
+        "date": {
+          "type": "string"
+        },
+        "commit": {
+          "type": "string",
+          "description": "Dataset commit the release was taken at."
+        },
+        "commits": {
+          "type": "array",
+          "description": "The changes of each commit in the release, oldest first.",
+          "items": {
+            "$ref": "#/$defs/commitChanges"
+          }
+        }
+      }
+    },
+    "bump": {
+      "enum": ["patch", "minor", "major"],
+      "description": "Semver bump."
+    },
+    "class": {
+      "enum": ["visual", "api", "documentation"],
+      "description": "visual: how the component looks or behaves (values, bindings, recipes). api: options, option values, states, anatomy, relationships present or removed, lifecycle. documentation: descriptions, document blocks, rationale. Metadata-class changes (legacy keys, ids, ordering, implementations, spec bookkeeping) are not entries; see commitChanges.metadata."
+    },
+    "change": {
+      "enum": [
+        "added",
+        "removed",
+        "updated",
+        "renamed",
+        "deprecated",
+        "reverted"
+      ]
+    },
+    "source": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "description": "The PR number from the squash subject (#NNN), otherwise the commit sha and subject.",
+      "properties": {
+        "type": {
+          "enum": ["pr", "commit"]
+        },
+        "repo": {
+          "type": "string"
+        },
+        "number": {
+          "type": "integer"
+        },
+        "title": {
+          "type": "string"
+        },
+        "sha": {
+          "type": "string"
+        },
+        "subject": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "oneOf": [
+        {
+          "properties": {
+            "type": {
+              "const": "pr"
+            }
+          },
+          "required": ["number"]
+        },
+        {
+          "properties": {
+            "type": {
+              "const": "commit"
+            }
+          },
+          "required": ["sha"]
+        }
+      ]
+    },
+    "field": {
+      "type": "object",
+      "required": ["path"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Dot path of the changed field."
+        },
+        "before": {},
+        "after": {}
+      }
+    },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "kind",
+        "change",
+        "class",
+        "bump",
+        "indirect",
+        "contexts",
+        "record",
+        "name",
+        "fields"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "relationship",
+            "token",
+            "option",
+            "option-value",
+            "anatomy-part",
+            "state",
+            "slot",
+            "document-block",
+            "implementation",
+            "lifecycle",
+            "component",
+            "visual-recipe",
+            "visual-part",
+            "visual"
+          ],
+          "description": "A token entry is a Values updated change; a relationship entry is a Bindings changed change."
+        },
+        "change": {
+          "$ref": "#/$defs/change"
+        },
+        "class": {
+          "$ref": "#/$defs/class"
+        },
+        "bump": {
+          "$ref": "#/$defs/bump",
+          "description": "Semver bump this entry implies. major: an option, option value, state, anatomy part, slot or relationship removed; an option, state, anatomy part or slot renamed; an option type changed; the component deprecated or removed. minor: anything added, including a recipe. patch: everything else."
+        },
+        "indirect": {
+          "type": "boolean",
+          "description": "True when a bound token's own record is unchanged but its alias-resolved value changed."
+        },
+        "contexts": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Relationship contexts (spec-sheet block titles) the change appears under."
+        },
+        "scope": {
+          "type": "object",
+          "properties": {
+            "property": {
+              "type": ["string", "null"]
+            },
+            "options": {
+              "type": ["object", "null"]
+            }
+          }
+        },
+        "record": {
+          "type": "string",
+          "description": "Record uuid, or a component-relative path such as options/size/values/xl."
+        },
+        "name": {
+          "type": "string"
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/field"
+          }
+        },
+        "before": {
+          "description": "Added and removed records: the bound token or value for relationships and tokens, the record otherwise."
+        },
+        "after": {},
+        "via": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Indirect entries: uuids of the aliased tokens whose own record changed."
+        },
+        "rationale": {
+          "type": "string",
+          "description": "The record's own rationale, read where it exists. Not required."
+        }
+      }
+    },
+    "commitChanges": {
+      "type": "object",
+      "required": ["commit", "date", "source", "entries"],
+      "additionalProperties": false,
+      "properties": {
+        "commit": {
+          "type": "string"
+        },
+        "date": {
+          "type": "string"
+        },
+        "source": {
+          "$ref": "#/$defs/source"
+        },
+        "entries": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/entry"
+          },
+          "description": "Listed changes (visual, api, documentation). Each is written on one line in the committed file."
+        },
+        "metadata": {
+          "type": "object",
+          "required": ["count", "fields"],
+          "additionalProperties": false,
+          "description": "Metadata-class changes of the commit, counted rather than listed. fields are the changed field paths; a record added or removed is named `<kind> <change>`, e.g. `implementation added`.",
+          "properties": {
+            "count": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "fields": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/component-spec-sheet.schema.json

@@ -0,0 +1,215 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component-spec-sheet.schema.json",
+  "title": "Component spec sheet (draft)",
+  "description": "Draft model of a per-component spec sheet generated by `design-data spec-sheet`: pages of blocks, one block per relationship context. Renderers draw each block's scene and add no layout of their own.",
+  "type": "object",
+  "required": ["specVersion", "component", "size", "block", "pages"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "specVersion": { "type": "string" },
+    "component": { "type": "string" },
+    "displayName": { "type": "string" },
+    "datasetRevision": {
+      "description": "Dataset revision (git commit) the sheet and its changelog were generated from.",
+      "type": ["string", "null"]
+    },
+    "size": {
+      "description": "Size key every block visual renders at.",
+      "type": "string"
+    },
+    "block": {
+      "description": "Block visual size in px.",
+      "type": "object",
+      "required": ["width", "height"],
+      "properties": {
+        "width": { "type": "number" },
+        "height": { "type": "number" }
+      },
+      "additionalProperties": false
+    },
+    "pages": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/page" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "page": {
+      "type": "object",
+      "required": ["title", "blocks"],
+      "properties": {
+        "title": { "type": "string" },
+        "blocks": { "type": "array", "items": { "$ref": "#/$defs/block" } }
+      },
+      "additionalProperties": false
+    },
+    "block": {
+      "type": "object",
+      "required": [
+        "id",
+        "page",
+        "title",
+        "render",
+        "rows",
+        "notes",
+        "changes",
+        "badges"
+      ],
+      "properties": {
+        "id": { "type": "string" },
+        "page": { "type": "string" },
+        "title": {
+          "description": "The relationship context string the block documents.",
+          "type": "string"
+        },
+        "render": { "$ref": "#/$defs/render" },
+        "rows": { "type": "array", "items": { "$ref": "#/$defs/row" } },
+        "notes": { "type": "array", "items": { "type": "string" } },
+        "changes": {
+          "description": "Ids of changelog entries whose relationship context equals the title.",
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "badges": {
+          "description": "Badges to show, for example \"Values updated\".",
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "render": {
+      "type": "object",
+      "required": [
+        "view",
+        "request",
+        "scene",
+        "highlight",
+        "markers",
+        "measurements"
+      ],
+      "properties": {
+        "view": {
+          "description": "Fit of the scene into the block visual: scene px to block px scale, and the offset of the scene's origin in the block.",
+          "type": "object",
+          "required": ["scale", "x", "y"],
+          "properties": {
+            "scale": { "type": "number" },
+            "x": { "type": "number" },
+            "y": { "type": "number" }
+          },
+          "additionalProperties": false
+        },
+        "request": {
+          "description": "The render request the scene was solved from.",
+          "type": "object",
+          "required": ["component", "size", "states", "options", "mode"],
+          "properties": {
+            "component": { "type": "string" },
+            "size": { "type": "string" },
+            "states": { "type": "array", "items": { "type": "string" } },
+            "options": { "type": "object" },
+            "mode": {
+              "type": "object",
+              "additionalProperties": { "type": "string" }
+            }
+          },
+          "additionalProperties": false
+        },
+        "scene": {
+          "description": "The resolved scene graph (`design-data render --format scene`).",
+          "type": "object",
+          "required": ["component", "width", "height", "nodes"]
+        },
+        "highlight": {
+          "description": "Recipe part and prop pairs bound to the block's relationship context.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["part", "prop"],
+            "properties": {
+              "part": { "type": "string" },
+              "prop": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "markers": {
+          "description": "Numbered markers 1..n, one per group of token rows that share a recipe property template. `part` is the recipe part the marker sits on, or null when no recipe binding fits.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["n", "part", "label"],
+            "properties": {
+              "n": { "type": "integer", "minimum": 1 },
+              "part": { "type": ["string", "null"] },
+              "label": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "measurements": {
+          "description": "Scene measurements the block shows: those whose relationship context is the block title. `index` points into scene.measurements and `label` is the relationship property.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["index", "prop", "kind", "label"],
+            "properties": {
+              "index": { "type": "integer", "minimum": 0 },
+              "prop": { "type": "string" },
+              "kind": { "type": "string" },
+              "label": { "type": "string" },
+              "relationship": { "type": ["string", "null"] }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "row": {
+      "type": "object",
+      "required": ["conditions", "items"],
+      "properties": {
+        "conditions": {
+          "description": "Scalar component options the relationship records pin for this row.",
+          "type": "object"
+        },
+        "items": { "type": "array", "items": { "$ref": "#/$defs/item" } }
+      },
+      "additionalProperties": false
+    },
+    "item": {
+      "type": "object",
+      "required": ["label", "marker", "size", "states", "token", "values"],
+      "properties": {
+        "label": {
+          "description": "Option label from component options or the registry.",
+          "type": "string"
+        },
+        "marker": {
+          "description": "Number of the render marker this token belongs to, matching render.markers[].n.",
+          "type": ["integer", "null"]
+        },
+        "size": { "type": ["string", "null"] },
+        "states": { "type": "array", "items": { "type": "string" } },
+        "token": {
+          "type": "object",
+          "required": ["name", "uuid", "property"],
+          "properties": {
+            "name": { "type": "string" },
+            "uuid": { "type": ["string", "null"] },
+            "property": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        "values": {
+          "description": "Token value per scale (`desktop`, `mobile`), or `value` when the token has no scale. An alias shows as {\"alias\": name}.",
+          "type": "object"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}