visualspec.1.0 RC
GitHub
Module

World

What exists

The world answers “what is this thing?” independently of one picture of it. An entity keeps its identity when it appears in another scene. Environments, representations, and relationships live here.

Use this module when The same cup, character, or product must stay the same object across views, shots, or UI states.

Keep in mind. A scene shows an entity. It does not create a second entity. If you only have a drawing and no lasting identity, you may only need a scene.

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

environment

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

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

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.

kindrequiredtaxonomy

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

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

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

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

skyobject

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

Exact constraints
type
object
additional properties
forbidden
colorcolor

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

type"solid" | "gradient" | "image" | "procedural"

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
  • "solid"
  • "gradient"
  • "image"
  • "procedural"
terrainobject

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

Exact constraints
type
object
additional properties
forbidden
entityRefid

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.

elevationnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
weathertaxonomy

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

timeOfDay"dawn" | "morning" | "noon" | "afternoon" | "dusk" | "night" | string

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 1"dawn" | "morning" | "noon" | "afternoon" | "dusk" | "night"

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
  • "dawn"
  • "morning"
  • "noon"
  • "afternoon"
  • "dusk"
  • "night"
anyOf 2string

Write a text value.

The text must match the pattern ^(?:[01][0-9]|2[0-3]):[0-5][0-9]$. That pattern is the contract for which characters are allowed.

Exact constraints
type
string
pattern
^(?:[01][0-9]|2[0-3]):[0-5][0-9]$
season"spring" | "summer" | "autumn" | "winter"

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
  • "spring"
  • "summer"
  • "autumn"
  • "winter"
temperaturenumber

Write a number. Decimals are allowed.

Exact constraints
type
number
fogobject

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 density, color, near, and far. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
densitynumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
colorcolor

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

nearnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
farnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
hazenumber

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

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.

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.

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.

environmentJSON
{  "kind": {    "$ref": "common#taxonomy"  }}

representation

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

You may omit id, assetRef, nodeRef, componentRef, sceneRef, variant, condition, levelOfDetail, referenceRefs, 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.

typerequired"image" | "video" | "vector" | "3d" | "illustration" | "generated" | "ui" | "text" | "procedural"

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
  • "image"
  • "video"
  • "vector"
  • "3d"
  • "illustration"
  • "generated"
  • "ui"
  • "text"
  • "procedural"
assetRefid

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

componentRefid

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

sceneRefid

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

variantstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
conditioncondition

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

levelOfDetailinteger

Write a whole number.

The number must be at least 0.

Exact constraints
type
integer
minimum
0
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.

Smallest example

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

representationJSON
{  "type": "image"}

entity

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.

20 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
roletaxonomy

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

transformtransform

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

representationrepresentation

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

representationsarray<representation>

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
itemsrepresentation

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

visibilityobject

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 visible, occluded, opacity, and layers. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
visibleboolean

Write true or false.

Exact constraints
type
boolean
occludedboolean

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
layersarray<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
presenceobject

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

Exact constraints
type
object
additional properties
forbidden
fromtime

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

totime

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

conditioncondition

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

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

lifecycle"persistent" | "ephemeral" | "generated" | "derived" | "conditional" | "tracked" | "procedural"

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
  • "persistent"
  • "ephemeral"
  • "generated"
  • "derived"
  • "conditional"
  • "tracked"
  • "procedural"
partsarray<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.

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

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

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

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

identityobject

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

Exact constraints
type
object
additional properties
forbidden
persistentKeystring

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
descriptionstring

Write a text value.

An empty string is not allowed.

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

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.

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

relationship

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, type, sourceRef, and targetRef.

You may omit strength, temporal, confidence, 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.

typerequiredtaxonomy

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

sourceRefrequiredid

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

targetRefrequiredid

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

strengthnumber

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
temporalobject

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

Exact constraints
type
object
additional properties
forbidden
fromtime

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

totime

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

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.

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.

relationshipJSON
{  "id": {    "$ref": "common#id"  },  "type": {    "$ref": "common#taxonomy"  },  "sourceRef": {    "$ref": "common#id"  },  "targetRef": {    "$ref": "common#id"  }}

world

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 id, name, environment, sceneRefs, entityRefs, cameraRefs, lightRefs, effectRefs, coordinateSystem, 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.

namestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
environmentenvironment

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

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

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.

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

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.

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.

coordinateSystemobject

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 handedness, upAxis, unit, and origin. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
handedness"left" | "right"

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
  • "left"
  • "right"
upAxis"x" | "y" | "z"

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
  • "x"
  • "y"
  • "z"
unit"px" | "m" | "cm" | "mm"

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
  • "px"
  • "m"
  • "cm"
  • "mm"
originvector3

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

worldJSON
{  "id": {    "$ref": "common#id"  },  "name": "example",  "environment": {    "$ref": "world#environment"  },  "sceneRefs": []}