visualspec.1.0 RC
GitHub
Module

Accessibility

How it is operated

Accessibility records the name, role, focus, and relationships a person needs in order to understand and operate the result. The contract is native-first: platform semantics come before ARIA, and ARIA is an explicit mapping when the web is the target.

Use this module when The visual result must be named, focused, or related to another control. If a sighted person can see the relationship, a non-visual user must get it from this module.

Keep in mind. Do not hide meaning that only exists in pixels. A button that looks like a button still needs a name.

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

name

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 1string

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
anyOf 2object

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

You may omit value, targetRef, and required. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
sourcerequired"content" | "literal" | "reference" | "derived"

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
  • "content"
  • "literal"
  • "reference"
  • "derived"
valuestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
targetRefid

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

requiredboolean

Write true or false.

Exact constraints
type
boolean

Smallest example

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

nameJSON
"example"

focus

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 strategy, trap, restoreOnClose, restore, initial, order, activation, and visible. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
strategy"natural" | "roving" | "active-descendant" | "programmatic" | "none"

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
  • "natural"
  • "roving"
  • "active-descendant"
  • "programmatic"
  • "none"
trapboolean

Write true or false.

Exact constraints
type
boolean
restoreOnCloseboolean

Write true or false.

Exact constraints
type
boolean
restoreboolean

Write true or false.

Exact constraints
type
boolean
initialstring

Write a text value.

An empty string is not allowed.

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

activation"automatic" | "manual"

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
  • "automatic"
  • "manual"
visibleboolean

Write true or false.

Exact constraints
type
boolean

Smallest example

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

focusJSON
{  "strategy": "natural",  "trap": true,  "restoreOnClose": true,  "restore": true}

relationships

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 controls, describedBy, details, flowTo, labelledBy, owns, and activeDescendant. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
controlsid | array<id>

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 2array<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.

describedByid | array<id>

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 2array<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.

detailsid | array<id>

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 2array<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.

flowToid | array<id>

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 2array<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.

labelledByid | array<id>

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 2array<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.

ownsid | array<id>

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 2array<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.

activeDescendantid

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

relationshipsJSON
{  "controls": {    "$ref": "common#id"  },  "describedBy": {    "$ref": "common#id"  },  "details": {    "$ref": "common#id"  },  "flowTo": {    "$ref": "common#id"  }}

accessibility

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

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

Exact constraints
type
object
additional properties
forbidden
semanticRoletaxonomy

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

roletaxonomy

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

namename

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

descriptionstring | name

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 1string

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
anyOf 2name

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

labelRequiredboolean

Write true or false.

Exact constraints
type
boolean
decorativeboolean

Write true or false.

Exact constraints
type
boolean
hiddenboolean

Write true or false.

Exact constraints
type
boolean
statesobject

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 checked, disabled, expanded, hidden, invalid, pressed, selected, and busy. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
checkedboolean | "mixed"

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 1boolean

Write true or false.

Exact constraints
type
boolean
anyOf 2"mixed"

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

Exact constraints
Allowed values
  • "mixed"
disabledboolean

Write true or false.

Exact constraints
type
boolean
expandedboolean

Write true or false.

Exact constraints
type
boolean
hiddenboolean

Write true or false.

Exact constraints
type
boolean
invalidboolean | "grammar" | "spelling"

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 1boolean

Write true or false.

Exact constraints
type
boolean
anyOf 2"grammar" | "spelling"

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
  • "grammar"
  • "spelling"
pressedboolean | "mixed"

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 1boolean

Write true or false.

Exact constraints
type
boolean
anyOf 2"mixed"

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

Exact constraints
Allowed values
  • "mixed"
selectedboolean

Write true or false.

Exact constraints
type
boolean
busyboolean

Write true or false.

Exact constraints
type
boolean
propertiesobject

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

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

Exact constraints
type
object
additional properties
forbidden
autocomplete"none" | "inline" | "list" | "both"

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
  • "none"
  • "inline"
  • "list"
  • "both"
hasPopupboolean | taxonomy

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 1boolean

Write true or false.

Exact constraints
type
boolean
anyOf 2taxonomy

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

levelinteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
multilineboolean

Write true or false.

Exact constraints
type
boolean
orientation"horizontal" | "vertical"

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
  • "horizontal"
  • "vertical"
placeholderstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
readonlyboolean

Write true or false.

Exact constraints
type
boolean
requiredboolean

Write true or false.

Exact constraints
type
boolean
valueMinnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
valueMaxnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
valueNownumber

Write a number. Decimals are allowed.

Exact constraints
type
number
valueTextstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
selectionMode"none" | "single" | "multiple"

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
  • "none"
  • "single"
  • "multiple"
relationshipsrelationships

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

focusfocus

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

keyboardobject
Exact constraints
type
object
additional properties
array<string>
additionalPropertiesarray<string>

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
itemsstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
inputModalitiesarray<"keyboard" | "pointer" | "touch" | "voice" | "switch" | "gamepad" | "spatial">

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
items"keyboard" | "pointer" | "touch" | "voice" | "switch" | "gamepad" | "spatial"

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
  • "keyboard"
  • "pointer"
  • "touch"
  • "voice"
  • "switch"
  • "gamepad"
  • "spatial"
readingOrderarray<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.

liveobject

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

Exact constraints
type
object
additional properties
forbidden
politeness"off" | "polite" | "assertive"

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
  • "off"
  • "polite"
  • "assertive"
atomicboolean

Write true or false.

Exact constraints
type
boolean
relevantarray<"additions" | "removals" | "text" | "all">

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
items"additions" | "removals" | "text" | "all"

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
  • "additions"
  • "removals"
  • "text"
  • "all"
textScalingobject

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

Exact constraints
type
object
additional properties
forbidden
enabledboolean

Write true or false.

Exact constraints
type
boolean
minnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
maxnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
contrastobject

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

Exact constraints
type
object
additional properties
forbidden
minimumRationumber

Write a number. Decimals are allowed.

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

Exact constraints
type
number
minimum
1
maximum
21
highContrastboolean

Write true or false.

Exact constraints
type
boolean
reducedMotion"respect" | "remove" | "reduce" | "substitute"

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
  • "respect"
  • "remove"
  • "reduce"
  • "substitute"
targetSizeobject

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.

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
ariaobject

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 preferNative, htmlElement, role, and attributes. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
preferNativeboolean

Write true or false.

Exact constraints
type
boolean
htmlElementstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
roletaxonomy

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

attributesobject
Exact constraints
type
object
additional properties
string | boolean | number
additionalPropertiesstring | boolean | number

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 2boolean

Write true or false.

Exact constraints
type
boolean
anyOf 3number

Write a number. Decimals are allowed.

Exact constraints
type
number
platformMappingsobject
Exact constraints
type
object
additional properties
object
additionalPropertiesobject

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 role, label, traits, and properties. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
rolestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
labelstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
traitsarray<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
propertiesobject
Exact constraints
type
object
additional properties
string | boolean | number
additionalPropertiesstring | boolean | number

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 2boolean

Write true or false.

Exact constraints
type
boolean
anyOf 3number

Write a number. Decimals are allowed.

Exact constraints
type
number
motionPolicyobject

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

Exact constraints
type
object
additional properties
forbidden
respectSystemPreferenceboolean

Write true or false.

Exact constraints
type
boolean
requireReducedAlternativeboolean

Write true or false.

Exact constraints
type
boolean
essentialMotionRequiresJustificationboolean

Write true or false.

Exact constraints
type
boolean
conformance"WCAG-2.2-A" | "WCAG-2.2-AA" | "WCAG-2.2-AAA"

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
  • "WCAG-2.2-A"
  • "WCAG-2.2-AA"
  • "WCAG-2.2-AAA"
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.

accessibilityJSON
{  "semanticRole": {    "$ref": "common#taxonomy"  },  "role": {    "$ref": "common#taxonomy"  },  "name": {    "$ref": "accessibility#name"  },  "description": "example"}