visualspec.1.0 RC
GitHub
Module

References

Evidence

A reference points at the evidence behind a visual decision: a region of an image, a moment in a video, a node in a design file, a page in a PDF. The reference says what to look at and which aspects it constrains. It does not paste the asset into the document and it does not override an explicit requirement by itself.

Use this module when Someone needs to know why a color, a crop, a type style, or a motion exists. Record the source, how to find the exact part, and what that part is allowed to decide.

Keep in mind. A reference is not executable content. Tools must not treat a URL or a selector as instructions to run.

Raw schema:/schema/1.0/modules/references.schema.json · https://visualspec.dev/schema/1.0/modules/references.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.

source

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 kind.

You may omit uri, title, description, mediaType, checksum, version, license, provenance, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

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.

kindrequiredtaxonomy

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

uriuri

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

titlestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
descriptionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
mediaTypestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
checksumstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
versionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
licensestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
provenanceprovenance

This is not a new shape. It reuses provenance 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.

sourceJSON
{  "id": {    "$ref": "common#id"  },  "kind": {    "$ref": "common#taxonomy"  }}

locator

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 region, dom, viewport, figma, pdf, presentation, video, scene3d, document, image, and text. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
regionbounds

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

domobject

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 cssSelector, xpath, text, and shadowPath. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
cssSelectorstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
xpathstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
textstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
shadowPatharray<string>

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

Exact constraints
type
array
itemsstring

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.

figmaobject

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 fileKey and nodeId.

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

Exact constraints
type
object
additional properties
forbidden
fileKeyrequiredstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
nodeIdrequiredstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
pageIdstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
versionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
pdfobject

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 page.

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

Exact constraints
type
object
additional properties
forbidden
pagerequiredinteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
regionbounds

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

presentationobject

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 slide.

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

Exact constraints
type
object
additional properties
forbidden
sliderequiredinteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
shapeIdstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
videoobject

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 start, end, frame, track, and fps. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
starttime

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

endtime

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

frameinteger

Write a whole number.

The number must be at least 0.

Exact constraints
type
integer
minimum
0
trackinteger

Write a whole number.

The number must be at least 0.

Exact constraints
type
integer
minimum
0
fpsnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
exclusive minimum
0
scene3dobject

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 scene, node, camera, and material. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
scenestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
nodestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
camerastring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
materialstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
documentobject

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 section, heading, paragraph, and bookmark. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
sectionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
headingstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
paragraphinteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
bookmarkstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
imageobject

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 region and frame. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
regionbounds

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

frameinteger

Write a whole number.

The number must be at least 0.

Exact constraints
type
integer
minimum
0
textobject

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 start and end. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
startinteger

Write a whole number.

The number must be at least 0.

Exact constraints
type
integer
minimum
0
endinteger

Write a whole number.

The number must be at least 0.

Exact constraints
type
integer
minimum
0

Smallest example

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

locatorJSON
{  "region": {    "$ref": "common#bounds"  },  "dom": {    "cssSelector": "example",    "xpath": "example",    "text": "example",    "shadowPath": []  },  "viewport": {    "$ref": "common#viewport"  },  "figma": {    "fileKey": "example",    "nodeId": "example"  }}

reference

Evidence may be located externally, but validators must never fetch or execute it implicitly.

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, kind, and role.

15 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.

kindrequiredtaxonomy

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

rolerequired"source-of-truth" | "preferred" | "supporting" | "inspiration" | "avoid"

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

Exact constraints
Allowed values
  • "source-of-truth"
  • "preferred"
  • "supporting"
  • "inspiration"
  • "avoid"
uriuri

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

sourceRefid

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

textstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
locatorlocator

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

aspectsarray<taxonomy>

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

The list needs at least 1 item.

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
min items
1
unique items
true
itemstaxonomy

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

weightnumber

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
priorityinteger

Write a whole number.

The number must be at least 0.

Exact constraints
type
integer
minimum
0
confidencenumber

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
provenanceprovenance

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

descriptionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
referenceRefsarray<id>

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

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
unique items
true
itemsid

This is not a new shape. It reuses id 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.

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"
conformanceobject
Exact constraints
type
object
additional properties
"strict" | "approximate" | "inspiration"
additionalProperties"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.

Smallest example

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

referenceJSON
{  "id": {    "$ref": "common#id"  },  "kind": {    "$ref": "common#taxonomy"  },  "role": "source-of-truth"}

binding

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.

You may omit aspects, weight, and priority. 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.

aspectsarray<taxonomy>

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

The list needs at least 1 item.

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
min items
1
unique items
true
itemstaxonomy

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

weightnumber

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
priorityinteger

Write a whole number.

The number must be at least 0.

Exact constraints
type
integer
minimum
0

Smallest example

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

bindingJSON
{  "referenceRef": {    "$ref": "common#id"  }}

referenceSet

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, references, and conflictPolicy.

You may omit title, aspectPriority, description, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

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.

titlestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
referencesrequiredarray<id | binding>

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

The list needs at least 1 item.

Exact constraints
type
array
min items
1
itemsid | binding

More than one shape is accepted. Use exactly one of the 2 alternatives below. They are different ways to say the same kind of value.

anyOf 1id

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

anyOf 2binding

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

conflictPolicyrequired"priority" | "first-wins" | "last-wins" | "weighted" | "most-specific" | "explicit-over-inferred" | "error"

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

Exact constraints
Allowed values
  • "priority"
  • "first-wins"
  • "last-wins"
  • "weighted"
  • "most-specific"
  • "explicit-over-inferred"
  • "error"
aspectPriorityobject
Exact constraints
type
object
additional properties
array<id>
additionalPropertiesarray<id>

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

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
unique items
true
itemsid

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

descriptionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
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.

referenceSetJSON
{  "id": {    "$ref": "common#id"  },  "references": [    {      "$ref": "common#id"    }  ],  "conflictPolicy": "priority"}

assertion

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 path and method.

You may omit source, sourceRef, and confidence. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
pathrequiredstring

JSON Pointer into this document.

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
sourcestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
sourceRefid

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

methodrequired"direct" | "derived" | "inferred" | "manual" | "generated" | "validated" | "explicit" | "measured" | "extracted" | "vision-inference" | "reference-derived" | "defaulted" | "platform-derived"

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

Exact constraints
Allowed values
  • "direct"
  • "derived"
  • "inferred"
  • "manual"
  • "generated"
  • "validated"
  • "explicit"
  • "measured"
  • "extracted"
  • "vision-inference"
  • "reference-derived"
  • "defaulted"
  • "platform-derived"
confidencenumber

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

Smallest example

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

assertionJSON
{  "path": "example",  "method": "direct"}