visualspec.1.0 RC
GitHub
Module

Document

Pages you read

Document describes pages, sections, figures, notes, and pagination. Reading order and page structure matter more than a single viewport. A page is a sheet with a job, not a long screenshot.

Use this module when The artifact is a PDF, a report, a spec, or any paginated reading experience.

Keep in mind. Reading order is explicit. Visual position on the page is not a substitute for it.

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

section

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 title, nodeRefs, columns, columnGap, breakBefore, and keepTogether. 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.

titlestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
nodeRefsarray<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.

columnsinteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
columnGapdimension

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

breakBefore"auto" | "page" | "column" | "odd" | "even"

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
  • "auto"
  • "page"
  • "column"
  • "odd"
  • "even"
keepTogetherboolean

Write true or false.

Exact constraints
type
boolean

Smallest example

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

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

note

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

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

anchorRefid

This is not a new shape. It reuses id 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
kindrequired"footnote" | "endnote" | "caption"

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
  • "footnote"
  • "endnote"
  • "caption"
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.

noteJSON
{  "id": {    "$ref": "common#id"  },  "text": "example",  "kind": "footnote"}

page

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.

You may omit size, margin, bleed, headerRef, footerRef, sections, notes, number, 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.

sizeobject

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 width and height.

Exact constraints
type
object
additional properties
forbidden
widthrequiredsize

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

heightrequiredsize

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

margininsets

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

bleedsize

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

headerRefid

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

footerRefid

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

sectionsarray<section>

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

Exact constraints
type
array
itemssection

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

notesarray<note>

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

Exact constraints
type
array
itemsnote

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

numberinteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
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.

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

document

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

You may omit title, pagination, binding, widows, orphans, 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.

titlestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
pagesrequiredarray<page>

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
itemspage

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

paginationobject

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 start, format, position, and showFirst. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
startinteger

Write a whole number.

The number must be at least 0.

Exact constraints
type
integer
minimum
0
format"decimal" | "lower-roman" | "upper-roman" | "lower-alpha" | "upper-alpha"

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
  • "decimal"
  • "lower-roman"
  • "upper-roman"
  • "lower-alpha"
  • "upper-alpha"
position"header" | "footer" | "margin"

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
  • "header"
  • "footer"
  • "margin"
showFirstboolean

Write true or false.

Exact constraints
type
boolean
binding"left" | "right" | "top" | "none"

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
  • "left"
  • "right"
  • "top"
  • "none"
widowsinteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
orphansinteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
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.

documentJSON
{  "id": {    "$ref": "common#id"  },  "pages": [    {      "$ref": "document#page"    }  ]}