JSON Schema 1.0

Reference

Start with the module that matches your question, not with a keyword from JSON Schema. Each module page explains what the definitions are for, what you must write, and a minimal example. Open “Exact constraints” only when you need the validator’s view: types, patterns, and numeric bounds. Normative requirements still live in the specification. specification.

Root document

Raw schema: /schema/1.0/schema.json

Framework-independent contract for visual intent: what exists, what it means, how it appears, how it behaves, how it changes, and which evidence defines the expected result.

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

Every alternative below applies at the same time. The value has to satisfy all of them.

You must include visualSpec, metadata, and profiles.

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

Exact constraints

type: object
additional properties: forbidden

$schemaconst "https://visualspec.dev/schema/1.0/schema.json"

The only allowed value is "https://visualspec.dev/schema/1.0/schema.json".

Exact constraints

const: "https://visualspec.dev/schema/1.0/schema.json"

visualSpecrequiredconst "1.0"

The only allowed value is "1.0".

Exact constraints

const: "1.0"

metadatarequiredmetadata

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

One or more combinable visual profiles.

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

The list needs at least 1 item.

Each item in the list must be different. Duplicates are invalid.

Exact constraints

type: array
min items: 1
unique items: true

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

"ui"
"image"
"illustration"
"document"
"presentation"
"video"
"motion-graphics"
"3d"
"game"

sourcesarray<source>

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

Exact constraints

type: array

itemssource

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

visualReferencesarray<reference>

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

Exact constraints

type: array

itemsreference

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

visualReferenceSetsarray<referenceSet>

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

Exact constraints

type: array

itemsreferenceSet

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

visualLanguagevisualLanguage

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

tokenstokenRegistry

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

worldworld

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

entitiesarray<entity>

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

Exact constraints

type: array

itemsentity

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

relationshipsarray<relationship>

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

Exact constraints

type: array

itemsrelationship

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

scenesarray<scene>

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

Exact constraints

type: array

itemsscene

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

componentsarray<component>

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

Exact constraints

type: array

itemscomponent

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

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

eventsarray<event>

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

Exact constraints

type: array

itemsevent

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

actionsarray<action>

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

Exact constraints

type: array

itemsaction

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

statesarray<state>

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

Exact constraints

type: array

itemsstate

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

motionarray<animation>

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

Exact constraints

type: array

itemsanimation

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

timelinesarray<timeline>

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

Exact constraints

type: array

itemstimeline

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

assetsarray<asset>

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

Exact constraints

type: array

itemsasset

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

camerasarray<camera>

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

Exact constraints

type: array

itemscamera

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

lightsarray<light>

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

Exact constraints

type: array

itemslight

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

materialsarray<material>

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

Exact constraints

type: array

itemsmaterial

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

effectsarray<effect>

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

Exact constraints

type: array

itemseffect

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

compositionsarray<composition>

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

Exact constraints

type: array

itemscomposition

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

illustrationsarray<illustration>

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

Exact constraints

type: array

itemsillustration

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

videosarray<video>

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

Exact constraints

type: array

itemsvideo

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

presentationsarray<presentation>

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

Exact constraints

type: array

itemspresentation

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

documentsarray<document>

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

Exact constraints

type: array

itemsdocument

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

threeDthreeD

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

gamegame

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

renderingrendering

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

platformOverridesarray<override>

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

Exact constraints

type: array

itemsoverride

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

validationvalidation

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

flowsarray<flow>

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

Exact constraints

type: array

itemsflow

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

provenancearray<assertion>

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

Exact constraints

type: array

itemsassertion

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

platformsarray<"web" | "apple" | "android" | "fluent" | "custom">

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"web" | "apple" | "android" | "fluent" | "custom"

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

"web"
"apple"
"android"
"fluent"
"custom"

extensionsextensions

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

allOf 1-

ifobject

Write an object. The fields below are the ones this definition names.

You must include profiles.

profilesrequired-

thenobject

Write an object. The fields below are the ones this definition names.

You must include scenes.

scenesrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

allOf 2-

ifobject

Write an object. The fields below are the ones this definition names.

You must include profiles.

profilesrequired-

thenobject

Write an object. The fields below are the ones this definition names.

You must include entities, scenes, and cameras.

entitiesrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

scenesrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

camerasrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

allOf 3-

ifobject

Write an object. The fields below are the ones this definition names.

You must include profiles.

profilesrequired-

thenobject

Write an object. The fields below are the ones this definition names.

You must include illustrations and entities.

illustrationsrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

entitiesrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

allOf 4-

ifobject

Write an object. The fields below are the ones this definition names.

You must include profiles.

profilesrequired-

thenobject

Write an object. The fields below are the ones this definition names.

You must include documents.

documentsrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

allOf 5-

ifobject

Write an object. The fields below are the ones this definition names.

You must include profiles.

profilesrequired-

thenobject

Write an object. The fields below are the ones this definition names.

You must include presentations.

presentationsrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

allOf 6-

ifobject

Write an object. The fields below are the ones this definition names.

You must include profiles.

profilesrequired-

thenobject

Write an object. The fields below are the ones this definition names.

You must include videos and timelines.

videosrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

timelinesrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

allOf 7-

ifobject

Write an object. The fields below are the ones this definition names.

You must include profiles.

profilesrequired-

thenobject

Write an object. The fields below are the ones this definition names.

You must include motion and scenes.

motionrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

scenesrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

allOf 8-

ifobject

Write an object. The fields below are the ones this definition names.

You must include profiles.

profilesrequired-

thenobject

Write an object. The fields below are the ones this definition names.

You must include threeD, scenes, and entities.

scenesrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

entitiesrequired-

The list needs at least 1 item.

Exact constraints

min items: 1

allOf 9-

ifobject

Write an object. The fields below are the ones this definition names.

You must include profiles.

profilesrequired-

thenobject

You must include game.

Common

Shared constrained identifiers, values, units, bounds, provenance and extension payloads.

21 defs

References

Addressable source resources, visual evidence, reference graph and conflict resolution.

6 defs

Appearance

Color spaces, paint, typography, filters, surface and rendering appearance.

8 defs

Tokens

Typed design tokens, aliases, modes and provenance. Alias cycles require semantic validation.

3 defs

Layout

Framework-independent layout, constraints, responsive rules and adaptive alternatives.

5 defs

Geometry

2D and 3D primitives, paths, transforms and coordinate conventions.

3 defs

Accessibility

Cross-platform semantic accessibility contract, with explicit native-first ARIA mappings.

4 defs

Components

Component definitions and instances, anatomy, variants, behavior and existing design-system mappings.

5 defs

Semantics

A semantic tree independently describes meaning, roles and reading relationships.

1 defs

Interaction

Observable events, declarative visual actions and visual state graphs. No executable business logic.

4 defs

Motion

Temporal visual changes including keyframes, springs, paths, shared elements and driven progress.

10 defs

Timeline

Tracks, clips, markers, editorial transitions and audio-visual synchronization.

5 defs

Assets

Resources used in the output, distinct from references that specify expected appearance.

1 defs

Camera

Photographic and realtime cameras with shared optical and composition intent.

1 defs

Lighting

Physical and intent-oriented lights, environment illumination and shadows.

1 defs

Materials

Interoperable material intent, texture bindings and physically based surface parameters.

2 defs

Effects

Reusable visual effects, particle systems and post-processing intent.

1 defs

World

Visual world, environments, identities, representations, lifecycle and semantic relationships.

5 defs

Scene

Renderable scene tree and its semantic, entity and component bindings.

3 defs

Media

Image composition, illustration, audiovisual projects, captions and data visualization.

6 defs

Presentation

Slides, masters, narrative sequence, presenter notes and per-slide timelines.

3 defs

Document

Editorial and paginated visual layout, page sections, figures, notes and pagination.

4 defs

Three D

3D scene intent, geometry instances, LOD, skeletons, skins, rigs and morph targets.

5 defs

Game

Visual-only game profile: levels, HUD, characters, animation controllers, spatial UI and cutscenes.

4 defs

Rendering

Output requirements, capability negotiation, explicit fallbacks and platform overrides.

4 defs

Validation

Structural, semantic, accessibility, visual and reference conformance expectations.

3 defs