Tutorial de PDF marcado no Connect

Tutorial de PDF marcado no Connect

Limite de conformidade (leia isto primeiro). O NextPDF emite a estrutura marcada, o texto alternativo e os metadados esperados pelo PDF/UA-2. Com isso, a saída fica destinada a estar em conformidade com o PDF/UA-2 (ISO 14289-2). Isso não torna o documento “conformante” por si só. Um verificador independente, o veraPDF em modo estrito de PDF/UA-2, determina a conformidade. Leia cada declaração de “PASS”, “conformant” ou “compliant” abaixo como “o documento tem como objetivo estar em conformidade; o veraPDF determina o resultado”.

Visão geral

Neste tutorial, você cria um arquivo Portable Document Format (PDF) marcado usando os transportes do Connect. Você ativa o modo marcado, define um título, adiciona HTML semântico e verifica o resultado com a ferramenta de verificação de padrões e o veraPDF. As ferramentas de modo marcado e conteúdo usadas aqui são core. A ferramenta de verificação de padrões pertence ao nível Pro/Enterprise. Ela só é registrada por meio de class_exists() quando o nextpdf/premium está instalado junto com o servidor.

Instalação

composer require nextpdf/server

Visão conceitual

A estrutura lógica, combinada com uma especificação em linguagem natural, torna o conteúdo navegável na ordem de leitura (ISO 32000-2 §14.7). A entrada /Alt contém uma descrição alternativa para conteúdo que não é texto (ISO 32000-2 §14.8). O conteúdo precisa estar representado na árvore de estrutura, e um verificador determina a conformidade (PDF/UA-2 §8.2.4). Quando você escreve HTML semântico bem estruturado, o pipeline produz a estrutura correta para você. Este tutorial usa esse fluxo em vez de pedir que você construa a estrutura manualmente.

Superfície da API

Os nomes das ferramentas são verificados no registro em execução por meio de tools/list. O catálogo oficial é /connect/tool-catalog/. Este tutorial não repete a contagem de ferramentas.

Exemplo de código — Início rápido

Este é o caminho mais curto. Ative o modo marcado com um idioma, defina um título e então adicione conteúdo.

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

Ative o modo marcado antes da primeira chamada de conteúdo. O mecanismo de escrita fixa o modo quando emite a primeira página. Se você ativá-lo mais tarde, o NextPDF não marca retroativamente o conteúdo que já foi emitido. O título do documento é obrigatório para o PDF/UA-2, e o modo marcado define a preferência de título do visualizador.

Exemplo de código — Produção

Adicione HTML semântico. O pipeline mapeia títulos, listas, tabelas com <th scope>, links e figuras com alt para os tipos de estrutura corretos:

{
  "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.

" } }}">

Depois, execute a verificação de padrões em relação ao PDF/UA-2 e rode o veraPDF --flavour ua2 na saída. O resultado da verificação e o veredito do veraPDF são avaliações. Eles informam se o documento se destina a estar em conformidade. O veraPDF, e não o NextPDF, determina a conformidade.

Casos extremos e pegadinhas

• Modo marcado ativado depois do conteúdo. Qualquer conteúdo que você adicionar antes de ativar o modo fica sem marcação. A verificação relata uma falha de conteúdo marcado. Ative o modo imediatamente depois de criar o documento.
• Imagem informativa sem alt. A verificação relata uma falha de texto alternativo de figura. Forneça texto alternativo ou marque uma imagem decorativa como artefato (/cookbook/connect/page-artifacts/).
• Nível de título pulado. Pular um nível, por exemplo H1 e depois H3, é uma falha de ordem de títulos. Desça no máximo um nível de cada vez.
• <th> sem scope. Uma célula de cabeçalho sem células de dados associadas é uma falha de estrutura de tabela. Atribua a cada <th> ou scope="col" ou scope="row".
• Título ausente. Um documento sem título é uma falha de metadados. Defina o título depois de ativar o modo marcado.

Desempenho

O orçamento do front-matter é um limite de documentação. A marcação faz parte da etapa normal de layout.

Notas de segurança

Aqui, nada se aplica além da orientação geral de transporte do Connect: não registre em log o conteúdo do documento nem o corpo HTML em um nível de log enviado externamente.

Conformidade

Mapeamento para PDF/UA-2

O HTML semântico é mapeado para os tipos de estrutura padrão do PDF/UA-2 (H1–H6, P, L/LI/Lbl/LBody, Table/TR/TH/TD, Link, Figure/Caption, Aside). O mapeamento é automático. Sua parte no contrato é escrever HTML semântico.

Tag → referência cruzada da ISO 32000-2 §14.9

Afirmação	Cláusula	reference_id
Estrutura lógica + idioma → navegável na ordem de leitura	ISO 32000-2 §14.7
Descrição alternativa contida em /Alt	ISO 32000-2 §14.8
Conteúdo na árvore de estrutura; um verificador determina a conformidade	PDF/UA-2 §8.2.4

Mapeamento para WCAG 2.2

A estrutura dá suporte aos SC 1.1.1, 1.3.1, 2.4.1 e 2.4.6 da WCAG 2.2 no nível do conteúdo. Como autor do conteúdo, você continua responsável pelas decisões de autoria no nível da WCAG.

O NextPDF produz uma saída destinada a estar em conformidade com o PDF/UA-2. Ele não declara conformidade. O veraPDF, ou outro verificador, determina a conformidade. Uma verificação aprovada ou uma execução do veraPDF serve como evidência de que a saída se destina a estar em conformidade, não como certificação do NextPDF.

Contexto comercial

As ferramentas de modo marcado e conteúdo são core. A ferramenta de verificação de padrões pertence ao nível Pro/Enterprise e só é registrada quando o nextpdf/premium está instalado junto com o servidor.

Especificidades do Connect

Disponibilidade de transporte (MCP / REST / gRPC)

Você invoca cada ferramenta deste tutorial da mesma forma por MCP tools/call, pelo endpoint REST de ferramenta e pelo serviço gRPC. Todas elas passam pelo executor de ferramentas compartilhado.

Nível de risco HITL

Ativar o modo marcado e usar as ferramentas de conteúdo ficam no nível de cautela. A verificação de padrões é somente leitura. O caminho de saída de gravação de arquivo exige aprovação, embora o modo base64 não exija. Consulte /connect/hitl-risk-tiers/.

Envelope JSON do gate de confirmação

Quando o caminho de saída de gravação de arquivo passa por um gate, o gate retorna um envelope de desafio e um token de uso único. O token está vinculado ao nome da ferramenta, a um nonce e a um time-to-live (TTL) de 300 segundos. Para prosseguir, invoque a ferramenta novamente com arguments._confirmation_token. Consulte /connect/hitl-risk-tiers/.

Veja também

• /cookbook/connect/conformance-mode/ — o discriminador de modo usado por trás do modo marcado.
• /cookbook/connect/aria-tagged-pdf/ — mapeamento de funções de landmark.
• /cookbook/connect/page-artifacts/ — exclua conteúdo decorativo da árvore de estrutura.
• /connect/tool-catalog/ — cálculo do conjunto de ferramentas por nível.