visualspec.1.0 RC
GitHub
Module

Materials

What a surface is made of

Materials describe surface intent: base color, roughness, metalness, and the textures bound to those roles. The goal is a shared idea of the surface, not a dump of one engine’s shader graph.

Use this module when A 3D or product surface has to look like a specific material in more than one tool.

Keep in mind. A texture is a binding to an asset plus a role. The image file itself is an asset.

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

texture

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

You may omit channel, coordinateSet, scale, offset, rotation, wrap, filter, and strength. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
assetRefrequiredid

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

channel"r" | "g" | "b" | "a" | "rgb" | "rgba"

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
  • "r"
  • "g"
  • "b"
  • "a"
  • "rgb"
  • "rgba"
coordinateSetinteger

Write a whole number.

The number must be at least 0.

Exact constraints
type
integer
minimum
0
scalevector2

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

offsetvector2

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

rotationnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
wrap"repeat" | "clamp" | "mirror"

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
  • "repeat"
  • "clamp"
  • "mirror"
filter"nearest" | "linear" | "anisotropic"

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
  • "nearest"
  • "linear"
  • "anisotropic"
strengthnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0

Smallest example

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

textureJSON
{  "assetRef": {    "$ref": "common#id"  }}

material

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

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

namestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
modelrequired"pbr-metallic-roughness" | "pbr-specular-glossiness" | "unlit" | "toon" | "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
  • "pbr-metallic-roughness"
  • "pbr-specular-glossiness"
  • "unlit"
  • "toon"
  • "custom"
baseColorcolor

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

metalnessnumber

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
roughnessnumber

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
normaltexture

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

emissivecolor

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

emissiveIntensitynumber

Write a number. Decimals are allowed.

The number must be at least 0.

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

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
iornumber

Write a number. Decimals are allowed.

The number must be at least 1.

Exact constraints
type
number
minimum
1
clearCoatnumber

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
clearCoatRoughnessnumber

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
doubleSidedboolean

Write true or false.

Exact constraints
type
boolean
alphaMode"opaque" | "mask" | "blend"

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
  • "opaque"
  • "mask"
  • "blend"
alphaCutoffnumber

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
texturesobject
Exact constraints
type
object
additional properties
texture
additionalPropertiestexture

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

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.

materialJSON
{  "id": {    "$ref": "common#id"  },  "model": "pbr-metallic-roughness"}