Conformità: validatore PDF/R-1, grammatica Arlington e strumenti per il ciclo di vita

In sintesi

NextPDF\Compliance fornisce validatori sui flussi di byte e un controllo incrociato di grammatica che leggono un PDF finito e segnalano dove diverge da un contratto normativo. Un validatore che restituisce zero risultati produce un esito verificato rispetto alle clausole che implementa, non un certificato globale.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

Il modulo è composto da tre parti.

PdfRValidator convalida un flusso di byte candidato ISO 23504-1:2020 (PDF/R-1). Opera sui byte non elaborati, non sullo stato interno del writer. Rileva lo scostamento tra ciò che il writer intende emettere e ciò che la specifica richiede. È il controllo finale. Il set di clausole implementato è il cluster v5.1.0: commento di identificazione della versione §5, allowlist dell’header §6.2.2/§6.2.3, divieto di generazione 0 e di object stream §6.2.4, allowlist degli operatori del content stream §6.5.7 (solo q, Q, cm, Do), allowlist delle chiavi dell’XObject immagine §6.6.1, allowlist delle chiavi del dizionario Info §6.4.3 e allowlist delle chiavi del Catalog §6.3. Gli aggiornamenti incrementali §6.7 e la cifratura §6.8 sono esplicitamente fuori ambito per il cluster iniziale e dichiarati come tali in claims.json. Il validatore non solleva un’eccezione al primo risultato. Raccoglie ogni divergenza in un’unica passata, così che il chiamante possa vedere il diff completo.

PdfRConformancePolicy è un criterio immutabile per le fasce consigliate ma informative attorno a PDF/R-1. La soglia minima normativa §6 non è mai configurabile. Il criterio controlla solo le raccomandazioni sui limiti di implementazione §A.5, la raccomandazione di evitare il multi-strip §6.6.1 e il requisito XMP §A.6 per la riclassificazione PDF/A a valle.

ArlingtonValidator esegue il modello Arlington PDF a monte della PDF Association in modalità solo report. Nel ciclo corrente è sempre consultivo: validateReportOnly() non solleva mai un’eccezione. Si degrada secondo tre modalità. Con il binario del checker di riferimento analizza risultati strutturati. Con la sola grammatica fissata emette un unico risultato info come prova del caricamento della grammatica fissata. Senza grammatica restituisce un elenco vuoto. Un WaiverRegistry consente all’orchestratore di sopprimere discrepanze note e accettabili preservando al tempo stesso l’audit trail.

La regola di onestà è la stessa della matrice di supporto CSS e del modulo di conformità. Una clausola è Verificata solo quando esiste un test superato e la clausola normativa è citata. Una clausola implementata ma priva di una fixture dedicata superata è Dichiarata. Le clausole fuori ambito sono indicate esplicitamente, non lasciate ambigue. Un esito di PdfRValidator con zero risultati asserisce soltanto le clausole che verifica effettivamente. Non avanza alcuna dichiarazione riguardo a §6.7 o §6.8, che non implementa.

Superficie dell’API

Tipo	Genere	Membri principali
NextPDF\Compliance\Validator\PdfRValidator	final class	validate(string $pdfBytes): list<PdfRValidationFinding>
NextPDF\Compliance\Validator\PdfRValidationFinding	final readonly class	string $clause, 'error'|'warning'|'info' $severity, string $message
NextPDF\Compliance\Profile\PdfRConformancePolicy	final readonly class	__construct(bool $enforceA5ImplementationLimits = true, bool $rejectMultiStripPages = false, bool $requireXmpForA6Compatibility = false); lax(), strictArchival()
NextPDF\Compliance\Validator\ArlingtonValidator	final class	validateReportOnly(string $pdfPath): list<ArlingtonFinding>
NextPDF\Compliance\Validator\WaiverRegistry	final class	isWaived(string $validator, string $ruleId, string $scopeKey): bool

Esempio di codice — Avvio rapido

<?php

declare(strict_types=1);

use NextPDF\Compliance\Validator\PdfRValidator;

$validator = new PdfRValidator();
$findings  = $validator->validate(file_get_contents('candidate.pdf'));

if ($findings === []) {
    // Zero divergences from the §6 clauses PdfRValidator implements.
    // This is NOT a PDF/R-1 certificate — §6.7 and §6.8 are not checked.
    echo "No PDF/R-1 §6 divergences detected (implemented clause set).\n";
} else {
    foreach ($findings as $f) {
        echo "[{$f->severity}] §{$f->clause}: {$f->message}\n";
    }
}

Esempio di codice — Produzione

<?php

declare(strict_types=1);

use NextPDF\Compliance\Validator\ArlingtonValidator;
use NextPDF\Compliance\Validator\ArlingtonGrammarLoader;
use NextPDF\Compliance\Validator\WaiverRegistry;

$validator = new ArlingtonValidator(
    waivers: new WaiverRegistry(/* loaded waiver entries */),
    grammar: new ArlingtonGrammarLoader(/* pinned submodule path */),
    adapter: null, // grammar-only mode when the reference checker is absent
);

// Advisory by contract — never throws on findings.
$findings = $validator->validateReportOnly('artifact.pdf');

foreach ($findings as $finding) {
    // Each finding pins the Arlington grammar commit SHA for provenance.
    logger()->info('arlington', [
        'rule'       => $finding->ruleId,
        'severity'   => $finding->severity,
        'grammarSha' => $finding->grammarSha,
    ]);
}

Casi limite e insidie

• PdfRValidator è basato su espressioni regolari, non è un parser completo. Prende come bersaglio l’output deterministico di NextPDF\Writer\PdfRWriter. Funziona come rilevatore di scostamenti per quel writer. Non è un parser PDF generico.
• Zero risultati ≠ piena conformità PDF/R-1. §6.7 (aggiornamenti incrementali) e §6.8 (cifratura) non sono implementati nel cluster v5.1.0 e sono dichiarati fuori ambito in claims.json. Considerare un esito pulito come «nessuna divergenza rispetto al set di clausole implementato», nulla di più.
• Arlington è consultivo. validateReportOnly() non fa mai fallire la build nel ciclo corrente. La CI consuma l’artefatto, ma non vi applica un gate.
• La validazione ICC PDF/A non è qui. La validazione ICC dell’OutputIntent §6.2.2 di ISO 19005-4:2020 risiede nel PdfAManager Enterprise (nextpdf/pro), non nel modulo Compliance di Core. La superficie PDF/A di Core è il solo discriminatore ConformanceMode.
• Le deroghe preservano l’audit trail. Una regola derogata viene soppressa dall’elenco dei risultati, ma la voce di deroga rimane come registrazione del perché.

Prestazioni

PdfRValidator::validate() esegue un’unica passata lineare con scansioni regex limitate sul flusso di byte. Il costo scala con le dimensioni del documento e rimane ampiamente entro il budget del modulo. ArlingtonValidator in modalità solo grammatica è O(numero-di-regole-della-grammatica) per il risultato che ne attesta il caricamento. Il percorso del checker di riferimento è un sottoprocesso ed è limitato dallo strumento a monte, non da NextPDF. È un passaggio CI fuori banda.

Note sulla sicurezza

Questi validatori leggono byte PDF non attendibili. PdfRValidator rimuove i valori letterali tra parentesi ed esadecimali prima dell’estrazione delle chiavi, così che una stringa Creator costruita ad arte non possa iniettare una falsa chiave /Name (gestione degli escape ISO 32000-1:2008 §7.3.4.2). L’adapter Arlington esegue il checker a monte come sottoprocesso limitato. Tratta un timeout o un errore di esecuzione come «nessun risultato» anziché fidarsi di un output parziale. Per la superficie di attacco del parsing PDF, consultare il modello di minaccia del progetto.

Conformità

Standard	Clausola	Cosa fa il modulo Compliance	Stato
ISO 23504-1:2020 (PDF/R-1)	§6.5.7	PdfRValidator applica la {q,Q,cm,Do} allowlist degli operatori del content stream	Verificato (test unitari, profilo standard e test di integrazione superati)
ISO 23504-1:2020 (PDF/R-1)	§6.4.3	PdfRValidator applica l’allowlist delle chiavi del dizionario Info	Verificato (supportato da test)
ISO 23504-1:2020 (PDF/R-1)	§6.7, §6.8	Non implementato nel cluster v5.1.0	Mancata copertura esplicita (dichiarata in claims.json)
ISO 32000-2:2020 (PDF 2.0)	§7.5.2	Scansione dell’allowlist delle chiavi del Catalog	Dichiarato (scansione regex; strutturale)
ISO 19005-4:2020 (PDF/A-4)	§6.7.3	Riconoscimento dello schema di identificazione tramite il modulo Conformance	Rimando incrociato (vedere /specifications/pdfa4/)

Il supporto non è conformità. Un’esecuzione di PdfRValidator che non restituisce alcun risultato dimostra che l’input non ha divergato dalle clausole §6 che il validatore implementa. Non asserisce che il file sia un file PDF/R-1 conforme: §6.7 e §6.8 non vengono verificati. Il controllo incrociato Arlington è consultivo e non asserisce mai la conformità. Per PDF/A-4 il validatore autorevole è veraPDF, eseguito fuori banda: vedere il modulo Conformance per l’oracolo veraPDF e il relativo gating opt-in.

Le citazioni sono parafrasate dal corpus di conformità di NextPDF. I digest completi di 64 caratteri di reference_id sono registrati nel front-matter della pagina e in _normative-evidence-conf.md.

Vedere anche

• Modulo Conformance — instradamento di ConformanceMode e oracolo veraPDF
• Modulo Audit — superficie di audit trail e attestazione
• Mappatura della specifica PDF/A-4 — copertura rispetto a mancata copertura di ISO 19005-4
• Modulo Security — modello di minaccia del parsing PDF