visualspec.1.0 RC
GitHub
Module

Lighting

How the scene is lit

Lighting records lights, environment illumination, and shadow intent. A light can be described physically or as an intention (“soft key from the left”) when the exact fixture is not the point.

Use this module when The light setup changes the meaning of the image and must survive a different renderer.

Keep in mind. Do not hide a required light inside a baked image if another profile still needs to relight the scene.

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

light

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

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

typerequired"directional" | "point" | "spot" | "area" | "environment" | "natural"

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
  • "directional"
  • "point"
  • "spot"
  • "area"
  • "environment"
  • "natural"
colorcolor

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

intensitynumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
intensityUnit"normalized" | "lux" | "lumens" | "candela" | "watts"

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
  • "normalized"
  • "lux"
  • "lumens"
  • "candela"
  • "watts"
temperaturenumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
positionvector3

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

directionvector3

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

targetRefid

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

softnessnumber

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
falloff"none" | "linear" | "inverse-square"

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
  • "none"
  • "linear"
  • "inverse-square"
rangenumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
coneAnglenumber

Write a number. Decimals are allowed.

The number must sit between 0 and 180, including both ends.

Exact constraints
type
number
minimum
0
maximum
180
sizevector2

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

shadowobject

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

Exact constraints
type
object
additional properties
forbidden
enabledboolean

Write true or false.

Exact constraints
type
boolean
biasnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
softnessnumber

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
resolutioninteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
assetRefid

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

role"key" | "fill" | "rim" | "background" | "ambient" | "practical"

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
  • "key"
  • "fill"
  • "rim"
  • "background"
  • "ambient"
  • "practical"
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.

lightJSON
{  "id": {    "$ref": "common#id"  },  "type": "directional"}