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/에 문서화된 내용을 따릅니다.

함께 보기

/cookbook/connect/figure-caption/ — 중첩된 Figure / Caption 구조.
/cookbook/connect/aria-noteref-pattern/ — 각주 참조 및 본문 역할.
/connect/tool-catalog/ — 등급별 도구 세트 계산.
/connect/hitl-risk-tiers/ — 위험 모델과 게이트.