visualspec.1.0 RC
GitHub
Module

Media

Pictures, illustration, and moving images

Media specializes the shared core for still images, illustration, captions, shots, video projects, and charts. It adds the words those profiles need without inventing a second document format.

Use this module when The profile is image, illustration, video, or a chart, and the generic scene fields are not specific enough.

Keep in mind. A chart is a visual claim about data. Record the mapping. Do not leave the reader to guess which bar means which value.

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

composition

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

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

sceneRefrequiredid

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.

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

intentstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
stylestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
rulesarray<"rule-of-thirds" | "golden-ratio" | "symmetry" | "leading-lines" | "centered" | "diagonal" | "radial" | "free">

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"rule-of-thirds" | "golden-ratio" | "symmetry" | "leading-lines" | "centered" | "diagonal" | "radial" | "free"

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

Exact constraints
Allowed values
  • "rule-of-thirds"
  • "golden-ratio"
  • "symmetry"
  • "leading-lines"
  • "centered"
  • "diagonal"
  • "radial"
  • "free"
subjectPlacementarray<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 entityRef and bounds.

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

Exact constraints
type
object
additional properties
forbidden
entityRefrequiredid

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

boundsrequiredbounds

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

priorityinteger

Write a whole number.

The number must be at least 0.

Exact constraints
type
integer
minimum
0
negativeSpacearray<bounds>

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

Exact constraints
type
array
itemsbounds

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

balance"symmetric" | "asymmetric" | "radial"

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
  • "symmetric"
  • "asymmetric"
  • "radial"
depth"flat" | "layered" | "deep"

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
  • "flat"
  • "layered"
  • "deep"
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.

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.

compositionJSON
{  "id": {    "$ref": "common#id"  },  "sceneRef": {    "$ref": "common#id"  }}

illustration

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, sceneRef, and technique.

You may omit style, palette, stroke, textureAssetRefs, 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
idrequiredid

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

sceneRefrequiredid

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

techniquerequiredtaxonomy

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

stylestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
palettearray<color>

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

Exact constraints
type
array
itemscolor

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

strokestroke

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

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

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.

illustrationJSON
{  "id": {    "$ref": "common#id"  },  "sceneRef": {    "$ref": "common#id"  },  "technique": {    "$ref": "common#taxonomy"  }}

caption

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, start, end, and text.

You may omit speaker, language, position, and nodeRef. 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.

startrequiredtime

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

endrequiredtime

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

textrequiredstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
speakerstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
languagestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
position"top" | "bottom" | "center"

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
  • "top"
  • "bottom"
  • "center"
nodeRefid

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.

captionJSON
{  "id": {    "$ref": "common#id"  },  "start": {    "$ref": "common#time"  },  "end": {    "$ref": "common#time"  },  "text": "example"}

shot

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, sceneRef, start, and duration.

You may omit cameraRef, intent, and transition. 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.

sceneRefrequiredid

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.

startrequiredtime

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

durationrequiredduration

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

intentstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
transitiontransition

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

Smallest example

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

shotJSON
{  "id": {    "$ref": "common#id"  },  "sceneRef": {    "$ref": "common#id"  },  "start": {    "$ref": "common#time"  },  "duration": {    "$ref": "common#duration"  }}

video

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, timelineRef, and shots.

You may omit captions, subtitleAssetRef, audioAssetRefs, effectRefs, aspectRatio, 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.

timelineRefrequiredid

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

shotsrequiredarray<shot>

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
itemsshot

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

captionsarray<caption>

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

Exact constraints
type
array
itemscaption

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

subtitleAssetRefid

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

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

aspectRationumber

Write a number. Decimals are allowed.

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

videoJSON
{  "id": {    "$ref": "common#id"  },  "timelineRef": {    "$ref": "common#id"  },  "shots": [    {      "$ref": "media#shot"    }  ]}

chart

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

You may omit title, description, labels, xLabel, yLabel, legend, and showValues. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
typerequired"bar" | "line" | "area" | "pie" | "donut" | "scatter" | "table"

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
  • "bar"
  • "line"
  • "area"
  • "pie"
  • "donut"
  • "scatter"
  • "table"
titlestring

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

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

Exact constraints
type
array
itemsstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
seriesrequiredarray<object>

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
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 name and values.

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

Exact constraints
type
object
additional properties
forbidden
namerequiredstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
valuesrequiredarray<number | null>

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

Exact constraints
type
array
itemsnumber | null

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

Write a number. Decimals are allowed.

Exact constraints
type
number
anyOf 2null
Exact constraints
type
null
colorcolor

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

xLabelstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
yLabelstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
legendboolean

Write true or false.

Exact constraints
type
boolean
showValuesboolean

Write true or false.

Exact constraints
type
boolean

Smallest example

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

chartJSON
{  "type": "bar",  "series": [    {      "name": "example",      "values": []    }  ]}