Skip to content
Specs

Metadata

Generation metadata attached to the spec. Present when the spec was produced by a tool (plugin, CLI) rather than authored by hand.

Only source describes the component that carries it. The other six properties describe the run that produced the spec — they are identical for every component generated together — and a run may state them once in a separate run metadata document instead of repeating them on each component (ADR-089). All six are therefore optional here: absent means “read them from the run metadata document”, not “unknown”.

Properties

PropertyTypeRequiredDescription
sourceobjectYesFigma source — pageId, nodeId, nodeType (COMPONENT, COMPONENT_SET, or FRAME)
authorstringNoWho or what generated the spec
lastUpdatedstringNoISO 8601 timestamp
generatorobjectNoTool info — name, version, url, and optional license
generator.versionstringYes, within generatorSemver string of the tool that produced the spec (e.g. "1.10.0")
generator.licenseobjectNoLicense status (status: VALID/EXPIRED/NONE) and level (FREE/PRO/EXTENDED)
schemaobjectNoSchema version info — url, version, and optional latest URL
conventionsMetadataConventionsNoExactly the one platform entry that produced this spec — platforms.figma for a Figma capture — not every platform the workspace configures (ADR-079); see Conventions
settingsSettingsNoChoices about the run that generated this spec
concernConcernNoWhich concern this document carries — api, variants, or examples — when a run wrote one file per concern. Forbidden on a whole component; see Component

Full form

metadata:
  author: Design Systems Team
  lastUpdated: "2026-09-15T00:00:00.000Z"
  generator: { url: "https://...", version: "0.30.0", name: specs-cli }
  schema: { url: "https://.../v0.33.0/schema/component.schema.json", version: "0.33.0" }
  source: { pageId: "12:0", nodeId: "12:345", nodeType: COMPONENT_SET }
  conventions: { ... }
  settings: { ... }

Reduced form

metadata:
  source: { pageId: "12:0", nodeId: "12:345", nodeType: COMPONENT_SET }

RunMetadata

RunMetadata is the run’s six facts on their own, as a document in its own right. It carries no per-component data, and all six properties are required — the document exists to state the run’s facts, so a partial one would leave a reader unable to tell a missing fact from one stated elsewhere.

PropertyTypeRequiredDescription
authorstringYesWho or what generated the specs
lastUpdatedstringYesISO 8601 timestamp
generatorobjectYesTool info — name, version, url, and optional license
schemaobjectYesSchema version info — url, version, and optional latest URL
conventionsMetadataConventionsYesThe one platform entry that produced the specs; see Conventions
settingsSettingsYesChoices about the run that generated the specs
author: Design Systems Team
lastUpdated: "2026-09-15T00:00:00.000Z"
generator:
  url: "https://..."
  version: "0.30.0"
  name: specs-cli
  license: { status: VALID, level: PRO }
schema:
  url: "https://.../v0.33.0/schema/component.schema.json"
  version: "0.33.0"
conventions: { ... }
settings: { ... }

The document validates against metadata.schema.json, exported as @directededges/specs-schema/schema/metadata and reachable from root.schema.json alongside a component and a component set.

Further Reading