The o3oscript language

o3oscript is a DECLARATIVE language written in JSON: you describe the document you want rather than write commands. There are no variables, loops, conditions or function calls, so a script cannot run forever or touch the server. Loops and conditions live in your code, which generates the JSON. One script builds exactly ONE document of one of three types and saves it in one or more formats.

{
  "o3oscript": 1,
  "type": "text",
  "meta": {
    "title": "Tên tài liệu"
  },
  "body": [
    {
      "type": "paragraph",
      "text": "Nội dung"
    }
  ],
  "save": [
    {
      "format": "docx"
    }
  ]
}

Overall structure#

Three document types#

Units#

• Every length (margins, spacing, widths, heights, coordinates) is in millimetres.
• Font sizes and border widths are in points (pt).
• Colours are #RRGGBB strings, e.g. #1D55B8.
• Line spacing is a percentage: 100 is single, 150 is one and a half.
• Text table column widths are RELATIVE numbers: columns share the table width in proportion.

Document properties: meta#

{
  "meta": {
    "title": "Hợp đồng cung cấp dịch vụ",
    "subject": "Hợp đồng số HD-2026-091",
    "author": "Phòng Pháp chế",
    "keywords": [
      "hợp đồng",
      "dịch vụ"
    ],
    "description": "Bản dựng tự động từ hệ thống quản lý hợp đồng.",
    "lang": "vi-VN"
  }
}

Files to save: save#

{
  "save": [
    {
      "format": "docx",
      "filename": "hop-dong.docx"
    },
    {
      "format": "pdf",
      "filename": "hop-dong.pdf",
      "pdfa": true
    }
  ]
}

Fonts#

Font names are 1 to 64 characters. The DocBuilder v1 image has: Liberation Sans, Liberation Serif, Liberation Mono, Carlito, Caladea, DejaVu Sans, Noto Sans, Noto Serif. Missing fonts are replaced by LibreOffice with the closest match. Liberation Serif, Liberation Sans and Carlito share the metrics of Times New Roman, Arial and Calibri, so documents using those fonts usually keep their layout.

Sample scripts#

All three scripts pass the schema and work as-is with POST /v1/build. Script unit counting is explained on Building documents.

Run-time checks#

• Every row of a text table must have as many cells as header or columns.
• Lists nest at most 3 levels deep.
• Sheet names must be unique.
• Base64 images must decode and be no larger than 10 MB.
• Images given by url follow the same SSRF rules as every other URL DocBuilder downloads.

Reading script errors#

Script errors point at the location with a JSON Pointer: /body/2/level is the level key of the third body element (counting from 0). script_invalid lists every schema failure in detail.errors; script_error gives one location in detail.path; script_too_large reports detail.units and detail.limit.

{
  "error": {
    "code": "script_invalid",
    "message": "Kịch bản không hợp lệ.",
    "detail": {
      "errors": [
        {
          "path": "/body/2/level",
          "message": "7 lớn hơn giá trị tối đa 6"
        }
      ]
    },
    "request_id": "req_0123456789abcdef"
  }
}

The JSON Schema#

The authoritative schema is JSON Schema draft-07, $id https://office.o3o.vn/api/schema/o3oscript-v1.schema.json, shipped in the DocBuilder image at /app/o3oscript-v1.schema.json. To validate scripts on your side in Python or JavaScript, see Building documents.

Coming later#

Reference by document type#