テンプレートのJSONスキーマ

定義の構造

テンプレート定義は、用紙を決めるpageと、その上に描画する順序付きリストのelementsからなる、1つのオブジェクトです。

{
  "page": {
    "size": "A4",
    "orientation": "portrait",
    "margin": { "top": 48, "right": 48, "bottom": 48, "left": 48 }
  },
  "elements": [
    {
      "id": "invoice-title",
      "type": "heading",
      "placementMode": "flow",
      "content": { "text": "Invoice" },
      "layout": { "width": 100, "widthUnit": "percent", "height": 40 },
      "style": { "fontSize": 24, "textStyle": "bold" }
    }
  ]
}

用紙サイズ：A4 · A3 · Letter。向きはportraitまたはlandscapeで、余白は1インチあたり96のCSSピクセル単位です。

各要素で利用できるフィールド

すべての要素はid, type, placementModeを持ちます。ほかのフィールドは種類によって異なります。以下の表は、検証処理と同じルールセットから生成されるため、製品の仕様に遅れることはありません。

その種類の行に含まれないフィールドは、無視されるのではなく検証エラーになります。黙ってフィールドを破棄すると、リクエストが成功したように見えても、ドキュメントの内容が欠けてしまうためです。

placementMode

用紙上での要素の配置方法です。このモードにより、layout.xとlayout.yを参照するかどうかも決まります。

• flow — ページの下方向に順番に積み重ねます。xとyは無視され、要素はコンテンツに合わせて拡大します
• free — layout.xとlayout.yで指定した正確な位置に配置します
• band — ヘッダーやフッターなど、要素で指定したバンド内で各ページに繰り返します

dataset要素

datasetは表ではないコレクションを出力します。訪問記録、写真、署名などのリストを、列形式ではなく、テンプレートで指定したレイアウトで描画します。

{
  "id": "maintenance-visits",
  "type": "dataset",
  "placementMode": "flow",
  "binding": "visits",
  "layout": { "width": 100, "widthUnit": "percent", "height": 160 },
  "style": { "fontSize": 11 },
  "dataRules": { "required": true }
}

bindingは、表の場合と同じようにデータ内の配列を指定します。各項目の描画方法はlayoutとstyleで決まるため、同じコレクションを、あるテンプレートでは表、別のテンプレートではdatasetとして表示できます。

datasetにcontentフィールドはありません。データはbindingからのみ受け取ります。以前はcontentに記述しても出力に反映されなかったため、効果のない入力欄として残さず、このフィールドを削除しました。

生成前のデータ検証

検証エンドポイントは、利用枠を消費せずに、生成時と同じ「このデータはテンプレートの要件を満たしているか」を確認します。

curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/validate-data \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "referenceNo": "DOC-2026-0042", "currency": "USD" } }'

よくある問題

• 要素の種類に対応しないフィールドは、無視されず検証エラーになります。黙って破棄すると内容の欠けたドキュメントが生成され、欠けているものに誰も気づかないため、意図的にこの動作にしています。
• flow配置では、layout.xとlayout.yは一切参照されません。設定しても移動しないという質問は、スキーマに関する最も一般的な質問です。
• datasetにはcontentフィールドがなく、bindingからのみデータを受け取ります。contentに記述しても出力には反映されません。
• 余白とサイズの単位はミリメートルではなく、1インチあたり96のCSSピクセルです。20をミリメートルのつもりで指定すると、約3分の1の大きさになります。
• データが合うかを確認するために生成すると、ページ数を消費します。検証エンドポイントなら、同じ確認を無料で行えます。