visualspec.1.0 RC
GitHub
Module

Semantics

Meaning, separate from pixels

The semantic tree says what something means and how it should be read. It is not the scene tree. A decorative shape can exist in the scene and be absent here. A heading can be a heading even when it is drawn as a path.

Use this module when Reading order, role, or grouping would be lost if you only stored rectangles.

Keep in mind. Do not mirror every visual node into the semantic tree. Only what carries meaning belongs here.

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

semanticNode

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

You may omit name, nodeRef, entityRef, componentRef, accessibility, children, relationshipRefs, 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.

rolerequiredtaxonomy

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.

nodeRefid

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

entityRefid

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

componentRefid

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

accessibilityaccessibility

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

childrenarray<semanticNode>

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

Exact constraints
type
array
itemssemanticNode

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

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

Smallest example

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

semanticNodeJSON
{  "id": {    "$ref": "common#id"  },  "role": {    "$ref": "common#taxonomy"  }}