Skip to main content
Document Styling extends the existing defaults.styles object. It does not introduce a second preset type: typography, element styles, page styles, and reusable header/footer regions stay in one style bundle. Legacy documents remain valid and are not modified when opened or rendered.

​
Root contract

The current root fields are all-or-nothing. A partial object such as { "pages": [] } is rejected, which prevents ambiguous mixed versions.

​
Page entries and master variants

Each page entry is identified by the pair (id, variant). Dynamic object keys and recursive inheritance are deliberately avoided.
Supported variants: The deterministic cascade is:
  1. global default/default;
  2. global odd/even or blank;
  3. global section-first;
  4. global document-first;
  5. selected page ID default;
  6. selected ID odd/even or blank;
  7. selected ID section-first;
  8. selected ID document-first;
  9. local section overrides.
Arrays replace the inherited array. Objects merge recursively. null explicitly clears a nullable value. A missing property inherits.

​
Geometry

Page entries support:
  • A3, A4, A5, Letter, Legal, and custom width/height;
  • portrait and landscape;
  • fixed or mirrored margins with an optional gutter;
  • bleed;
  • one to twelve columns, gap, divider, and balancing;
  • top, center, or bottom content alignment;
  • solid, image, linear-gradient, or radial-gradient backgrounds.
Custom dimensions are only legal with format: "custom". For Office exports, page size, orientation, margins, columns, bleed, and vertical content alignment are section geometry. Therefore an odd/even/first variant may change the master content (headerRegionId, footerRegionId, background, and page objects), but it may not silently change section geometry. Use mirrored margins for binding-aware odd/even pages. Use a named page style assigned to a dedicated section for a cover, landscape appendix, or genuinely different first-page margins. HTML can apply variant geometry directly. Office export rejects PDF bleed boxes because DOCX/ODT cannot preserve them. This is reported as an unsupported capability instead of producing a misleading PDF.

​
Repeating page objects

objects places reusable design elements behind or in front of document content:
Available object types are shape, line, image, text, and field. A frame requires exactly two horizontal and two vertical constraints:
  • left + width, right + width, or left + right;
  • top + height, bottom + height, or top + bottom.
This supports rails, borders, corner marks, watermarks, full-page art, and fixed metadata without storing arbitrary CSS. Physical safety is explicit:
By default, an object extending beyond the physical page is an error. Foreground objects intersecting the content area are also errors. Set allowClip or allowOverlap only when cropping or overlay is intentional. Free text is wrapped inside its frame; insufficient height is rejected unless intentional clipping is enabled. A region uses a bounded grid. Cells can span tracks and contain multiple blocks, so a header can contain several images, multiple text lines, fields, rules, and a background without a recursive layout tree.
Region blocks: Regions and cells also support fills, padding, and per-edge borders. A traditional Word-style separator is a bottom border on the region or a horizontal rule block. For Office output, column tracks may mix mm, %, auto, and fr. Their fixed share must fit the available physical width. Row tracks are auto or fixed mm; relative row heights are rejected because Word cannot preserve them reliably. A fixed region height or maxHeight is checked against both the configured blocks and the resolved runtime text/variables before the file is written.

​
Section assignment

Both page and flow sections can select a page style:
pageStart accepts auto, next, odd, and even. Number formats are decimal, lowerRoman, upperRoman, lowerAlpha, and upperAlpha.

​
Validation layers

Autype validates a style in five layers:
  1. structural Zod/JSON Schema validation;
  2. semantic references, unique IDs, grids, constraints, gradients, and tokens;
  3. asset authorization and copy-on-apply traversal;
  4. renderer capabilities (native, rasterized, approximated, unsupported);
  5. deterministic layout geometry and header/footer collision checks.
Potential header/footer-to-content collisions are warnings. The following are hard errors:
  • a non-positive content area;
  • region content exceeding height or maxHeight;
  • fixed grid tracks that do not fit or cannot resolve to 100%;
  • a page object outside the physical page without allowClip;
  • a foreground object over the content area without allowOverlap;
  • free page text that cannot fit its frame.
Auto-height regions should define minHeight or maxHeight to make collision checking deterministic. New atomic style operations run these layout checks before committing. The renderer repeats capability and layout validation so a direct JSON request cannot bypass them. In compatible export mode, non-native decisions are returned as warnings. In strict mode, any unsupported decision rejects the target export.

​
Atomic style operations

Small edits do not require replacing the complete JSON:
Operations include upsertPage, removePage, upsertRegion, removeRegion, duplicatePage, duplicateRegion, addPageObject, updatePageObject, removePageObject, duplicatePageObject, movePageObject, moveRegionBlock, assignSection, setToken, removeToken, setElementStyle, and resetElementStyle. Passing null as assignSection.pageStyleId removes the explicit page-style assignment. The batch is atomic: structural, semantic, token-reference, capability, or physical-layout failure leaves the stored style unchanged. Document writes can provide expectedSnapshotId; preset writes can provide expectedVersion. Document writes are additionally committed in a serializable database transaction, so a concurrent snapshot created between validation and commit also returns HTTP 409. Clients that require a faithful target can request a strict renderer gate:
If the resulting style contains an unsupported DOCX capability, the complete write is rejected with UNSUPPORTED_STYLE_CAPABILITY. Images referenced by legacy header/footer fields or current pages, regions, fills, and blocks are copied as one unit. A failed copy or a later transaction conflict rolls those copies back before the request fails.

​
Legacy migration

The read path normalizes legacy page settings and three-slot headers/footers in memory. It does not mutate a document. An explicit upgrade is copy-on-write:
  1. preview the generated current bundle;
  2. optionally persist it;
  3. create a new immutable document snapshot;
  4. keep legacy fields for rollback and compatibility.
The mapping preserves page geometry, left/center/right content, rich text lines, header/footer images, and excludeFirstPage. Features that cannot be downgraded losslessly return explicit warnings.

​
Focused schemas for agents

Use the smallest applicable generated schema: These files are generated from the canonical Zod source. Do not edit generated JSON Schema files manually.