Schemas / v0.4

Lifecycle

Composable lifecycle fragment for the v0.4 contracts: a shared status vocabulary and deprecation records that every entity type references instead of redefining.

This is a reusable definitions fragment, not a standalone manifest format: the root document has no properties of its own and validates no complete manifest. The other v0.4 contracts select the definitions they need from here with $ref, so every entity type shares one canonical vocabulary for status and deprecation. Because the fragment cannot be pointed at by a manifest's $schema, the examples on this page show fragment records — single definition values — rather than full manifests.

Minimal fragment record

The smallest valid Deprecated record carries only the required message field. It is a value the definition accepts, not a complete manifest.

{
  "message": "Use the “ghost” variant instead."
}

Nested definitions

The shared lifecycle definitions. Every v0.4 contract that models lifecycle metadata $refs the ones it needs from here, so all entity types share one vocabulary.

{
  "status": "deprecated"
}

{
  "message": "Use the “ghost” variant instead.",
  "removal": "2027-01-01",
  "replacement": "ghost"
}

{
  "message": "Use the “ghost” variant instead."
}

{
  "removal": "2027-01-01"
}

{
  "replacement": "ghost"
}

{
  "message": "Use the “ghost” variant instead.",
  "removal": "2027-01-01",
  "replacement": "ghost"
}

{
  "message": "Use the “ghost” variant instead."
}

{
  "removal": "2027-01-01"
}

{
  "replacement": "ghost"
}

{
  "deprecated": {
    "message": "Use “lasagna-action-button” instead.",
    "removal": "2027-01-01"
  }
}

{
  "value": "flat",
  "message": "Use “ghost” instead."
}

{
  "value": "flat"
}

{
  "message": "Use “ghost” instead."
}

{
  "removal": "2027-01-01"
}

{
  "replacement": "ghost"
}

How the v0.4 contracts use this fragment

Every v0.4 contract that models lifecycle metadata $refs definitions from this file instead of redefining them:

• Tokens

  Token.status →uses Status

  Token.deprecated →uses NativeDeprecation

• Utilities

  UtilityClass.status →uses Status

  UtilityClass.deprecated →uses NativeDeprecation

• Icons

  Icon.status →uses Status

  Icon.deprecated →uses NativeDeprecation

• Components (CEM)

  LifecycleFields.status, AttributeExtensions.status →uses Status

  deprecatedValues entries →uses DeprecatedValue

• DTCG extensions

  TokenExtensions.status, GroupExtensions.status →uses Status

  TokenExtensions.deprecated, GroupExtensions.deprecated →uses StrictDeprecated

The native manifest contracts (tokens, utilities, icons) also carry a local Deprecated alias that $refs lifecycle.json#/definitions/Deprecated, and the DTCG extensions schema aliases its local Deprecated to StrictDeprecated — one canonical record shape per namespace, defined once here.

Lifecycle selection and rules

Selection

• Native manifests (tokens, utilities, icons): the $schema URL selects the validating contract. schemaVersion is a plain string, not version dispatch; the consuming resolver selects the matching v0.4 profile.
• A v0.3 manifest keeps its v0.3 URL and "0.3.0". A migrated one is valid only against v0.4 and needs a v0.4-capable consumer.
• CEM and DTCG are host formats: no Design Lasagna schemaVersion. A CEM manifest keeps its CEM schemaVersion; DTCG lifecycle data lives in $extensions["recipes.designlasagna"].
• CEM and DTCG extension lifecycle fields apply only when project or resolver config selects lifecycle profile 0.4; otherwise the legacy profile applies. No schema file encodes this; see docs/lifecycle-migration.md in @designlasagna/schemas@0.4.0.
• Legacy data has no automatic, lossless conversion; do not assume universal v0.4 consumer support.
• During the transition, v0.3 and v0.4 documents coexist, each valid against its own contracts.
• Legacy parser-only forms (native booleans or strings, raw DTCG $status/$removal/$replacement, prose-derived data) have no lossless upgrade path; ask authors for structured message, removal, replacement.

Rules

• DTCG extension deprecated must not be false or null; clear inherited deprecation with the standard $deprecated: false.
• CEM deprecated must not be an object.
• Positive evidence (status: deprecated or removed, or a deprecation record) beats false; the conflict is reported as lifecycle-conflict.
• removed is always an error.
• Only exact ISO dates (YYYY-MM-DD) in removal drive severity; semver and quarters are displayed as authored.
• Expand DTCG $extends before lifecycle selection.
• Offline validation: register all six exported v0.4 schemas by $id, since the relative $refs to this fragment do not resolve from a single file.