Tutorial de PDF etiquetado con Connect

Tutorial de PDF etiquetado con Connect

Límite de conformidad (leer esto primero). NextPDF emite la estructura etiquetada, el texto alternativo y los metadatos que espera PDF/UA-2. Esto hace que la salida esté prevista para cumplir con PDF/UA-2 (ISO 14289-2). No convierte el documento en «conforme» por sí solo. Un verificador independiente —veraPDF en modo estricto PDF/UA-2— determina la conformidad. Por eso, toda afirmación de «PASS», «conforme» o «que cumple» que aparezca a continuación debe leerse como: «el documento está previsto para cumplir; veraPDF determina el resultado».

De un vistazo

Este tutorial crea un PDF etiquetado con los transportes de Connect. Activa el modo etiquetado, establece un título, añade HTML con estructura semántica y, a continuación, verifica el resultado con la herramienta de comprobación de estándares y veraPDF. Las herramientas de modo etiquetado y de contenido que se usan aquí forman parte del núcleo. La herramienta de comprobación de estándares pertenece al nivel Pro/Enterprise. Se registra mediante class_exists() solo cuando nextpdf/premium está instalado junto al servidor.

Instalación

composer require nextpdf/server

Descripción conceptual

La estructura lógica, junto con una especificación en lenguaje natural, hace que el contenido sea navegable en orden de lectura (ISO 32000-2 §14.7). Una descripción alternativa para el contenido no textual se conserva en la entrada /Alt (ISO 32000-2 §14.8). El contenido debe reflejarse en el árbol de estructura, y un verificador determina la conformidad (PDF/UA-2 §8.2.4). Cuando se redacta HTML semántico bien estructurado, el flujo genera la estructura correcta automáticamente. Este tutorial se apoya en ese comportamiento, en lugar de construir la estructura a mano.

Superficie de la API

Los nombres de las herramientas se verifican frente al registro en ejecución mediante tools/list. El catálogo de referencia es /connect/tool-catalog/. Este tutorial no repite el recuento de herramientas.

Ejemplo de código: inicio rápido

Esta es la ruta más breve. Activar el modo etiquetado con un idioma, establecer un título y, a continuación, añadir contenido.

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

Activar el modo etiquetado antes de la primera llamada de contenido. El escritor congela el modo cuando emite la primera página, por lo que activarlo más tarde no vuelve atrás para etiquetar el contenido que ya se ha emitido. El título del documento es obligatorio para PDF/UA-2, y el modo etiquetado establece la preferencia de título del visor.

Ejemplo de código: producción

Añadir HTML semántico. El flujo asigna los encabezados, las listas, las tablas (con <th scope>), los enlaces y las figuras (con alt) a los tipos de estructura correctos:

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

" } }}">

A continuación, ejecutar la comprobación de estándares frente a PDF/UA-2 y ejecutar veraPDF --flavour ua2 sobre la salida. El resultado de la comprobación y el veredicto de veraPDF son evaluaciones. Así se averigua si el documento está previsto para cumplir: veraPDF, no NextPDF, decide la conformidad.

Casos límite y trampas

• Modo etiquetado activado después del contenido. Todo el contenido que se añada antes de activar el modo queda sin etiquetar, y la comprobación informa de un fallo de contenido etiquetado. Activar el modo inmediatamente después de crear el documento.
• Imagen informativa sin alt. La comprobación informa de un fallo de texto alternativo de figura. Proporcionar texto alternativo o marcar una imagen decorativa como artefacto (/cookbook/connect/page-artifacts/).
• Nivel de encabezado omitido. Omitir un nivel (por ejemplo H1 y luego H3) es un fallo de orden de encabezados. Descender como máximo un nivel cada vez.
• <th> sin scope. Una celda de encabezado sin celdas de datos asociadas es un fallo de estructura de tabla. Asignar a cada <th> bien scope="col" o scope="row".
• Falta el título. Un documento sin título es un fallo de metadatos. Establecer el título después de activar el modo etiquetado.

Rendimiento

El presupuesto del front matter es un límite de documentación. El etiquetado forma parte de la pasada normal de diseño.

Notas de seguridad

Aquí no se aplica nada más allá de la orientación general sobre el transporte de Connect: no registrar el contenido del documento ni el cuerpo HTML en un nivel de registro que se distribuya externamente.

Conformidad

Asignación de PDF/UA-2

El HTML semántico se asigna a los tipos de estructura estándar de PDF/UA-2 (H1–H6, P, L/LI/Lbl/LBody, Table/TR/TH/TD, Link, Figure/Caption, Aside). La asignación es automática. La parte del contrato que le corresponde es redactar HTML semántico.

Referencia cruzada de etiqueta → ISO 32000-2 §14.9

Afirmación	Cláusula	reference_id
Estructura lógica + idioma → navegable en orden de lectura	ISO 32000-2 §14.7
Descripción alternativa conservada en /Alt	ISO 32000-2 §14.8
Contenido en el árbol de estructura; un verificador determina la conformidad	PDF/UA-2 §8.2.4

Asignación de WCAG 2.2

La estructura admite los SC 1.1.1, 1.3.1, 2.4.1 y 2.4.6 de WCAG 2.2 a nivel de contenido. El autor del contenido sigue siendo responsable de las decisiones de redacción a nivel de WCAG.

NextPDF produce una salida prevista para cumplir con PDF/UA-2. No declara la conformidad. veraPDF (u otro verificador) determina la conformidad. Una comprobación superada o una ejecución de veraPDF aporta evidencia de que la salida está prevista para cumplir, no una certificación por parte de NextPDF.

Contexto comercial

Las herramientas de modo etiquetado y de contenido forman parte del núcleo. La herramienta de comprobación de estándares pertenece al nivel Pro/Enterprise y se registra solo cuando nextpdf/premium está instalado junto al servidor.

Detalles de Connect

Disponibilidad de transporte (MCP / REST / gRPC)

Todas las herramientas de este tutorial se invocan de la misma manera mediante MCP tools/call, el endpoint de herramientas REST y el servicio gRPC. Todas se ejecutan mediante el ejecutor de herramientas compartido.

Nivel de riesgo HITL

Activar el modo etiquetado y usar las herramientas de contenido pertenecen al nivel de precaución. La comprobación de estándares es de solo lectura. La ruta de salida con escritura en archivo requiere aprobación, aunque el modo base64 no. Consulte /connect/hitl-risk-tiers/.

Envoltorio JSON de la barrera de confirmación

Cuando la ruta de salida con escritura en archivo está protegida, la barrera devuelve un envoltorio de desafío y un token de un solo uso. El token está vinculado al nombre de la herramienta, a un nonce y a un tiempo de vida (TTL) de 300 segundos. Para continuar, volver a invocar la herramienta con arguments._confirmation_token. Consulte /connect/hitl-risk-tiers/.

Véase también

• /cookbook/connect/conformance-mode/ — el discriminador de modo que respalda el modo etiquetado.
• /cookbook/connect/aria-tagged-pdf/ — asignación de roles de referencia.
• /cookbook/connect/page-artifacts/ — excluir el contenido decorativo del árbol de estructura.
• /connect/tool-catalog/ — cálculo del conjunto de herramientas por nivel.