Reference
Issue codes
Every code the validator can report, its default severity, and its message.
Generated from the message catalog of the installed package. Codes are public API; message wording is not.
document
| Code | Severity | Message |
|---|---|---|
document.not-object | error | The document root must be a JSON object, received "<actualType>". |
document.invalid-json | error | The input is not valid JSON: "<reason>". |
document.too-deep | error | The document nests groups deeper than the supported limit of 256 levels. |
document.circular | error | The input object contains a circular reference and cannot be validated. |
document.unreadable-node | error | A property could not be read while validating: "<reason>". |
value
| Code | Severity | Message |
|---|---|---|
value.unknown-property | warning | Property "<property>" is not defined for this value type. Known properties: "…". |
name
| Code | Severity | Message |
|---|---|---|
name.forbidden-character | error | Name "<name>" contains "<character>", which is not allowed in token or group names (reserved for alias syntax). |
name.empty | warning | Token and group names should not be empty. |
token
| Code | Severity | Message |
|---|---|---|
token.type.missing | error | The token has no $type and none can be inherited from a parent group, so its type cannot be determined. |
token.type.invalid | error | Unknown $type "<actual>". Allowed: "…". Did you mean "<suggestion>"? Values are case-sensitive. |
token.type.not-string | error | $type must be a string, received "<actualType>". |
token.description.not-string | error | $description must be a plain string, received "<actualType>". |
token.deprecated.invalid | error | $deprecated must be true, false, or a string explanation, received "<actualType>". |
token.extensions.not-object | error | $extensions must be an object, received "<actualType>". |
token.extensions.key-not-namespaced | warning | $extensions key "<key>" should use reverse domain name notation (for example "com.example.tool") to avoid clashes. |
token.property.unknown | warning | Property "<property>" is not defined for tokens by this specification version and will be ignored. |
token.property.not-allowed | error | Property "<property>" is not allowed on a token: an object with $value cannot also contain child tokens or groups. |
group
| Code | Severity | Message |
|---|---|---|
group.description.not-string | error | $description must be a plain string, received "<actualType>". |
group.type.invalid | error | Unknown group $type "<actual>". Allowed: "…". Did you mean "<suggestion>"? Values are case-sensitive. |
group.type.not-string | error | $type must be a string, received "<actualType>". |
group.deprecated.invalid | error | $deprecated must be true, false, or a string explanation, received "<actualType>". |
group.extensions.not-object | error | $extensions must be an object, received "<actualType>". |
group.extensions.key-not-namespaced | warning | $extensions key "<key>" should use reverse domain name notation (for example "com.example.tool") to avoid clashes. |
group.extends.invalid | error | $extends must be a group reference such as "{group.name}", received "<actual>". |
group.ref.invalid | error | $ref on a group must be a local JSON pointer such as "#/group/name", received "<actual>". |
group.property.unknown | warning | Property "<property>" is not defined for groups by this specification version. Names must not start with "$". |
group.member.invalid | error | Member "<name>" must be a token or a group (an object), received "<actualType>". |
group.root.not-token | error | The reserved "$root" member must be a token (an object with $value). |
group.name.case-collision | warning | Names "…" differ only by case; tools that transform names may produce duplicates. |
alias
| Code | Severity | Message |
|---|---|---|
alias.syntax.invalid | error | Alias "<actual>" is malformed. Use "{group.token}" with non-empty, dot-separated names. |
alias.target.missing | error | Alias "<alias>" does not resolve: no token at "<path>". |
alias.target.not-token | error | Alias "<alias>" points at a group, not a token. Curly-brace aliases can only target tokens (use "{<path>.$root}" for a group's root token). |
alias.cycle | error | Circular alias chain: "…". The value of every token in the chain is unknown. |
alias.type.mismatch | error | Alias "<alias>" resolves to a "<actual>" token but this token is declared as "<expected>". |
ref
| Code | Severity | Message |
|---|---|---|
ref.not-local | error | $ref "<actual>" must point inside this document and start with "#/". External and remote references are not supported. |
ref.syntax.invalid | error | $ref "<actual>" is not a valid JSON pointer (RFC 6901). |
ref.target.missing | error | $ref "<actual>" does not resolve: nothing exists at that location. |
ref.cycle | error | Circular reference chain: "…". |
ref.type.mismatch | error | $ref "<actual>" resolves to a "<actualType>" token but this token is declared as "<expected>". |
extends
| Code | Severity | Message |
|---|---|---|
extends.target.missing | error | $extends "<actual>" does not resolve: no group at "<path>". |
extends.target.not-group | error | $extends "<actual>" must reference a group, but "<path>" is a token. |
extends.cycle | error | Circular group extension: "…". A group cannot extend itself, an ancestor, or a group that extends it. |
extends.inherited-token.invalid | error | Token "<token>" inherited from "<inheritedFrom>" is invalid in this group: "<reason>". |
composite
| Code | Severity | Message |
|---|---|---|
composite.property.missing | error | A "<type>" value must have a "<property>" property ("<expectedType>" value or reference). |
composite.value.not-object | error | A "<type>" value must be an object with "<properties>", received "<actualType>". |
stroke-style
| Code | Severity | Message |
|---|---|---|
stroke-style.value.invalid | error | A strokeStyle value must be a keyword string or an object with "dashArray" and "lineCap", received "<actualType>". |
stroke-style.keyword.invalid | error | Unknown stroke style "<actual>". Allowed: "…". Did you mean "<suggestion>"? Values are case-sensitive. |
stroke-style.dash-array.not-array | error | "dashArray" must be an array of dimension values or references, received "<actualType>". |
stroke-style.line-cap.invalid | error | "lineCap" must be one of "…", received "<actual>". Did you mean "<suggestion>"? Values are case-sensitive. |
shadow
| Code | Severity | Message |
|---|---|---|
shadow.value.invalid | error | A shadow value must be a shadow object or an array of shadow objects and references, received "<actualType>". |
shadow.item.invalid | error | Shadow entry "<index>" must be a shadow object or a reference to a shadow token, received "<actualType>". |
shadow.inset.not-boolean | error | "inset" must be true or false, received "<actualType>". |
gradient
| Code | Severity | Message |
|---|---|---|
gradient.value.not-array | error | A gradient value must be an array of gradient stops and references, received "<actualType>". |
gradient.stop.invalid | error | Gradient entry "<index>" must be a stop object with "color" and "position" or a reference to a gradient token, received "<actualType>". |
gradient.position.out-of-range | warning | Gradient stop position "<actual>" is outside [0, 1] and will be clamped by consumers. |
color
| Code | Severity | Message |
|---|---|---|
color.value.not-object | error | A color value must be an object with "colorSpace" and "components", received "<actualType>". |
color.color-space.missing | error | A color value must have a "colorSpace" property. |
color.color-space.invalid | error | Unsupported color space "<actual>". Supported: "…". Did you mean "<suggestion>"? Values are case-sensitive. |
color.components.missing | error | A color value must have a "components" array. |
color.components.not-array | error | "components" must be an array, received "<actualType>". |
color.components.wrong-length | error | "components" must have exactly "<expected>" entries for "<colorSpace>", received "<actual>". |
color.component.invalid | error | Color component "<index>" must be a number or "none", received "<actual>". |
color.component.out-of-range | error | Color component "<index>" ("<name>") of "<colorSpace>" must be in [<min>, <max>), received "<actual>". |
color.alpha.not-number | error | "alpha" must be a number, received "<actualType>". |
color.alpha.out-of-range | error | "alpha" must be in [0, 1], received "<actual>". |
color.hex.invalid | error | "hex" must be a 6-digit CSS hex color such as "#ff00ff", received "<actual>". |
color.hex.mismatch | warning | "hex" "<hex>" does not match the sRGB components (expected "<expected>"). |
dimension
| Code | Severity | Message |
|---|---|---|
dimension.value.not-object | error | A dimension value must be an object with "value" and "unit", received "<actualType>". |
dimension.value.missing | error | A dimension value must have a "value" property. |
dimension.value.not-number | error | Dimension "value" must be a number, received "<actualType>". |
dimension.unit.missing | error | A dimension value must have a "unit" property, even when "value" is 0. |
dimension.unit.invalid | error | Dimension "unit" must be one of "…", received "<actual>". Did you mean "<suggestion>"? Values are case-sensitive. |
font-family
| Code | Severity | Message |
|---|---|---|
font-family.value.invalid | error | A font family value must be a string or an array of strings, received "<actualType>". |
font-family.name.not-string | error | Font family entry "<index>" must be a string, received "<actualType>". |
font-weight
| Code | Severity | Message |
|---|---|---|
font-weight.value.invalid | error | A font weight value must be a number in [1, 1000] or a keyword, received "<actualType>". |
font-weight.number.out-of-range | error | Font weight must be in [1, 1000], received "<actual>". |
font-weight.keyword.invalid | error | Unknown font weight keyword "<actual>". Allowed: "…". Did you mean "<suggestion>"? Values are case-sensitive. |
duration
| Code | Severity | Message |
|---|---|---|
duration.value.not-object | error | A duration value must be an object with "value" and "unit", received "<actualType>". |
duration.value.missing | error | A duration value must have a "value" property. |
duration.value.not-number | error | Duration "value" must be a number, received "<actualType>". |
duration.unit.missing | error | A duration value must have a "unit" property. |
duration.unit.invalid | error | Duration "unit" must be one of "…", received "<actual>". Did you mean "<suggestion>"? Values are case-sensitive. |
cubic-bezier
| Code | Severity | Message |
|---|---|---|
cubic-bezier.value.not-array | error | A cubic Bézier value must be an array of four numbers, received "<actualType>". |
cubic-bezier.value.wrong-length | error | A cubic Bézier value must have exactly 4 numbers [P1x, P1y, P2x, P2y], received "<actual>". |
cubic-bezier.point.not-number | error | Cubic Bézier coordinate "<index>" must be a number, received "<actualType>". |
cubic-bezier.x.out-of-range | error | Cubic Bézier x coordinate "<index>" must be in [0, 1], received "<actual>". |
number
| Code | Severity | Message |
|---|---|---|
number.value.not-number | error | A number value must be a JSON number, received "<actualType>". |