{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://designsystemdocspec.org/v0.15.2/dsds.schema.json",
"title": "Design system doc spec (DSDS) v0.15.2",
"description": "DSDS is a machine-readable format for design system documentation. A DSDS document is either one entity (a component, token, pattern, and so on) or a group of entities. Each entity's `kind` says what it is: component, token, token-group, theme, foundation, pattern, guide, or chunk. Entity schemas live in entities/, document block schemas in document-blocks/, and shared schemas in common/.",
"type": "object",
"required": [
"dsdsVersion"
],
"oneOf": [
{
"required": [
"entityGroups"
]
},
{
"required": [
"entity"
]
}
],
"properties": {
"$schema": {
"type": "string",
"description": "URI reference to the DSDS JSON Schema for validation."
},
"dsdsVersion": {
"type": "string",
"const": "0.15.2",
"description": "The DSDS spec version this document follows."
},
"systemInfo": {
"$ref": "common/system-info.schema.json#/$defs/systemInfo"
},
"extends": {
"$ref": "common/extends.schema.json#/$defs/documentExtends",
"description": "Declares that this DSDS document inherits from another DSDS document. Typically used for a core/extension setup: the base document provides the core entities, and this document adds to or extends them."
},
"documentBlocks": {
"type": "array",
"description": "Structured docs for the design system as a whole — its purpose, system-wide guidelines, overviews. Accepts the general block kinds: `use-cases`, `guidelines`, `sections`, `accessibility`, `content`, or `checklist`.",
"items": {
"$ref": "document-blocks/document-blocks.schema.json#/$defs/generalDocumentBlock"
},
"minItems": 1
},
"entityGroups": {
"type": "array",
"description": "One or more entity groups. Each group has a name and an `entities` array holding any mix of entities — components, tokens, token groups, themes, foundations, patterns, guides, chunks — in display order. Multiple groups let one file organize entities into sections (ex: one for foundations, one for components). A group can be inline or a `$ref` to another DSDS file.",
"items": {
"oneOf": [
{
"$ref": "#/$defs/entityGroup"
},
{
"$ref": "#/$defs/fileRef"
}
]
},
"minItems": 1
},
"entity": {
"$ref": "#/$defs/anyEntity",
"description": "A single entity — component, token, token group, theme, foundation, pattern, guide, or chunk. Use this instead of `entityGroups` when each entity lives in its own file. The `kind` field says which type it is."
},
"$extensions": {
"$ref": "common/extensions.schema.json#/$defs/extensions"
}
},
"additionalProperties": false,
"$defs": {
"anyEntity": {
"type": "object",
"description": "Every entity has a `kind`. It says which type the entity is, and the `if`/`then` branches below pick the matching schema for it.",
"required": [
"kind"
],
"properties": {
"kind": {
"enum": [
"component",
"pattern",
"foundation",
"theme",
"token",
"token-group",
"guide",
"chunk"
]
}
},
"allOf": [
{
"if": {
"required": [
"kind"
],
"properties": {
"kind": {
"const": "component"
}
}
},
"then": {
"$ref": "entities/component.schema.json#/$defs/component"
}
},
{
"if": {
"required": [
"kind"
],
"properties": {
"kind": {
"const": "pattern"
}
}
},
"then": {
"$ref": "entities/pattern.schema.json#/$defs/pattern"
}
},
{
"if": {
"required": [
"kind"
],
"properties": {
"kind": {
"const": "foundation"
}
}
},
"then": {
"$ref": "entities/foundation.schema.json#/$defs/foundation"
}
},
{
"if": {
"required": [
"kind"
],
"properties": {
"kind": {
"const": "theme"
}
}
},
"then": {
"$ref": "entities/theme.schema.json#/$defs/theme"
}
},
{
"if": {
"required": [
"kind"
],
"properties": {
"kind": {
"const": "token"
}
}
},
"then": {
"$ref": "entities/token.schema.json#/$defs/token"
}
},
{
"if": {
"required": [
"kind"
],
"properties": {
"kind": {
"const": "token-group"
}
}
},
"then": {
"$ref": "entities/token.schema.json#/$defs/tokenGroup"
}
},
{
"if": {
"required": [
"kind"
],
"properties": {
"kind": {
"const": "guide"
}
}
},
"then": {
"$ref": "entities/guide.schema.json#/$defs/guide"
}
},
{
"if": {
"required": [
"kind"
],
"properties": {
"kind": {
"const": "chunk"
}
}
},
"then": {
"$ref": "entities/chunk.schema.json#/$defs/chunk"
}
}
]
},
"fileRef": {
"type": "object",
"description": "A link to a DSDS entity or entity group in another file. A tool like `json-schema-ref-parser` resolves it before validation and bundling. Point at a specific value with a JSON Pointer fragment (ex: './button.dsds.json#/entity', './groups/tokens.dsds.json#/entityGroups/0').",
"required": [
"$ref"
],
"properties": {
"$ref": {
"type": "string",
"pattern": "^(?![a-zA-Z][a-zA-Z0-9+.\\-]*:)(?!//)(?!/)",
"description": "A relative path to another DSDS file, optionally with a JSON Pointer fragment for one value in it (ex: './button.dsds.json#/entity'). MUST be relative — no absolute paths, protocol-relative paths, or scheme URIs (http:, file:, …). To reference another system, use `extends.url` instead. Resolvers MUST catch cycles, MUST treat a broken file, pointer, or shape mismatch as a fatal error, and MUST only fetch remote files from an allow-list (see the spec's security rules).",
"minLength": 1
}
},
"additionalProperties": false
},
"entityGroup": {
"type": "object",
"description": "A named collection of entities. They all live in one `entities` array, in display order, and can mix any type — each entity's `kind` says what it is, so there's no need for separate arrays per type. A group MUST hold at least one entity.",
"required": [
"name",
"entities"
],
"properties": {
"name": {
"type": "string",
"description": "Human-readable name of the collection (ex: 'Acme Design System', 'Color Tokens', 'Button Documentation'). Used only as a display label.",
"minLength": 1
},
"description": {
"$ref": "common/rich-text.schema.json#/$defs/richText"
},
"entities": {
"type": "array",
"description": "The group's entities, in display order — any mix of kinds. Each item can be inline or a `$ref` to another DSDS file. Order matters; tools SHOULD keep it.",
"items": {
"oneOf": [
{
"$ref": "#/$defs/anyEntity"
},
{
"$ref": "#/$defs/fileRef"
}
]
},
"minItems": 1
},
"$extensions": {
"$ref": "common/extensions.schema.json#/$defs/extensions"
}
},
"additionalProperties": false
}
}
}Root PropertiesThe DSDS spec version this document follows.URI reference to the DSDS JSON Schema for validation.Declares that this DSDS document inherits from another DSDS document. Typically used for a core/extension setup: the base document provides the core entities, and this document adds to or extends them.Structured docs for the design system as a whole — its purpose, system-wide guidelines, overviews. Accepts the general block kinds: use-cases, guidelines, sections, accessibility, content, or checklist. Min items: 1One or more entity groups. Each group has a name and an entities array holding any mix of entities — components, tokens, token groups, themes, foundations, patterns, guides, chunks — in display order. Multiple groups let one file organize entities into sections (ex: one for foundations, one for components). A group can be inline or a $ref to another DSDS file. Min items: 1A single entity — component, token, token group, theme, foundation, pattern, guide, or chunk. Use this instead of entityGroups when each entity lives in its own file. The kind field says which type it is.
Human-readable name of the collection (ex: 'Acme Design System', 'Color Tokens', 'Button Documentation'). Used only as a display label.The group's entities, in display order — any mix of kinds. Each item can be inline or a $ref to another DSDS file. Order matters; tools SHOULD keep it. Min items: 1References:richText, anyEntity, fileRef, extensionsReferences:component, pattern, foundation, theme, token, tokenGroup, guide, chunkA relative path to another DSDS file, optionally with a JSON Pointer fragment for one value in it (ex: './button.dsds.json#/entity'). MUST be relative — no absolute paths, protocol-relative paths, or scheme URIs (http:, file:, …). To reference another system, use extends.url instead. Resolvers MUST catch cycles, MUST treat a broken file, pointer, or shape mismatch as a fatal error, and MUST only fetch remote files from an allow-list (see the spec's security rules). Pattern: ^(?![a-zA-Z][a-zA-Z0-9+.\-]*:)(?!//)(?!/)