Ngôn ngữ kịch bản o3oscript

o3oscript là ngôn ngữ KHAI BÁO viết bằng JSON: bạn mô tả tài liệu muốn có chứ không viết lệnh. Không có biến, vòng lặp, điều kiện hay lời gọi hàm, nên kịch bản không thể chạy vô hạn hay chạm vào máy chủ. Vòng lặp và điều kiện nằm trong mã của bạn, nơi sinh ra JSON. Một kịch bản dựng đúng MỘT tài liệu thuộc một trong ba loại rồi lưu ra một hoặc nhiều định dạng.

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

Cấu trúc chung#

Ba loại tài liệu#

Đơn vị đo#

• Mọi độ dài (lề, khoảng cách, bề rộng, chiều cao, toạ độ) tính bằng milimét.
• Cỡ chữ và độ dày viền tính bằng point (pt).
• Màu là chuỗi #RRGGBB, ví dụ #1D55B8.
• Giãn dòng tính theo phần trăm: 100 là dòng đơn, 150 là một dòng rưỡi.
• Bề rộng cột của bảng văn bản là số TƯƠNG ĐỐI: các cột chia bề rộng bảng theo tỷ lệ.

Thuộc tính tài liệu: 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"
  }
}

Tệp cần lưu: save#

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

Font#

Tên font dài 1 tới 64 ký tự. Image DocBuilder v1 có: Liberation Sans, Liberation Serif, Liberation Mono, Carlito, Caladea, DejaVu Sans, Noto Sans, Noto Serif. Font không có thì LibreOffice tự thay bằng font gần nhất. Liberation Serif, Liberation Sans và Carlito có cùng số đo chữ với Times New Roman, Arial và Calibri, nên tài liệu dùng các font đó thường giữ được bố cục.

Kịch bản mẫu#

Cả ba kịch bản đều hợp lệ theo lược đồ và dùng được ngay với POST /v1/build. Cách đếm đơn vị kịch bản nằm ở trang Dựng tài liệu.

Ràng buộc kiểm lúc chạy#

• Mọi hàng của một bảng văn bản phải có cùng số ô với header hoặc columns.
• Danh sách lồng tối đa 3 cấp.
• Tên trang tính không được trùng nhau.
• Ảnh base64 phải giải mã được và không quá 10 MB.
• Ảnh theo url chịu quy tắc chống SSRF như mọi URL khác mà DocBuilder tự tải.

Đọc lỗi kịch bản#

Lỗi kịch bản chỉ vị trí bằng JSON Pointer: /body/2/level là khoá level của phần tử thứ ba trong body (đánh số từ 0). script_invalid liệt kê mọi chỗ sai lược đồ trong detail.errors; script_error chỉ một chỗ trong detail.path; script_too_large báo detail.units và 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"
  }
}

Lược đồ JSON Schema#

Lược đồ chính thức là JSON Schema draft-07, $id https://office.o3o.vn/api/schema/o3oscript-v1.schema.json, có sẵn trong image DocBuilder ở /app/o3oscript-v1.schema.json. Cách kiểm kịch bản ở phía bạn bằng Python hoặc JavaScript: xem Dựng tài liệu.

Sắp có#

Tham chiếu theo loại tài liệu#