データスキーマ

テンプレートは版面だけのものではありません。読み取る変数を自分で宣言します — 名前、型、レコードごとに繰り返すかどうか、そして例の値。この宣言が、テンプレートを 設計した人と API を呼ぶシステムとのあいだのデータスキーマです。

スキーマを取得する

curl https://composepdf.com/v1/canvases/{canvasId}/schema \
  -H "x-api-key: $COMPOSEPDF_API_KEY"

返るのは POST /v1/canvases/{canvasId}/pdf のペイロードを記述した JSON Schema です。 そこから型を生成する、CI で検証する、それに合わせてフォームを組む、といった使い方ができます。

強制

同じスキーマが、レイアウトの前にサーバー側でも検査されます。スキーマを満たさないペイロードは レンダリングまで届かず、API は違反したパスを名指しした 400 を返します。

{
  "error": "data does not satisfy the template's declarations",
  "violations": ["customer.name", "items[2].price"]
}

dataList の場合、パスはレコードを名指しします: dataList[3].customer.name。

「来たものをそのまま描く」ではなくスキーマにする理由

間違ったペイロードで何かが描けてしまうことが、最悪の壊れ方です。誤りは顧客に渡る文書の 空欄として、何週間もあとに表に出ます。スキーマはその失敗を API の境界へ移します。そこなら 結合テストが見つけられます —— 本番の空っぽの請求書ではなく、今日の 400 として。

列挙型の変数もスキーマの一部です。宣言した集合の外にある値は違反になり、許される値はスキーマに 公開されるので、フォーム側はそれを選択肢として描けます。