visualspec.1.0 RC
GitHub
Module

Three D

Spatial models

This module adds 3D structure the shared scene does not carry alone: meshes, skeletons, skinning, rigs, levels of detail, and morph targets. It is intent for a spatial object, not a private scene-graph dump.

Use this module when The profile is 3d, or a UI embeds a 3D product that has real geometry.

Keep in mind. Level of detail is a declared alternative, not an excuse to drop a required silhouette.

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

joint

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, parentRef, transform, and inverseBindMatrix. 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
parentRefid

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

inverseBindMatrixarray<number>

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

The list needs at least 16 items.

The list allows at most 16 items.

Exact constraints
type
array
min items
16
max items
16
itemsnumber

Write a number. Decimals are allowed.

Exact constraints
type
number

Smallest example

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

jointJSON
{  "id": {    "$ref": "common#id"  }}

skeleton

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

You may omit rootRef 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.

jointsrequiredarray<joint>

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
itemsjoint

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

rootRefid

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.

skeletonJSON
{  "id": {    "$ref": "common#id"  },  "joints": [    {      "$ref": "three-d#joint"    }  ]}

mesh

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 assetRef, geometry, materialRefs, skeletonRef, skin, morphTargets, lod, instanceRefs, 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.

assetRefid

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

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

skeletonRefid

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

skinobject

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

Exact constraints
type
object
additional properties
forbidden
jointRefsarray<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.

weightsAssetRefid

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

bindPoseAssetRefid

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

morphTargetsarray<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, assetRef, and weight. 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
assetRefid

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

weightnumber

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

You may omit assetRef, meshRef, and screenCoverage. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
distancerequirednumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
assetRefid

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

meshRefid

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

screenCoveragenumber

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

meshJSON
{  "id": {    "$ref": "common#id"  }}

rig

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 skeletonRef, assetRef, controls, 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.

skeletonRefid

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.

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

You may omit jointRefs and targetRef. 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.

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

kindrequired"fk" | "ik" | "look-at" | "constraint"

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
  • "fk"
  • "ik"
  • "look-at"
  • "constraint"
targetRefid

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.

rigJSON
{  "id": {    "$ref": "common#id"  }}

threeD

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 sceneRefs, meshes, skeletons, rigs, assetRefs, animationRefs, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
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.

meshesarray<mesh>

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

Exact constraints
type
array
itemsmesh

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

skeletonsarray<skeleton>

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

Exact constraints
type
array
itemsskeleton

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

rigsarray<rig>

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

Exact constraints
type
array
itemsrig

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

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

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

threeDJSON
{  "sceneRefs": [],  "meshes": [],  "skeletons": [],  "rigs": []}