visualspec.1.0 RC
GitHub
Module

Validation

How to judge the result

Validation records what “correct” means: structural checks, semantic checks, accessibility checks, visual tolerances, and reference comparisons. It turns “looks right” into evidence someone else can rerun.

Use this module when A later review has to decide whether an implementation matched the document.

Keep in mind. JSON Schema checks shape. This module records the extra expectations schema cannot express, including how much visual difference is acceptable.

Raw schema:/schema/1.0/modules/validation.schema.json · https://visualspec.dev/schema/1.0/modules/validation.schema.json

How to read a definition.The paragraphs say what to write and why. “Exact constraints” opens the schema keywords (type, pattern, bounds) for people checking a validator. A sample at the bottom of each definition is the smallest JSON that shows the required shape. Values such as $ref inside a sample point at another definition. They are not fields you copy into a document.

tolerance

Comparison thresholds; metric-specific interpretation is declared by the validator.

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You may omit absolute, relative, and unit. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
absolutenumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
relativenumber

Write a number. Decimals are allowed.

The number must sit between 0 and 1, including both ends.

Exact constraints
type
number
minimum
0
maximum
1
unitstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

toleranceJSON
{  "absolute": 0,  "relative": 0,  "unit": "example"}

rule

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include id and type.

14 other fields are optional. Include one only when you have a real value for it.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

typerequired"schema" | "semantic" | "capability" | "accessibility" | "visual" | "reference-conformance"

Pick one of the 6 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "schema"
  • "semantic"
  • "capability"
  • "accessibility"
  • "visual"
  • "reference-conformance"
targetRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

referenceRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

aspecttaxonomy

This is not a new shape. It reuses taxonomy from the common module. Open that definition for the fields you can write.

metrictaxonomy

This is not a new shape. It reuses taxonomy from the common module. Open that definition for the fields you can write.

matchMode"exact" | "structural" | "perceptual" | "semantic" | "stylistic" | "inspirational"

Pick one of the 6 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "exact"
  • "structural"
  • "perceptual"
  • "semantic"
  • "stylistic"
  • "inspirational"
conformance"strict" | "approximate" | "inspiration"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "strict"
  • "approximate"
  • "inspiration"
tolerancetolerance

This is not a new shape. It reuses tolerance from the validation module. Open that definition for the fields you can write.

severity"error" | "warning" | "info"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "error"
  • "warning"
  • "info"
requiredboolean

Write true or false.

Exact constraints
type
boolean
descriptionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
viewportviewport

This is not a new shape. It reuses viewport from the common module. Open that definition for the fields you can write.

stateRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

timetime

This is not a new shape. It reuses time from the common module. Open that definition for the fields you can write.

extensionsextensions

This is not a new shape. It reuses extensions from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

ruleJSON
{  "id": {    "$ref": "common#id"  },  "type": "schema"}

validation

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You may omit schema, semantic, accessibility, capabilities, rules, referenceConformance, failOn, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
schemaboolean

Write true or false.

Exact constraints
type
boolean
semanticboolean

Write true or false.

Exact constraints
type
boolean
accessibilityboolean

Write true or false.

Exact constraints
type
boolean
capabilitiesboolean

Write true or false.

Exact constraints
type
boolean
rulesarray<rule>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemsrule

This is not a new shape. It reuses rule from the validation module. Open that definition for the fields you can write.

referenceConformancearray<object>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemsobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include referenceRef, aspect, and conformance.

You may omit matchMode and tolerance. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
referenceRefrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

aspectrequiredtaxonomy

This is not a new shape. It reuses taxonomy from the common module. Open that definition for the fields you can write.

conformancerequired"strict" | "approximate" | "inspiration"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "strict"
  • "approximate"
  • "inspiration"
matchMode"exact" | "structural" | "perceptual" | "semantic" | "stylistic" | "inspirational"

Pick one of the 6 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "exact"
  • "structural"
  • "perceptual"
  • "semantic"
  • "stylistic"
  • "inspirational"
tolerancetolerance

This is not a new shape. It reuses tolerance from the validation module. Open that definition for the fields you can write.

failOn"error" | "warning" | "info"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "error"
  • "warning"
  • "info"
extensionsextensions

This is not a new shape. It reuses extensions from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

validationJSON
{  "schema": true,  "semantic": true,  "accessibility": true,  "capabilities": true}