visualspec.1.0 RC
GitHub
Module

Common

Shared vocabulary

Almost every other module borrows from Common. It does not describe a screen, a shot, or a scene. It describes the small reusable values those things are built from: identifiers, times, sizes, colors-as-tokens, evidence, and the metadata of the document itself.

Use this module when You need a stable id, a duration, a length, a point in space, a condition, or a record of where a value came from. If two modules would otherwise invent their own spelling for “an id” or “two seconds”, they use a definition from here instead.

Keep in mind. An id names something inside this document. It is not a CSS selector, a file path, or a URL. References resolve locally. Nothing in Common is allowed to fetch the network.

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

id

Stable document-wide identifier; references resolve locally, never through network execution.

Write a text value.

The text must match the pattern ^[A-Za-z_][A-Za-z0-9_.:/-]*$. That pattern is the contract for which characters are allowed.

An empty string is not allowed.

Exact constraints
type
string
pattern
^[A-Za-z_][A-Za-z0-9_.:/-]*$
min length
1

Smallest example

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

idJSON
"example"

taxonomy

Open taxonomy. Standard terms and namespaced vendor terms are accepted.

Write a text value.

The text must match the pattern ^[a-zA-Z][a-zA-Z0-9_-]*(?:[.:/][a-zA-Z0-9_-]+)*$. That pattern is the contract for which characters are allowed.

An empty string is not allowed.

Exact constraints
type
string
pattern
^[a-zA-Z][a-zA-Z0-9_-]*(?:[.:/][a-zA-Z0-9_-]+)*$
min length
1

Smallest example

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

taxonomyJSON
"example"

uri

Write a text value.

The text should be a uri-reference. Validators that understand this format will reject values that do not look like one.

An empty string is not allowed.

Exact constraints
type
string
format
uri-reference
min length
1

Smallest example

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

uriJSON
"https://example.com/resource"

time

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

anyOf 1number

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
anyOf 2string

Nonnegative time in seconds (number), an ms/s/f string, or {value,unit}.

Write a text value.

The text must match the pattern ^(?:0|[0-9]+(?:\.[0-9]+)?)(?:ms|s|f)$. That pattern is the contract for which characters are allowed.

Exact constraints
type
string
pattern
^(?:0|[0-9]+(?:\.[0-9]+)?)(?:ms|s|f)$
anyOf 3object

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 value and unit.

Exact constraints
type
object
additional properties
forbidden
valuerequirednumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
unitrequired"ms" | "s" | "f"

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
  • "ms"
  • "s"
  • "f"

Smallest example

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

timeJSON
0

duration

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

anyOf 1number

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
anyOf 2string

Write a text value.

The text must match the pattern ^(?:0|[0-9]+(?:\.[0-9]+)?)(?:ms|s|f)$. That pattern is the contract for which characters are allowed.

Exact constraints
type
string
pattern
^(?:0|[0-9]+(?:\.[0-9]+)?)(?:ms|s|f)$
anyOf 3object

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 value and unit.

Exact constraints
type
object
additional properties
forbidden
valuerequirednumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
unitrequired"ms" | "s" | "f"

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
  • "ms"
  • "s"
  • "f"

Smallest example

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

durationJSON
0

delay

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

anyOf 1number

Write a number. Decimals are allowed.

Exact constraints
type
number
anyOf 2string

Write a text value.

The text must match the pattern ^-?(?:0|[0-9]+(?:\.[0-9]+)?)(?:ms|s|f)$. That pattern is the contract for which characters are allowed.

Exact constraints
type
string
pattern
^-?(?:0|[0-9]+(?:\.[0-9]+)?)(?:ms|s|f)$
anyOf 3object

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 value and unit.

Exact constraints
type
object
additional properties
forbidden
valuerequirednumber

Write a number. Decimals are allowed.

Exact constraints
type
number
unitrequired"ms" | "s" | "f"

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
  • "ms"
  • "s"
  • "f"

Smallest example

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

delayJSON
0

dimension

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

anyOf 1number

Write a number. Decimals are allowed.

Exact constraints
type
number
anyOf 2string

Write a text value.

The text must match the pattern ^-?[0-9]+(?:\.[0-9]+)?(?:px|%|rem|em|pt|mm|cm|in|vw|vh|vmin|vmax|m)$. That pattern is the contract for which characters are allowed.

Exact constraints
type
string
pattern
^-?[0-9]+(?:\.[0-9]+)?(?:px|%|rem|em|pt|mm|cm|in|vw|vh|vmin|vmax|m)$
anyOf 3object

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 value and unit.

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

Exact constraints
type
object
additional properties
forbidden
valuerequirednumber

Write a number. Decimals are allowed.

Exact constraints
type
number
unitrequired"px" | "%" | "rem" | "em" | "pt" | "mm" | "cm" | "in" | "vw" | "vh" | "m"

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

Exact constraints
Allowed values
  • "px"
  • "%"
  • "rem"
  • "em"
  • "pt"
  • "mm"
  • "cm"
  • "in"
  • "vw"
  • "vh"
  • "m"
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.

anyOf 4tokenRef

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

dimensionJSON
0

size

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

anyOf 1number

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
anyOf 2string

Write a text value.

The text must match the pattern ^[0-9]+(?:\.[0-9]+)?(?:px|%|rem|em|pt|mm|cm|in|vw|vh|vmin|vmax|m)$. That pattern is the contract for which characters are allowed.

Exact constraints
type
string
pattern
^[0-9]+(?:\.[0-9]+)?(?:px|%|rem|em|pt|mm|cm|in|vw|vh|vmin|vmax|m)$
anyOf 3"auto" | "fill" | "hug" | "min-content" | "max-content"

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
  • "auto"
  • "fill"
  • "hug"
  • "min-content"
  • "max-content"
anyOf 4tokenRef

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

sizeJSON
0

tokenRef

Write a text value.

The text must match the pattern ^\{[A-Za-z_][A-Za-z0-9_.-]*\}$. That pattern is the contract for which characters are allowed.

Exact constraints
type
string
pattern
^\{[A-Za-z_][A-Za-z0-9_.-]*\}$

Smallest example

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

tokenRefJSON
""

jsonValue

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

anyOf 1string | number | boolean | null

Write a text value.

Exact constraints
type
string | number | boolean | null
anyOf 2array<jsonValue>

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

Exact constraints
type
array
itemsjsonValue

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

anyOf 3object
Exact constraints
type
object
additional properties
jsonValue
additionalPropertiesjsonValue

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

jsonValueJSON
""

extensions

Only namespaced extension keys are allowed. Unknown optional extensions may be retained without interpretation.

Exact constraints
type
object
additional properties
jsonValue
additionalPropertiesjsonValue

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

extensionsJSON
{}

provenance

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

You may omit sourceRef, tool, agent, timestamp, and notes. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
sourceRefid

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

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

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

Exact constraints
Allowed values
  • "explicit"
  • "measured"
  • "extracted"
  • "inferred"
  • "generated"
  • "defaulted"
  • "platform-derived"
  • "vision-inference"
  • "reference-derived"
toolstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
agentstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
timestampstring

Write a text value.

The text should be a date-time. Validators that understand this format will reject values that do not look like one.

Exact constraints
type
string
format
date-time
notesstring

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.

provenanceJSON
{  "method": "explicit"}

evidence

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

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

Exact constraints
type
object
additional properties
forbidden
statusrequired"explicit" | "measured" | "extracted" | "inferred" | "generated" | "defaulted" | "platform-derived" | "unknown"

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

Exact constraints
Allowed values
  • "explicit"
  • "measured"
  • "extracted"
  • "inferred"
  • "generated"
  • "defaulted"
  • "platform-derived"
  • "unknown"
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.

Smallest example

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

evidenceJSON
{  "status": "explicit"}

vector2

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 x and y.

Exact constraints
type
object
additional properties
forbidden
xrequirednumber

Write a number. Decimals are allowed.

Exact constraints
type
number
yrequirednumber

Write a number. Decimals are allowed.

Exact constraints
type
number

Smallest example

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

vector2JSON
{  "x": 0,  "y": 0}

vector3

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 x, y, and z.

Exact constraints
type
object
additional properties
forbidden
xrequirednumber

Write a number. Decimals are allowed.

Exact constraints
type
number
yrequirednumber

Write a number. Decimals are allowed.

Exact constraints
type
number
zrequirednumber

Write a number. Decimals are allowed.

Exact constraints
type
number

Smallest example

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

vector3JSON
{  "x": 0,  "y": 0,  "z": 0}

quaternion

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 x, y, z, and w.

Exact constraints
type
object
additional properties
forbidden
xrequirednumber

Write a number. Decimals are allowed.

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

Exact constraints
type
number
minimum
-1
maximum
1
yrequirednumber

Write a number. Decimals are allowed.

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

Exact constraints
type
number
minimum
-1
maximum
1
zrequirednumber

Write a number. Decimals are allowed.

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

Exact constraints
type
number
minimum
-1
maximum
1
wrequirednumber

Write a number. Decimals are allowed.

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

Exact constraints
type
number
minimum
-1
maximum
1

Smallest example

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

quaternionJSON
{  "x": -1,  "y": -1,  "z": -1,  "w": -1}

bounds

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 x, y, width, and height.

You may omit z, depth, and coordinateSpace. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
xrequirednumber

Write a number. Decimals are allowed.

Exact constraints
type
number
yrequirednumber

Write a number. Decimals are allowed.

Exact constraints
type
number
znumber

Write a number. Decimals are allowed.

Exact constraints
type
number
widthrequirednumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
heightrequirednumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
depthnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
coordinateSpacecoordinateSpace

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

boundsJSON
{  "x": 0,  "y": 0,  "width": 0,  "height": 0}

coordinateSpace

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

Exact constraints
Allowed values
  • "absolute"
  • "normalized"
  • "local"
  • "parent"
  • "viewport"
  • "world"
  • "camera"
  • "screen"
  • "document"

Smallest example

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

coordinateSpaceJSON
"absolute"

viewport

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 width and height.

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

Exact constraints
type
object
additional properties
forbidden
widthrequirednumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
heightrequirednumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
pixelRationumber

Write a number. Decimals are allowed.

Exact constraints
type
number
exclusive minimum
0
orientation"portrait" | "landscape"

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

Exact constraints
Allowed values
  • "portrait"
  • "landscape"

Smallest example

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

viewportJSON
{  "width": 0,  "height": 0}

condition

Declarative visual conditions only; no executable expressions or gameplay logic.

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 stateRef, eventRef, capability, equals, not, all, and any. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
stateRefid

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

eventRefid

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

capabilitytaxonomy

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

equalsstring | number | boolean

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

anyOf 1string

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
anyOf 2number

Write a number. Decimals are allowed.

Exact constraints
type
number
anyOf 3boolean

Write true or false.

Exact constraints
type
boolean
notboolean

Write true or false.

Exact constraints
type
boolean
allarray<condition>

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
itemscondition

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

anyarray<condition>

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
itemscondition

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

conditionJSON
{  "stateRef": {    "$ref": "common#id"  },  "eventRef": {    "$ref": "common#id"  },  "capability": {    "$ref": "common#taxonomy"  },  "equals": "example"}

metadata

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

You may omit id, description, version, language, authors, license, created, modified, tags, status, links, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idid

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

titlerequiredstring

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
versionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
languagestring

Write a text value.

The text must match the pattern ^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$. That pattern is the contract for which characters are allowed.

Exact constraints
type
string
pattern
^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$
authorsarray<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 name.

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

Exact constraints
type
object
additional properties
forbidden
namerequiredstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
urluri

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

emailstring

Write a text value.

The text should be a email. Validators that understand this format will reject values that do not look like one.

Exact constraints
type
string
format
email
licensestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
createdstring

Write a text value.

The text should be a date-time. Validators that understand this format will reject values that do not look like one.

Exact constraints
type
string
format
date-time
modifiedstring

Write a text value.

The text should be a date-time. Validators that understand this format will reject values that do not look like one.

Exact constraints
type
string
format
date-time
tagsarray<string>

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
itemsstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
status"draft" | "review" | "approved" | "deprecated"

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

Exact constraints
Allowed values
  • "draft"
  • "review"
  • "approved"
  • "deprecated"
linksobject
Exact constraints
type
object
additional properties
uri
additionalPropertiesuri

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

metadataJSON
{  "title": "example"}