viva_logo-135x40
viva_logo-135x40

VivaJSON Document Structure Documentation

Version 1.0 – 2025/06/26

Introduction

VivaJSON documents are JSON-based document descriptions that allow the key components of a document to be stored in a structured format. The VivaJSON format was developed for the exchange of structured document data and specifically describes pages, objects, styles, text, text chains, images, and layers. It is particularly suitable for technical and automated workflows, for example when documents are generated or processed by external programs, scripts, server services or AI systems. The format is therefore primarily aimed at developers.
Important: Unlike the open formats VivaXML or IDML, VivaJSON does not serve to fully represent a document, but concentrates on the document components that are essential for exchange and automated processing.

Root Structure

The JSON document must have a root object containing a single key, "document", which holds all document data.

{
  "document": { ... }
}

The "document" object contains the following fields:

  • version (string): The version of the document format (e.g., "1.0").
  • format (string): The document format identifier (e.g., "VivaDesigner-Document").
  • actions (object): A key-value map of actions, where keys are strings and values are arbitrary JSON values (optional).
  • settings (object): Document settings (see Settings).
  • resources (object): Brushes and stylesheets (see Resources).
  • layers (array): List of layer definitions (see Layers).
  • pages (array): List of page definitions (see Pages).
  • chains (array): List of text chains, where each chain is an array of object IDs (integer) representing connected text objects (optional).

Example

{
  "document": {
    "version": "1.0",
    "format": "VivaDesigner-Document",
    "actions": {
      "rgb2cmyk": "someAction"
    },
    "settings": { ... },
    "resources": { ... },
    "layers": [ ... ],
    "pages": [ ... ],
    "chains": [ [1, 2], [3, 4] ]
  }
}

Settings

The "settings" object defines document-wide properties:

  • pageMode (string): Page layout mode, either "singlePage" or "doublePage".
  • pageOrder (string): Page reading order, either "leftRight" or "rightLeft".
  • pageSize (object): Page dimensions:
    • width (number): Width in points.
    • height (number): Height in points.
  • margins (object): Page margins:
    • top (number): Top margin in points.
    • bottom (number): Bottom margin in points.
    • left (number): Left margin in points.
    • right (number): Right margin in points.
  • bleed (object): Bleed settings (same structure as margins).

Example

"settings": {
  "pageMode": "singlePage",
  "pageOrder": "leftRight",
  "pageSize": {
    "width": 595,
    "height": 842
  },
  "margins": {
    "top": 36,
    "bottom": 36,
    "left": 36,
    "right": 36
  },
  "bleed": {
    "top": 9,
    "bottom": 9,
    "left": 9,
    "right": 9
  }
}

Resources

The "resources" object contains:

  • brushes (object): A map of named brushes (see Brushes).
  • stylesheets (object): A map of named stylesheets (see Stylesheets).

Example

"resources": {
  "brushes": { ... },
  "stylesheets": { ... }
}

Brushes

Each brush is an object with:

  • type (string): Either "rgb" or "cmyk".
  • value (string): Color value, format depends on type:
    • For "rgb": A 6-character hexadecimal color code (e.g., "ff0000" for red).
    • For "cmyk": Space-separated percentages for cyan, magenta, yellow, and key (e.g., "0 0 0 100" for black).

Example

"brushes": {
  "red": {
    "type": "rgb",
    "value": "ff0000"
  },
  "black": {
    "type": "cmyk",
    "value": "0 0 0 100"
  }
}

Stylesheets

Each stylesheet is an object with:

  • type (string): Either "character", "paragraph", or "graphic".
  • Additional fields depend on the type (all optional unless specified).

Character Stylesheet

  • characterSpacing (number): Spacing between characters (in percentage).
  • characterBrush (string): Reference to a brush name.
  • font (string): Font family name.
  • fontSize (number): Font size in points.

Example

"charStyle": {
  "type": "character",
  "characterSpacing": 10,
  "characterBrush": "black",
  "font": "Arial",
  "fontSize": 12
}

Paragraph Stylesheet

  • characterStylesheet (string): Reference to a character stylesheet name.
  • lineSpacing (number): Line spacing in points.
  • leftIndent (number): Left indent in points.
  • rightIndent (number): Right indent in points.
  • spaceBefore (number): Space before paragraph in points.
  • spaceAfter (number): Space after paragraph in points.
  • writingJustification (string): Justification, one of "left", "right", "center", "justified", "forced-justified".
  • dropCaps (object): Drop cap settings:
    • type (string): Type, one of "none", "sequence", "word".
    • characterLength (integer): Number of characters for drop cap.
    • linesCount (integer): Number of lines for drop cap.
    • runaround (string): Text runaround, either "shape" or "box".

Example

"paraStyle": {
  "type": "paragraph",
  "characterStylesheet": "charStyle",
  "lineSpacing": 12,
  "leftIndent": 10,
  "rightIndent": 10,
  "spaceBefore": 6,
  "spaceAfter": 6,
  "writingJustification": "justified",
  "dropCaps": {
    "type": "sequence",
    "characterLength": 2,
    "linesCount": 3,
    "runaround": "shape"
  }
}

Graphic Stylesheet

  • borderWidth (number): Border width in points.
  • borderBrush (string): Reference to a brush name.
  • borderPattern (string): Border pattern name.
  • fillBrush (string): Reference to a brush name.
  • radius (number): Corner radius in points.
  • borderDensity (number): Border density (0 to 1).
  • borderOpacity (number): Border opacity (0 to 1).
  • startCap (integer): Start cap type (1 to 4).
  • endCap (integer): End cap type (1 to 4).

Example

"graphStyle": {
  "type": "graphic",
  "borderWidth": 1,
  "borderBrush": "black",
  "borderPattern": "solid",
  "fillBrush": "red",
  "radius": 5,
  "borderDensity": 1,
  "borderOpacity": 0.8,
  "startCap": 1,
  "endCap": 1
}

Layers

Each layer is an object with:

  • name (string): Layer name.
  • print (boolean): Whether the layer is printable (default: true).
  • locked (boolean): Whether the layer is locked (default: false).
  • hidden (boolean): Whether the layer is hidden (default: false).
  • color (string): Layer color as a 6-character hexadecimal code (e.g., "ff0000").

Example

"layers": [
  {
    "name": "Layer 1",
    "print": true,
    "locked": false,
    "hidden": false,
    "color": "ff0000"
  }
]

Pages

Each page is an object with:

  • startNumber (object, optional): Page numbering settings:
    • prefix (string): Prefix for page numbers.
    • number (integer): Starting page number.
    • format (string): Numbering format, one of "1, 2, 3", "A, B, C", "a, b, c", "I, II, III", "i, ii, iii".
  • objects (object): A map where keys are layer names and values are arrays of objects (see Objects).

Example

"pages": [
  {
    "startNumber": {
      "prefix": "Page ",
      "number": 1,
      "format": "1, 2, 3"
    },
    "objects": {
      "Layer 1": [ ... ]
    }
  }
]

Objects

Each object has common fields and type-specific fields. Common fields (all optional unless specified):

  • id (integer, required): Unique object identifier.
  • type (string, required): Object type, one of "text", "image", "group", "line".
  • geometry (string): Space-separated coordinates and size ("x y width height").
  • transform (string): Space-separated 2D transformation matrix values ("m11 m12 m21 m22 dx dy").
  • stylesheet (string): Reference to a graphic stylesheet name.
  • textOnPath (object): Text on path settings:
    • startOffset (number): Start offset along the path.
    • endOffset (number): End offset along the path.
    • alignment (string): Alignment, one of "ascender", "descender", "center", "baseline".
    • toPath (string): Path alignment, one of "top", "center", "bottom".
    • flipped (boolean): Whether text is flipped.
    • story (string): Text content (e.g., HTML-formatted string).

Text Object

  • columns (integer): Number of columns (default: 1).
  • columnGutter (number): Gutter between columns in points (default: 0).
  • story (string): Text content (e.g., HTML-formatted string).

Example

{
  "id": 1,
  "type": "text",
  "geometry": "100 100 200 300",
  "stylesheet": "graphStyle",
  "columns": 2,
  "columnGutter": 10,
  "story": "<p>Hello, World!</p>",
  "textOnPath": {
    "startOffset": 10,
    "alignment": "baseline",
    "story": "<p>Text on Path</p>"
  }
}

Image Object

  • source (object): Image source settings:
    • url (string): File path or URL to the image.
    • fit (string): Scaling mode, one of "proportional", "fitToFrame", "zoomToFrame".
    • align (string): Alignment, one of "topleft", "topright", "bottomright", "bottomleft", "center", "leftcenter", "topcenter", "rightcenter", "bottomcenter".
    • transform (string): Space-separated transformation matrix ("m11 m12 m21 m22 dx dy").

Example

{
  "id": 2,
  "type": "image",
  "geometry": "350 100 100 100",
  "stylesheet": "graphStyle",
  "source": {
    "url": "image.jpg",
    "fit": "proportional",
    "align": "center"
  }
}

Group Object

  • objects (array): List of sub-objects (recursive, any object type).

Example

{
  "id": 3,
  "type": "group",
  "transform": "1 0 0 1 50 50",
  "objects": [
    {
      "id": 4,
      "type": "text",
      "geometry": "0 0 100 50",
      "story": "<p>Subtext</p>"
    }
  ]
}

Line Object

  • points (object): Line endpoints:
    • start (string): Space-separated x, y coordinates ("x y").
    • end (string): Space-separated x, y coordinates ("x y").

Example

{
  "id": 5,
  "type": "line",
  "stylesheet": "graphStyle",
  "points": {
    "start": "100 100",
    "end": "200 200"
  }
}

Full Example

{
  "document": {
    "version": "1.0",
    "format": "vjson",
    "actions": {},
    "settings": {
      "pageMode": "singlePage",
      "pageOrder": "leftRight",
      "pageSize": { "width": 595, "height": 842 },
      "margins": { "top": 36, "bottom": 36, "left": 36, "right": 36 },
      "bleed": { "top": 9, "bottom": 9, "left": 9, "right": 9 }
    },
    "resources": {
      "brushes": {
        "red": { "type": "rgb", "value": "ff0000" },
        "black": { "type": "cmyk", "value": "0 0 0 100" }
      },
      "stylesheets": {
        "body": {
          "type": "paragraph",
          "lineSpacing": 12,
          "writingJustification": "justified",
          "characterStylesheet": "charStyle"
        },
        "charStyle": {
          "type": "character",
          "font": "Arial",
          "fontSize": 12,
          "characterBrush": "black"
        },
        "borderStyle": {
          "type": "graphic",
          "borderWidth": 1,
          "borderBrush": "black",
          "fillBrush": "[none]"
        }
      }
    },
    "layers": [
      {
        "name": "Layer 1",
        "print": true,
        "locked": false,
        "hidden": false,
        "color": "ff0000"
      }
    ],
    "pages": [
      {
        "startNumber": {
          "prefix": "",
          "number": 1,
          "format": "1, 2, 3"
        },
        "objects": {
          "Layer 1": [
            {
              "id": 1,
              "type": "text",
              "geometry": "100 100 200 300",
              "stylesheet": "borderStyle",
              "story": "<p>Hello, World!</p>",
              "columns": 2,
              "columnGutter": 10
            },
            {
              "id": 2,
              "type": "image",
              "geometry": "350 100 100 100",
              "stylesheet": "borderStyle",
              "source": {
                "url": "image.jpg",
                "fit": "proportional",
                "align": "center"
              }
            }
          ]
        }
      }
    ],
    "chains": []
  }
}

 

Newsletter

VIVA Newsletter