Connect 経由のタグ付き PDF チュートリアル

Connect 経由のタグ付き PDF チュートリアル

適合の境界（まずお読みください）。 NextPDF は、PDF/UA-2 が要求するタグ付き構造、代替テキスト、メタデータを出力します。これにより、 出力は PDF/UA-2（ISO 14289-2）への準拠を意図したものになります。ただし、 それだけで文書が「適合」するわけではありません。適合の判定は、独立したチェッカー、つまり厳格な PDF/UA-2 モードの veraPDF が行います。したがって、 以下に出てくる「PASS」「適合」「準拠」という記述はすべて、「文書は準拠を意図したものであり、結果は veraPDF が判定する」と読み替えてください。

概要

このチュートリアルでは、Connect トランスポート経由でタグ付き PDF を作成します。タグ付きモードを有効化し、タイトルを設定し、セマンティックに構造化された HTML を追加したうえで、標準チェックツールと veraPDF で結果を検証します。ここで使用するタグ付きモードおよびコンテンツ系ツールはコアに含まれます。標準チェックの検証ツールは Pro/Enterprise ティアで提供されます。これは、サーバーと併せて nextpdf/premium がインストールされている場合にのみ、class_exists() によって登録されます。

インストール

composer require nextpdf/server

概念的な全体像

論理構造と自然言語の指定を組み合わせることで、コンテンツを読み順でたどれるようになります（ISO 32000-2 §14.7）。非テキストコンテンツの代替説明は /Alt エントリに保持されます（ISO 32000-2 §14.8）。コンテンツは構造ツリーに反映されている必要があり、適合の可否はチェッカーが判定します（PDF/UA-2 §8.2.4）。適切に構造化されたセマンティック HTML を作成すれば、パイプラインが正しい構造を自動生成します。このチュートリアルは、手作業で構築する構造ではなく、その自動生成に依拠します。

API サーフェス

ツール名は、tools/list を通じて稼働中のレジストリと照合して検証されます。正式なカタログは /connect/tool-catalog/ です。このチュートリアルでは、ツール数を改めて記載しません。

コードサンプル — クイックスタート

最短の手順は次のとおりです。言語を指定してタグ付きモードを有効化し、タイトルを設定してから、コンテンツを追加します。

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "enable_tagged_pdf",
    "arguments": { "document_id": "<id>", "language": "en" }
  }
}

最初のコンテンツ呼び出しの前に、タグ付きモードを有効化してください。ライターは最初のページを出力した時点でモードを固定するため、後から有効化しても、すでに出力済みのコンテンツに遡ってタグを付けることはできません。PDF/UA-2 では文書タイトルが必須であり、タグ付きモードではビューアタイトルの設定も有効になります。

コードサンプル — 本番運用

セマンティック HTML を追加します。パイプラインは、見出し、リスト、表（<th scope> 付き）、リンク、図（alt 付き）を正しい構造タイプにマッピングします。

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id>",
      "html": "<h1>Annual Report</h1><h2>Summary</h2><p>Revenue grew.</p><table><caption>Revenue</caption><thead><tr><th scope=\"col\">Region</th><th scope=\"col\">Q1</th></tr></thead><tbody><tr><th scope=\"row\">EMEA</th><td>120</td></tr></tbody></table><figure><img src=\"chart.png\" alt=\"Revenue by region bar chart\" /><figcaption>Figure 1.</figcaption></figure>"
    }
  }
}

RevenueRegionQ1EMEA120

Figure 1.

" } }}">

続いて、PDF/UA-2 に対して標準チェックを実行し、出力に対して veraPDF を --flavour ua2 で実行します。チェック結果と veraPDF の判定はいずれも評価結果です。文書が準拠を意図したものかどうかは、これらの結果から把握します。適合を判定するのは NextPDF ではなく veraPDF です。

エッジケースと注意点

• コンテンツ追加後にタグ付きモードを有効化した場合。 モードを有効化する前に追加したコンテンツはタグ付けされず、チェックはタグ付きコンテンツの失敗として報告します。文書を作成した直後にモードを有効化してください。
• alt のない情報画像。 チェックは図の代替テキストの失敗として報告します。代替テキストを指定するか、装飾画像をアーティファクトとしてマークしてください（/cookbook/connect/page-artifacts/）。
• 見出しレベルのスキップ。 レベルを飛ばすこと（たとえば H1 の次に H3）は、見出し順序の失敗となります。1 回につき最大 1 レベルずつ下げてください。
• scope のない <th>。 関連するデータセルを持たないヘッダーセルは、表構造の失敗となります。すべての <th> に scope="col" または scope="row" のいずれかを指定してください。
• タイトルの欠落。 タイトルのない文書は、メタデータの失敗となります。タグ付きモードを有効化した後にタイトルを設定してください。

パフォーマンス

フロントマターのバジェットはドキュメント上の上限です。タグ付けは通常のレイアウトパスの一部として実行されます。

セキュリティに関する注意

ここで適用される注意事項は、一般的な Connect トランスポートの指針に限られます。文書の内容や HTML 本文を、外部へ送信されるログレベルで記録しないでください。

適合

PDF/UA-2 へのマッピング

セマンティック HTML は、PDF/UA-2 標準の構造タイプ（H1–H6、P、L/LI/Lbl/LBody、Table/TR/TH/TD、Link、Figure/Caption、Aside）にマッピングされます。このマッピングは自動的に行われます。作成者が担う役割は、セマンティック HTML を作成することです。

タグ → ISO 32000-2 §14.9 相互参照

主張	箇条	reference_id
論理構造 + 言語 → 読み順でのナビゲーション可能	ISO 32000-2 §14.7
/Alt に保持される代替説明	ISO 32000-2 §14.8
構造ツリー内のコンテンツ。適合の可否はチェッカーが判定	PDF/UA-2 §8.2.4

WCAG 2.2 へのマッピング

この構造は、コンテンツレベルで WCAG 2.2 SC 1.1.1、1.3.1、2.4.1、2.4.6 をサポートします。コンテンツ作成者は、WCAG レベルの制作判断について引き続き責任を負います。

NextPDF は、PDF/UA-2 への準拠を意図した出力を生成します。適合を主張することはありません。適合の判定は veraPDF（または別のチェッカー）が行います。チェックの合格や veraPDF の実行結果は、出力が準拠を意図したものであることの証拠であり、NextPDF による認証ではありません。

商用コンテキスト

タグ付きモードおよびコンテンツ系ツールはコアに含まれます。標準チェックの検証ツールは Pro/Enterprise ティアで提供され、サーバーと併せて nextpdf/premium がインストールされている場合にのみ登録されます。

Connect 固有の事項

トランスポートの可用性（MCP / REST / gRPC）

このチュートリアル内のすべてのツールは、MCP の tools/call、REST のツールエンドポイント、gRPC サービスのいずれからでも同じ方法で呼び出せます。これらはすべて、共有のツールエグゼキューターを経由して実行されます。

HITL リスクティア

タグ付きモードの有効化とコンテンツ系ツールの使用は注意レベルです。標準チェックは読み取り専用です。ファイル書き込みの出力パスには承認が必要ですが、base64 モードは不要です。/connect/hitl-risk-tiers/ を参照してください。

確認ゲートの JSON エンベロープ

ファイル書き込みの出力パスがゲートされている場合、ゲートはチャレンジエンベロープと使い捨てトークンを返します。トークンは、ツール名、ナンス、300 秒の有効期限（TTL）に紐づけられます。処理を続行するには、arguments._confirmation_token を指定してツールを再度呼び出してください。/connect/hitl-risk-tiers/ を参照してください。

関連項目

• /cookbook/connect/conformance-mode/ — タグ付きモードの背景にあるモード判別子。
• /cookbook/connect/aria-tagged-pdf/ — ランドマークロールのマッピング。
• /cookbook/connect/page-artifacts/ — 装飾コンテンツを構造ツリーから除外。
• /connect/tool-catalog/ — ティアごとのツールセットの算出。