Connect 経由で ARIA ランドマークロールをタグ付き PDF にマッピングする

概要

HTML5 のセクショニング要素と ARIA ランドマークロールを含む HTML を、Connect トランスポート経由で送信します。タグ付きコンテンツのパイプラインがそれらを PDF 2.0 標準構造タイプにマッピングするため、支援技術は視覚的な位置ではなくランドマークを基準にナビゲートできます。ここで使うアクセシビリティチェックは Pro ティア です。このツールは class_exists() プローブによって検出され、nextpdf/premium がサーバーと併せてインストールされている場合にのみ登録されます。ドキュメントの作成と HTML の取り込みにはコアツールを使用します。

アクセシビリティツールは、PDF/UA-2（ISO 14289-2）に照らして検出結果を報告します。ツールによる合格判定は、そのツール自身の評価です。これはアクセシビリティチェックであり、独立した適合性認証ではありません。適合性の判定は、veraPDF などの別のチェッカーが行います。

インストール

composer require nextpdf/server

tools/list 呼び出しで、稼働中のデプロイに Pro アクセシビリティツールが存在することを確認します（/connect/tool-catalog/ を参照）。存在しない場合、このデプロイには nextpdf/premium がインストールされていないため、このレシピの検証ステップは実行できません。

概念の概要

グルーピング構造要素は、ドキュメントの論理構造をセクションや同種のコンテナーに整理します（ISO 32000-2 §14.8）。HTML パイプラインは、これらの要素を次のようにマッピングします。

<aside> と role="complementary" → PDF 2.0 の Aside 標準タイプ
<article> / role="article" → Art
<nav> / role="navigation" → Sect

非標準の構造タイプは、標準タイプにロールマッピングされている場合にのみ許容されます（PDF/UA-2 §8.2.5）。パイプラインは標準タイプを直接出力するため、手動のロールマップは必要ありません。支援技術がコンテンツに到達できるようにするには、コンテンツが構造ツリーに反映されている必要があります（PDF/UA-2 §8.2.4）。

API サーフェス

ツール名は、tools/list を通じて稼働中のレジストリと照合して検証されます。基準となるカタログは /connect/tool-catalog/ です。このレシピでは、コアのドキュメント作成ツールと HTML 取り込みツールに加えて、Pro アクセシビリティチェックを使用します。固定のツール数をここで改めて記載することはありません。

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

タグ付き PDF 2.0 ドキュメントを作成し、ランドマークロールを持つ HTML を追加して、その結果をチェックします（MCP tools/call、順番に実行）。

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_pdf",
    "arguments": { "page_size": "A4", "title": "ARIA Landmark Demo", "language": "en" }
  }
}

HTML を追加する前に、タグ付きコンテンツのエミッターを接続しておきます。言語を設定した状態でドキュメントを作成し、最初のコンテンツ呼び出しからエミッターが有効になるようにします。

コードサンプル — 本番

ランドマークを含む HTML を追加してアクセシビリティチェックを実行します。このとき、成功以外のステータスはトランスポートエラーではなく、確認すべき通常の結果として扱います。

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<main><h1>Annual Report</h1><aside><h2>Aside</h2><p>Note.</p></aside><div role=\"complementary\"><h2>Related</h2><p>Links.</p></div><nav role=\"navigation\"><p>Skip nav</p></nav></main>"
    }
  }
}

チェックのレスポンスは、観測された構造ツリーと PDF/UA-2 の検出結果のサマリーを報告します。<aside> と <div role="complementary"> は、いずれも同じ Aside 標準タイプに集約されます。

エッジケースと注意点

コンテンツより前にタグ付き出力が有効になっていない。 ドキュメントが言語/タグ付きモードで作成されていない場合、最初の HTML 追加でタグなしのコンテンツが生成され、チェックはタグ付きコンテンツの失敗を報告します。言語を設定したうえで、ドキュメントを作成し直します。
セクショニング要素上の競合するロール（<aside role="navigation">）は警告を生成します。競合するロールを削除するか、<div> を使用します。
ツールが存在しない。 nextpdf/premium がない場合、Pro アクセシビリティツールは登録されず、検証ステップは未知のツールエラーで失敗します。

パフォーマンス

フロントマターのバジェットは、ドキュメント上の上限値です。ランドマークのマッピングは、通常のレイアウトパスの一部です。一般的なドキュメントでは、別途測定可能なフェーズを追加することはありません。

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

一般的な Connect トランスポートのガイダンス以上に該当する事項はありません。外部に出力されるログレベルでは、ドキュメントの内容や HTML 本文をログに記録しないでください。

適合性

PDF/UA-2 マッピング

HTML	PDF 2.0 標準タイプ
`<aside>`, `role="complementary"`	`Aside`
`<article>`, `role="article"`	`Art`
`<nav>`, `role="navigation"`	`Sect`

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

主張	条項	reference_id
グルーピング要素が論理構造をセクションに整理	ISO 32000-2 §14.8
非標準タイプは標準タイプへのロールマッピングが必須	PDF/UA-2 §8.2.5
コンテンツは構造ツリーを通じて到達可能であることが必須	PDF/UA-2 §8.2.4

WCAG 2.2 マッピング

ランドマークナビゲーションは、コンテンツレベルで WCAG 2.2 SC 1.3.1（情報と関係性）および SC 2.4.1（ブロックスキップ）をサポートします。PDF フォーマットは構造を保持します。WCAG レベルのオーサリング上の判断については、引き続きコンテンツ作成者が責任を負います。

アクセシビリティツールによる合格判定は、アクセシビリティチェックであり、適合性認証ではありません。PDF/UA-2 の適合性は、独立したチェッカー（たとえば veraPDF）が判定します。

商用に関する背景

アクセシビリティチェックツールは Pro ティアであり、nextpdf/premium がサーバーと併せてインストールされている場合にのみ登録されます。

Connect 固有の事項

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

create_pdf、add_html、およびアクセシビリティチェックは、共有のツールエグゼキューターを介して、MCP tools/call、REST ツールエンドポイント、gRPC サービスのいずれでも同じように呼び出されます。

HITL リスクティア

ドキュメントの作成と HTML の取り込みは注意レベル（自動実行、監査ログ記録）です。アクセシビリティチェックは読み取り専用です。これらのツールは、いずれもデフォルトでは approval_required ではありません。/connect/hitl-risk-tiers/ を参照してください。

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

これらのツールは、オペレーターによる構成のオーバーライドでいずれかが approval_required に引き上げられない限り、ゲートをトリガーしません。ゲートが適用される場合、チャレンジエンベロープおよび単回使用トークンのコントラクトは、/connect/hitl-risk-tiers/ に記載されているものになります。

Connect 経由で ARIA ランドマークロールをタグ付き PDF にマッピングする

Connect 経由で ARIA ランドマークロールをタグ付き PDF にマッピングする

概要

インストール

概念の概要

API サーフェス

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

コードサンプル — 本番

エッジケースと注意点

パフォーマンス

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

適合性

PDF/UA-2 マッピング

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

WCAG 2.2 マッピング

商用に関する背景

Connect 固有の事項

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

HITL リスクティア

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

関連情報