visualspec.1.0 RC
GitHub
Module

Scene

What is shown

A scene is one renderable arrangement: the nodes you would see in a given view, their content, and links back to semantics, entities, and components. A document can have many scenes.

Use this module when You are describing a specific composition: a screen, a slide frame, a shot, or a 3D view.

Keep in mind. Do not store identity only on the scene node. If the thing must survive the next scene, give it an entity in World.

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

content

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 text, assetRef, alt, runs, fit, objectPosition, and chart. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
textstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
assetRefid

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

altstring

Write a text value.

An empty string is not allowed.

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

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

Exact constraints
type
object
additional properties
forbidden
textrequiredstring

Write a text value.

Exact constraints
type
string
typographytypography

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

colorcolor

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

fit"contain" | "cover" | "fill" | "none" | "scale-down"

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
  • "contain"
  • "cover"
  • "fill"
  • "none"
  • "scale-down"
objectPositionvector2

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

chartchart

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

Smallest example

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

contentJSON
{  "text": "example",  "assetRef": {    "$ref": "common#id"  },  "alt": "example",  "runs": []}

node

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.

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

namestring

Write a text value.

An empty string is not allowed.

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

semanticRefid

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

assetRefid

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

materialRefid

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

instanceOfid

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.

Exact constraints
type
string
contentcontent

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

geometrygeometry

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

layoutlayout

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

appearanceappearance

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

transformtransform

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

boundsbounds

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

responsiveresponsive

This is not a new shape. It reuses responsive from the layout 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<node>

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

Exact constraints
type
array
itemsnode

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

visibleboolean

Write true or false.

Exact constraints
type
boolean
layerstring

Write a text value.

An empty string is not allowed.

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

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

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

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

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

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

spatialUIspatialUI

This is not a new shape. It reuses spatialUI from the game 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.

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

scene

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

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.

namestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
kindrequired"2d" | "2.5d" | "3d"

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
  • "2d"
  • "2.5d"
  • "3d"
nodesrequiredarray<node>

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

Exact constraints
type
array
itemsnode

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

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

cameraRefid

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

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

layersarray<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 id.

You may omit name, order, visible, and opacity. 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.

namestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
orderinteger

Write a whole number.

Exact constraints
type
integer
visibleboolean

Write true or false.

Exact constraints
type
boolean
opacitynumber

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
environmentenvironment

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

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

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

viewportviewport

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

backgroundpaint

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

coordinateSpacecoordinateSpace

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

timelineRefid

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

layoutlayout

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

sceneJSON
{  "id": {    "$ref": "common#id"  },  "kind": "2d",  "nodes": []}