Spectrum Design Data
  • Components
  • Tokens
  • Registry
  • AI
  • Specification
  • Tools
    •
    Draft Specification (v1.0.0-draft) — This specification is under active development. Normative text and schemas may change before the stable 1.0.0 release.

    Design Data Specification

    Version: 1.0.0-draft
    Status: Draft — normative text and schemas may change before 1.0.0.

    This document is the top-level overview for the Design Data Specification: a machine-readable model for Spectrum design tokens, dimensions, platform manifests, and validation.

    Scope

    The specification defines:

    1. Token format — structured token identity (name), literal value or alias $ref, and lifecycle metadata (Token format).
    2. Cascade and resolution — layered data (foundation, platform, product), specificity, and how a context picks a winning value (Cascade).
    3. Dimensions — declared modes, defaults, and coverage expectations (Dimensions).
    4. Platform manifest — how a platform repo pins foundation data, filters tokens, and applies typed overrides (Manifest).
    5. Semantic diff — change taxonomy, token identity rules, and property-level change tracking for comparing dataset versions (Diff).
    6. Query notation — filter syntax for selecting tokens by structured fields (Query).
    7. Evolution — deprecation lifecycle, migration windows, change classification, and legacy format contract (Evolution).

    Conformance

    The key words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, and OPTIONAL in this specification are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

    Conformance levels

    Level Meaning
    NORMATIVE Required for a conforming document or tool.
    RECOMMENDED Strong default; deviations SHOULD be documented.
    OPTIONAL May be omitted unless a feature explicitly requires it.

    Validation layers

    Conformance is checked in three layers (all under @adobe/design-data-spec):

    Layer Artifact Responsibility
    1 schemas/*.json Per-instance structural shape (JSON Schema Draft 2020-12).
    2 rules/rules.yaml Semantic rules with stable IDs (e.g. SPEC-001).
    3 conformance/ Fixtures and expected diagnostics for implementors.

    A conforming validator MUST implement Layer 1 for supported document types and SHOULD implement Layer 2 rules whose introduced_in is less than or equal to the validator’s claimed spec version.

    Spec version and SemVer

    This document set carries the spec version 1.0.0-draft. Published artifacts (schemas, rule catalog) are expected to align with Semantic Versioning once 1.0.0 is released: MAJOR for incompatible schema or rule behavior, MINOR for backward-compatible additions, PATCH for clarifications and compatible fixes.

    Full governance (compatibility tiers, migration, CLI --spec-version) is discussed in discussion #735 — Versioning and Evolution.

    Normative references (sibling documents)

    Document Role
    Token format Token name, value / $ref, value types, lifecycle metadata.
    Cascade Layers, specificity, resolution algorithm.
    Dimensions Dimension declarations, built-in dimensions, coverage.
    Manifest Platform manifest fields and validation expectations.
    Diff Semantic diff change taxonomy, token identity, property changes.
    Query Filter notation for selecting tokens by structured fields.
    Evolution Deprecation lifecycle, migration windows, change classification.

    JSON Schema $id and versioning

    NORMATIVE: Canonical schema documents use versioned path $id URIs so major revisions can coexist on the documentation host:

    • Base: https://opensource.adobe.com/spectrum-design-data/schemas/v0/
    • Examples: .../v0/token.schema.json, .../v0/dimension.schema.json, .../v0/manifest.schema.json

    The v0 segment denotes the draft / pre-1.0 schema family aligned with spec version 1.0.0-draft. A future 1.0.0 stable release MAY introduce v1 paths without reusing v0 URLs for incompatible shapes.

    RECOMMENDED: Each root schema document includes a top-level string property specVersion (const matching this spec’s version label) when the instance is a design-data document that should self-identify; see individual schemas.

    Packaged copies in this repository live under packages/design-data-spec/schemas/; their $id still identifies the canonical published URL above.

    Relationship to existing Adobe packages

    Package / area Relationship
    @adobe/spectrum-tokens Current token JSON under packages/tokens/ is the legacy shape (e.g. color-set, scale-set). This spec defines the target format; backward-compat schemas and migration are Phase 1 (#723).
    @adobe/design-system-registry Registry enums and component metadata MAY be referenced by validation rules (e.g. component association); exact coupling is Layer 2.
    @adobe/spectrum-component-api-schemas Component schemas MAY be cross-checked by graph rules; not required for Layer 1 structural validation.

    Umbrella discussions