적합성: ConformanceMode 라우팅과 검증의 경계

한눈에 보기

NextPDF\Conformance는 문서가 어떤 ISO 계약을 대상으로 하는지 작성기에 알려 주는 단일 판별자를 담고 있습니다. 라이브러리는 계약이 정의하는 구조를 방출합니다. 결과 파일이 적합하다고 인증하지 않으며, 인증할 수도 없습니다. 적합성을 확인해 단언할 수 있는 주체는 외부 검증기뿐입니다.

설치

composer require nextpdf/core:^3

개념 개요

Conformance 모듈에는 두 가지 공개 타입이 있습니다. ConformanceMode는 대상 계약의 이름을 지정하는 백드 열거형입니다(Plain, PdfUa1, PdfUa2, PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). ConformancePolicy는 모드를 서로 독립적인 엄격성 토글과 결합하는 불변 값 객체입니다.

모드는 다운스트림 작성기 게이트가 참조하는 유일한 기준입니다. 이 열거형이 도입되기 전에는 엔진이 “이 문서는 사양 태그가 지정되어 있는가?”를 여러 플래그에서 추론했습니다. ConformanceMode::isTagged(), isAccessibility(), isArchival(), pdfaPart(), pdfaConformanceLetter(), 그리고 requiresPdf17()는 각각 작성기가 직접 읽을 수 있는 타입 지정 응답을 반환합니다. 카탈로그, /MarkInfo, 파일 헤더 계보, XMP pdfaid 마커는 선언된 의도와 일관성을 유지합니다.

지원 범위의 경계를 정확히 이해해야 합니다. NextPDF Core는 이러한 표준이 정의하는 구조를 방출합니다. ISO 19005-4:2020 §6.7.3은 파일이 어떤 PDF/A 변형을 주장하는지 기록하는 식별 스키마를 규정합니다. ISO 19005-4:2020은 적합성의 실제 판정이 해당 표준의 5 절에 규정된 대로 수행된다고 명시합니다. 즉, 적합성 판정은 생성 라이브러리가 아니라 검사 도구가 규범적 요구 사항에 비추어 수행하는 일입니다. ISO 14289-2:2024 §6은 적합성을 파일이 충족하는 속성으로 규정합니다. NextPDF가 모드를 설정하는 것은 적합한 파일을 만들기 위한 필수 입력입니다. 그 자체만으로는 적합성 결과가 아닙니다.

이는 CSS 지원 매트릭스에 적용되는 검증됨과 주장됨의 구분 원칙과 같습니다. 기능은 통과하는 테스트 또는 오라클 실행과 인용된 조항이 존재할 때에만 검증됨 상태입니다. 그 밖의 모든 것은 라이브러리가 방출하는 구현입니다. 유용하지만 적합성 보장은 아닙니다. 적합성은 라이브러리의 약속이 아니라 최종 파일과 검증기의 속성입니다. 출력은 veraPDF로 검증해야 합니다(아래 “적합성” 참조).

보존용 작업에서는 두 번째 경계도 중요합니다. PDF/A-4 작성 — OutputIntent 딕셔너리, 임베디드 ICC 프로필, XMP 확장 스키마 — 은 Core가 아니라 nextpdf/pro 확장에서 제공됩니다. Core 전용 설치에서 Document::enablePdfA()는 InvalidConfigException을 발생시키는데, 이는 security.pdfa 기능이 등록되어 있지 않기 때문입니다. Core는 여전히 ConformanceMode 판별자를 소유하지만(따라서 인트로스펙션과 PDF/UA-2 태그 경로가 작동함), 자체적으로 PDF/A-4 파일을 작성하지는 않습니다.

API 표면

타입	종류	주요 멤버
`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는 생성자에서 불변 조건을 강제합니다. 엄격한 PDF/UA-2 토글은 모드가 PdfUa2일 때에만 적용되며, strictUa2 = true는 rejectUnvalidatedLang = true를 강제합니다. 일관성이 없는 조합은 조용히 완화되지 않고 InvalidConfigException을 발생시킵니다.

코드 샘플 — 빠른 시작

<?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

코드 샘플 — 프로덕션

Core에 포함되어 적합성 계약을 처음부터 끝까지 실행하는 경로는 PDF/UA-2 태그 경로입니다. 이 경로가 실행 가능한 예제입니다(examples/31-pdfua2-tagged.php). 또한 엄격한 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.)

엣지 케이스 및 주의 사항

PDF/A-4 작성은 Premium입니다. Core 전용 설치에서는 Document::enablePdfA()가 InvalidConfigException을 발생시킵니다(security.pdfa 사용 불가). Core는 OutputIntent/ICC/XMP 방출이 아니라 판별자를 소유합니다. /specifications/pdfa4/을 참조해야 합니다.
포괄 케이스와 변형 케이스. PdfA4는 포괄 케이스이며 빈 pdfaConformanceLetter()를 보고합니다. ISO 19005-4:2020 §6.7.3은 PDF/A-4e에도 PDF/A-4f에도 적합하지 않은 파일은 pdfa:conformance를 제공하지 않도록 지시합니다. PdfA4e / PdfA4f는 부속서 B / 부속서 A 변형에 대해서만 사용해야 합니다.
엄격한 PDF/UA-2는 옵트인입니다. ConformancePolicy::lax()가 하위 호환성에 안전한 기본값입니다. strictUa2()는 /MarkInfo /Marked true와 BCP-47 거부를 강제합니다. PdfUa2가 아닌 모드에서 활성화하면 예외가 발생합니다.
isTagged()는 변형을 인식합니다. Plain, PdfA2, PdfA3b, 그리고 PdfA4e는 태그가 지정되지 않은 것으로 보고합니다. 작성기는 보존용 모드가 구조 트리를 의미한다고 가정해서는 안 됩니다.
모드가 통과한다고 파일도 통과하는 것은 아닙니다. PdfA4를 설정해도 출력이 유효한 PDF/A-4 파일이 되지는 않습니다. 검증기를 실행해야 합니다.

성능

ConformanceMode와 ConformancePolicy는 순수 값 타입입니다. 열거형 케이스 해석과 match 디스패치는 불변 정책 객체를 제외하면 추가 할당이 없는 O(1) 연산입니다. 이들은 쓰기 경로에 측정 가능한 비용을 추가하지 않습니다. 모듈 예산(wall_ms: 1500)을 지배하는 것은 판별자가 아니라 작성기입니다. veraPDF 오라클은 문서 생성의 일부가 아니라 별도의 CI 단계입니다.

보안 참고 사항

여기서 ConformancePolicy의 엄격 토글은 페일 클로즈 보안 동작을 제어합니다. securityPkiRfc5280Strict(RFC 5280 §6 경로 검증), strictOcspProducedAtTolerance(RFC 6960 §4.2.2.1 시간 편차 윈도우), allowStaleOcsp(기본값 false — nextUpdate가 없는 OCSP 응답을 거부)가 그것입니다. 이러한 기본값은 보수적이며, 문서화된 하위 호환성 전략에 따라 향후 메이저 버전에서 엄격 모드로 전환됩니다. 서명 경로의 세부 사항은 보안 모듈과 프로젝트 위협 모델에서 다룹니다.

적합성

NextPDF는 적합성을 인증하지 않습니다. 아래 표준이 정의하는 구조를 방출하며, 파일이 적합한지는 별도의 검증기가 결정합니다.

표준	조항	NextPDF Core가 하는 일	상태
ISO 14289-2:2024 (PDF/UA-2) 표준	§6	Core 태그 경로를 통해 구조 트리, `/MarkInfo /Marked true`(엄격), `/Lang`, `pdfuaid` XMP를 방출	검증된 프로필: `pdfua.strict` — veraPDF 바이너리가 있을 때 veraPDF 오라클(`php oracle/run.php pdfua.strict`)이 검증함(옵트인 게이트)
ISO 19005-4:2020 (PDF/A-4) 표준	§6.7.3	식별자 `pdfaid:part` / `pdfa:conformance` 방출에 사용하는 타입은 `ConformanceMode`	주장됨(판별자 방출, 단위 테스트됨); PDF/A-4 파일 작성은 Premium 전용
ISO 32000-2:2020 (PDF 2.0) 표준	§7.5.2	기본 catalog/document 구조	주장됨(기본 엔진 동작)

지원은 적합성이 아닙니다. NextPDF Core는 PDF/UA-2 및 PDF/A-4 식별 구조를 방출합니다(구현이며, tests/Unit/Conformance/의 테스트로 입증됨). 파일이 PDF/A-4 또는 PDF/UA-2에 적합하다는 것은 일치하는 프로필을 실행하는 검증기만 단언할 수 있습니다. ISO 19005-4:2020 5 절에 따라, 적합성 판정은 생성 라이브러리가 아니라 검증기의 역할입니다.

veraPDF 게이팅은 그 요구 사항을 있는 그대로 반영합니다. 오라클(oracle/run.php, oracle/lib/OracleRunner.php)은 고정된 veraPDF Docker 이미지로 셸 아웃합니다. Docker 또는 이미지가 없으면 러너는 코드 2(인프라 실패)로 종료되며 아무것도 검증하지 않습니다. 따라서 pdfua.strict 프로필은 옵트인 적합성 게이트입니다. veraPDF 바이너리가 있는 시스템에서만 적합성을 증명합니다. NextPDF는 내장 검증기를 제공하지 않으며, 검증기가 없는 경우 어떠한 적합성 주장도 하지 않습니다.

인용문은 NextPDF 컴플라이언스 코퍼스에서 의역한 것입니다. 전체 64자 reference_id 다이제스트는 페이지 프런트매터와 _normative-evidence-conf.md에 기록되어 있습니다.

참고 항목

규정 준수 모듈 — PDF/R-1 검증기, Arlington 문법, 수명 주기 도구
접근성 모듈 — PDF/UA-2 태그 콘텐츠 방출기
PDF/A-4 사양 매핑 — ISO 19005-4 기능 지원 범위와 명시적 비지원
PDF/UA-2 사양 매핑 — ISO 14289-2 접근성 매핑
보안 모듈 — 서명 경로의 엄격 토글