Conformidad: enrutamiento de ConformanceMode y límite de validación

De un vistazo

NextPDF\Conformance contiene el único discriminador que indica al escritor a qué contrato ISO apunta un documento. La biblioteca emite las estructuras definidas por ese contrato. No certifica, ni puede certificar, que el archivo resultante sea conforme. Solo un validador externo certifica la conformidad.

Instalación

composer require nextpdf/core:^3

Visión conceptual

El módulo Conformance expone dos tipos públicos. ConformanceMode es una enumeración respaldada que identifica el contrato de destino (Plain, PdfUa1, PdfUa2, PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). ConformancePolicy es un objeto de valor inmutable que combina un modo con conmutadores ortogonales de rigor.

El modo es la única fuente de verdad para las compuertas del escritor que se aplican más adelante. Antes de que existiera esta enumeración, el motor infería «¿este documento está etiquetado según la especificación?» a partir de banderas dispersas. ConformanceMode::isTagged(), isAccessibility(), isArchival(), pdfaPart(), pdfaConformanceLetter() y requiresPdf17() devuelven, cada una, una respuesta tipada que el escritor lee directamente. El catálogo, /MarkInfo, el linaje del encabezado del archivo y los marcadores XMP pdfaid se mantienen coherentes con la intención declarada.

El límite de soporte debe interpretarse con precisión. NextPDF Core emite estructuras definidas por estos estándares. ISO 19005-4:2020 §6.7.3 especifica el esquema de identificación que registra qué variante de PDF/A reclama un archivo. ISO 19005-4:2020 establece que la determinación efectiva de la conformidad se realiza según lo especificado en su Cláusula 5 — es decir, frente a los requisitos normativos, mediante una herramienta de comprobación, no por la biblioteca productora. ISO 14289-2:2024 §6 plantea la conformidad como una propiedad que satisface un archivo. Que NextPDF establezca un modo es una entrada necesaria para un archivo conforme. Por sí solo, no constituye un resultado de conformidad.

Esta es la misma disciplina de Verificado frente a Reclamado que aplica la matriz de soporte de CSS. Una capacidad es Verificada solo cuando existen una prueba aprobada o una ejecución aprobada del oráculo y una cláusula citada. Todo lo demás es una implementación que la biblioteca emite: útil, pero no una garantía de conformidad. La conformidad es una propiedad del archivo final más un validador, no una promesa de la biblioteca. Validar la salida con veraPDF (consultar «Conformidad» más abajo).

Hay un segundo límite relevante para el trabajo de archivado. La autoría de PDF/A-4 — el diccionario OutputIntent, el perfil ICC incrustado y el esquema de extensión XMP — está incluida en la extensión nextpdf/pro, no en Core. En una instalación que solo incluye Core, Document::enablePdfA() lanza InvalidConfigException porque la capacidad security.pdfa no está registrada. Core sigue siendo dueño del discriminador ConformanceMode (de modo que la introspección y la ruta etiquetada de PDF/UA-2 funcionen), pero no genera por sí solo un archivo PDF/A-4.

Superficie de la API

Tipo	Clase	Miembros clave
`NextPDF\Conformance\ConformanceMode`	`enum: string`	`Plain`, `PdfUa1`, `PdfUa2`, `PdfA2`, `PdfA3`, `PdfA3b`, `PdfA3u`, `PdfA4`, `PdfA4e`, `PdfA4f`; `isTagged()`, `isAccessibility()`, `isArchival()`, `requiresPdfUa2PageTabs()`, `pdfaPart(): ?int`, `pdfaConformanceLetter(): string`, `requiresPdf17(): bool`
`NextPDF\Conformance\ConformancePolicy`	`final readonly class`	`__construct(ConformanceMode $mode = PdfUa2, bool $strictUa2 = false, bool $rejectUnvalidatedLang = false, …)`; `lax()`, `strictUa2()`, `withUax9IsolateSupport()`, `withoutAstShadowMode()`, `withBlackPointCompensation()`, `withStrictOcspProducedAtTolerance()`, `withAllowStaleOcsp()`

ConformancePolicy impone una invariante en su constructor: los conmutadores estrictos de PDF/UA-2 solo se aplican cuando el modo es PdfUa2, y strictUa2 = true fuerza rejectUnvalidatedLang = true. Las combinaciones incoherentes lanzan InvalidConfigException en lugar de degradarse silenciosamente.

Ejemplo de código — Inicio rápido

<?php

declare(strict_types=1);

use NextPDF\Conformance\ConformanceMode;

$mode = ConformanceMode::PdfA4f;

// Introspect the declared contract — these drive writer-side gates.
$mode->pdfaPart();              // 4
$mode->pdfaConformanceLetter(); // 'F'
$mode->requiresPdf17();         // false (PDF/A-4 is PDF 2.0 lineage)
$mode->isArchival();            // true

Ejemplo de código — Producción

La ruta incluida en Core que ejercita un contrato de conformidad de principio a fin es la ruta etiquetada de PDF/UA-2. Este es el ejemplo ejecutable (examples/31-pdfua2-tagged.php). También es el objetivo del oráculo para el perfil estricto de PDF/UA-2.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$doc = Document::createStandalone();

// Set the tagged-PDF contract BEFORE writing content so the HTML pipeline
// wires the TaggedContentEmitter at parser-construction time.
$doc->enableTaggedPdf(lang: 'en');

$doc->setTitle('Accessible report');
// … write content …

$doc->save(__DIR__ . '/out/report-ua2.pdf');

// The library has now emitted PDF/UA-2 structures. It has NOT asserted
// conformance. Verify the file with the pinned veraPDF oracle:
//
//   php oracle/run.php pdfua.strict
//
// (Requires the veraPDF Docker image — opt-in; see "Conformance" below.)

Casos límite y trampas

La autoría de PDF/A-4 es Premium. Document::enablePdfA() lanza InvalidConfigException en una instalación que solo incluye Core (security.pdfa no disponible). Core es dueño del discriminador, no de la emisión de OutputIntent/ICC/XMP. Consultar /specifications/pdfa4/.
Casos paraguas frente a casos de variante. PdfA4 es el caso paraguas e informa una pdfaConformanceLetter() vacía. ISO 19005-4:2020 §6.7.3 indica que un archivo que no cumple ni con PDF/A-4e ni con PDF/A-4f no proporciona ningún pdfa:conformance. Usar PdfA4e / PdfA4f solo para las variantes del Anexo B / Anexo A.
El modo estricto de PDF/UA-2 es voluntario. ConformancePolicy::lax() es el valor predeterminado seguro para la compatibilidad con versiones anteriores. strictUa2() fuerza /MarkInfo /Marked true y el rechazo de etiquetas de idioma no validadas según BCP-47. Habilitarlo en un modo distinto de PdfUa2 lanza una excepción.
isTagged() tiene en cuenta la variante. Plain, PdfA2, PdfA3b y PdfA4e reportan que no están etiquetados. El escritor no debe asumir que un modo de archivado implica un árbol de estructura.
Un modo aprobado no es un archivo aprobado. Establecer PdfA4 no convierte la salida en un archivo PDF/A-4 válido. Ejecutar un validador.

Rendimiento

ConformanceMode y ConformancePolicy son tipos de valor puros: la resolución de los casos de la enumeración y el despacho de match son O(1), sin asignaciones más allá del objeto de política inmutable. No añaden ningún costo medible a la ruta de escritura. El escritor domina el presupuesto del módulo (wall_ms: 1500), no el discriminador. El oráculo veraPDF es un paso de CI fuera de banda; no forma parte de la generación del documento.

Notas de seguridad

Los conmutadores estrictos de ConformancePolicy controlan comportamientos de seguridad con fallo cerrado: securityPkiRfc5280Strict (validación de ruta de RFC 5280 §6), strictOcspProducedAtTolerance (ventana de desfase de RFC 6960 §4.2.2.1) y allowStaleOcsp (de manera predeterminada false: rechaza las respuestas OCSP que carecen de nextUpdate). Estos valores predeterminados son conservadores y pasarán a estricto en una versión mayor futura, conforme a la estrategia de compatibilidad con versiones anteriores documentada. Consultar el módulo de seguridad y el modelo de amenazas del proyecto para conocer los detalles de la ruta de firma.

Conformidad

NextPDF no certifica la conformidad. Emite estructuras definidas por los estándares que figuran a continuación, y un validador independiente decide si un archivo es conforme.

Estándar	Cláusula	Qué hace NextPDF Core	Estado
ISO 14289-2:2024 (PDF/UA-2)	§6	Emite el árbol de estructura, `/MarkInfo /Marked true` (estricto), `/Lang`, XMP `pdfuaid` a través de la ruta etiquetada de Core	Perfil verificado: `pdfua.strict` validado por el oráculo veraPDF (`php oracle/run.php pdfua.strict`) cuando el binario de veraPDF está presente (compuerta voluntaria)
ISO 19005-4:2020 (PDF/A-4)	§6.7.3	Emite el discriminador `pdfaid:part` / `pdfa:conformance` a través de `ConformanceMode`	Reclamado (emisión del discriminador, con pruebas unitarias); la autoría del archivo PDF/A-4 es exclusiva de Premium
ISO 32000-2:2020 (PDF 2.0)	§7.5.2	Estructura base de catalog/document	Reclamado (comportamiento del motor base)

El soporte no es conformidad. NextPDF Core emite estructuras de identificación de PDF/UA-2 y PDF/A-4 (implementación evidenciada por las pruebas en tests/Unit/Conformance/). La conformidad de un archivo con PDF/A-4 o PDF/UA-2 solo puede afirmarla un validador que ejecute el perfil correspondiente. Según la Cláusula 5 de ISO 19005-4:2020, la determinación de la conformidad es tarea del validador, no de la biblioteca productora.

La verificación con veraPDF explicita su requisito. El oráculo (oracle/run.php, oracle/lib/OracleRunner.php) delega en una imagen Docker de veraPDF con versión fijada. Cuando Docker o la imagen no están presentes, el ejecutor termina con el código 2 (fallo de infraestructura) y no realiza ninguna verificación. Por lo tanto, el perfil pdfua.strict es una compuerta de conformidad voluntaria: solo demuestra la conformidad en las máquinas donde el binario de veraPDF está presente. NextPDF no incluye ningún validador incrustado y no hace ninguna afirmación de conformidad en su ausencia.

Las citas se han parafraseado del corpus de cumplimiento de NextPDF. Los resúmenes de 64 caracteres del reference_id completo se registran en el front-matter de la página y en _normative-evidence-conf.md.

Consulta también

Módulo de cumplimiento — validador de PDF/R-1, gramática Arlington, herramientas de ciclo de vida
Módulo de accesibilidad — el emisor de contenido etiquetado de PDF/UA-2
Mapeo de la especificación PDF/A-4 — cobertura de funciones frente a la no cobertura explícita de ISO 19005-4
Mapeo de la especificación PDF/UA-2 — mapeo de accesibilidad de ISO 14289-2
Módulo de seguridad — conmutadores estrictos de la ruta de firma