Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .github/workflows/compliance.yml
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,7 @@ jobs:
set -euo pipefail
output="$RUNNER_TEMP/SharpCorePDF.Examples/output"

for profile in 1b 2b 2u 3b 3u; do
for profile in 1b 2b 2u 3b 3u 4; do
python3 docs/tools/validate-pdfa.py \
--format xml --report-dir artifacts/pdfa --require-version "$VERAPDF_VERSION" \
--profile "$profile" \
Expand All @@ -213,7 +213,8 @@ jobs:
done

# The same documents, read by two more implementations. --strict-tools makes a missing tool a failure
# rather than a note, because a green run here is supposed to mean that all three agreed.
# rather than a note, because a green run here is supposed to mean that all three agreed. PDFBox 3.0.8
# and Ghostscript have no PDF/A-4 mode, so veraPDF is the only reading of that profile.
- name: Cross-validate with a second and a third implementation
env:
VERAPDF_HOME: ${{ env.VERAPDF_INSTALL }}
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,11 @@ against an empty feed.
The report is read-only and never returns stream contents; a document that stays closed is reported
with `IsReadable`/`RequiresPassword` instead of throwing. `tools/SharpCorePDF.Diagnostics` prints it as
text or JSON, with `--profile` for the archival pre-flight and `--json` for the whole report.
- **PDF/A-4 (ISO 19005-4) is written.** `PdfAProfile.PdfA4` writes a PDF 2.0 document with `pdfaid:part`
4 and no conformance level — the base level — with the same embedded fonts and sRGB output intent as the
other profiles, and transparency allowed. `compliance.yml` now validates `archive-4.pdf` and
`archive-source-4.pdf` with veraPDF, and the `archive-pdfa` example writes both. PDF/A-4f/-4u and level A
remain out of scope.

### Changed

Expand Down
Binary file modified docs/SharpCorePDF-Manual-1.7.0.pdf
Binary file not shown.
18 changes: 11 additions & 7 deletions docs/manual/src/24-pdf-a.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@ if (!result.IsWritten)
`new PdfAWriterService(new PdfAWriter())` (Chapter 10). The source is opened, read to its end and disposed;
the destination belongs to the caller and is flushed, not closed.

`PdfAProfile` names five profiles — three at level B and two at level U:
`PdfAProfile` names six profiles — three at level B, two at level U, and PDF/A-4, whose base level has no
letter:

| Profile | Part of ISO 19005 | Level | PDF version written | Transparency | JPEG 2000 | Embedded files |
| --- | --- | --- | --- | --- | --- | --- |
Expand All @@ -52,13 +53,16 @@ the destination belongs to the caller and is flushed, not closed.
| `PdfA2U` | 19005-2 | U | 1.7 | allowed | allowed | refused |
| `PdfA3B` | 19005-3 | B | 1.7 | allowed | allowed | allowed |
| `PdfA3U` | 19005-3 | U | 1.7 | allowed | allowed | allowed |
| `PdfA4` | 19005-4 | (none) | 2.0 | allowed | allowed | refused |

Level B keeps the visual appearance. Level U adds one requirement: every glyph the document draws has a
Unicode equivalent, which is what a text extractor or a search index reads. The writer already states a
`ToUnicode` map for every font it subsets, so a document that converts to `PdfA2B` converts to `PdfA2U`
as well; the level is written as `pdfaid:conformance` in the packet, and nothing else about the file
changes. A profile at level A — tagged structure, accessibility — is not offered, and PDF/UA is a
different standard.
changes. PDF/A-4 is based on PDF 2.0 and is the base level of ISO 19005-4: it writes `pdfaid:part` 4 and
no `pdfaid:conformance` element, and it allows transparency while refusing embedded files. PDF/A-4f, -4u
and a profile at level A — tagged structure, accessibility — are not offered, and PDF/UA is a different
standard.

The profile decides the version of the file, whatever `PdfVersion` a caller might otherwise have asked
for; a PDF/A-1b document that claims 1.7 is not one.
Expand All @@ -69,9 +73,9 @@ byte-identical, which is what a test that compares files needs.

## What the writer writes

- **The header version** the profile names, 1.4 or 1.7.
- **An XMP packet** in the catalog, uncompressed and UTF-8, carrying `pdfaid:part` and
`pdfaid:conformance`, plus the document information mirrored into `dc:title`, `dc:creator`,
- **The header version** the profile names, 1.4, 1.7 or 2.0.
- **An XMP packet** in the catalog, uncompressed and UTF-8, carrying `pdfaid:part` and — for the level-B
and level-U profiles — `pdfaid:conformance`, plus the document information mirrored into `dc:title`, `dc:creator`,
`dc:description`, `pdf:Keywords`, `pdf:Producer`, `xmp:CreatorTool` and the two dates. A profile
requires the dictionary and the packet to agree, so the same values are written to both.
- **An output intent** in the catalog: `/S /GTS_PDFA1` and a destination profile. By default the profile is
Expand Down Expand Up @@ -117,7 +121,7 @@ changing what a page looks like, or that are data.
| A CID font subset without `/CIDSet`, for 1b | ISO 19005-1 requires the set, and the writer cannot know which CIDs a program it did not subset describes. |
| Transparency for 1b — a soft mask, a blend mode, a transparency group | PDF 1.4 has no transparency, and making it opaque changes the page. |
| `JPXDecode` or `LZWDecode` for 1b | The first part of ISO 19005 forbids both filters. |
| Embedded files for 1b and 2b | Only PDF/A-3 allows attachments. |
| Embedded files for 1b, 2b and 4 | Only PDF/A-3 allows attachments; PDF/A-4f would, and is not offered. |
| Optional content for 1b | PDF 1.4 has no layers. |
| An annotation without an appearance stream (except `Link` and `Popup`) | A viewer would have to invent the content. |
| A JavaScript, `Launch`, `Sound`, `Movie`, `Rendition`, `ImportData` or `SubmitForm` action | The profile forbids the action itself, not just its startup use. |
Expand Down
2 changes: 1 addition & 1 deletion docs/parity.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ No “Must” row is unowned. The owner is the story that closes it: `US1 creato
| 9 | Annotation creation, editing, removal and appearance streams | PDFsharp: broad annotation model. PdfPig: read-only annotations. | Must: link, text, free text, stamp, highlight, underline, strikeout, square, circle, line and ink; update/remove; appearance for every creatable kind. | 1.2 | US2 editing | `PdfAnnotationTests.Adds_a_highlight_and_reads_it_back_with_an_appearance`, `Adds_links_to_a_url_and_to_a_page`, `Updates_one_annotation_and_removes_another`, `Keeps_the_annotation_a_page_already_carried`, `Carries_an_annotation_into_a_duplicate_of_its_page`, `Writes_an_appearance_for_every_kind_that_draws_something`, `Draws_the_text_of_a_free_text_annotation_into_its_appearance`, `Drops_a_link_whose_destination_the_edit_removes`, `Clips_an_annotation_to_the_page_and_reports_it`, `Refuses_an_update_of_an_annotation_the_page_does_not_carry`, `Refuses_a_link_with_both_a_page_and_a_url`, `Refuses_a_translucent_annotation_for_pdfa_1b` (T043) | `python docs/tools/validate-pdf.py annotated.pdf` from the `annotate` example (pikepdf 10.17.0 / qpdf: `qpdf check: no problems`, PDF 1.7, 2 pages, 20 objects, page 1 `annots=6`, 6 streams decoded, 0 failed) and a PyMuPDF 2.0 render of the same file, which reports six annotations and paints the highlight quad (255, 223, 129) for `#FFE082`, the note icon (255, 211, 0), the free text in `#1F3A5F` and the stamp frame (191, 43, 31) | Met in 1.2 (2026-10-24): the ten kinds the row lists are written by `PdfAnnotations`, each with an appearance stream the engine draws unless the caller supplies one; `AddAnnotation`, `UpdateAnnotation` and `RemoveAnnotation` rebuild the page's `/Annots` without touching its content, a page the plan does not name keeps its objects, an annotation that states no identifier is named `scpdf-N`, and every refusal the contract states — unknown kind, link with both a page and a URL, missing identifier, empty geometry, opacity outside 0-1, translucency under PDF/A-1b — is made before a byte is written |
| 10 | Incremental updates that preserve existing signatures | PDFsharp: yes. PdfPig: no. | Must: append a revision, keep every prior byte, refuse a changed source, and keep the prior signature's byte range valid. | 1.2 | US2 editing | `PdfIncrementalWriterTests.Appends_a_revision_after_the_bytes_of_the_source`, `Chains_the_revision_to_the_cross_reference_section_of_the_source`, `Chains_a_second_revision_to_the_first`, `Keeps_a_signature_that_covers_the_earlier_revision`, `Refuses_an_incremental_update_of_an_encrypted_document` (T042, T050) | `uv run --with pikepdf python docs/tools/validate-pdf.py <output.pdf>` and a byte-for-byte prefix comparison | Met in 1.2 (2026-10-24): a 1220-byte source edited into a 2465-byte result whose first 1220 bytes are the source unchanged, with one `/Prev`, two `%%EOF` and two `startxref` in the file; `validate-pdf.py` on that result reports `qpdf check: no problems`, PDF 1.7, 2 pages, page 1 `rotate=90` and 4 streams decoded, so an independent reader resolves the appended revision; the signature of a signed source still validates with `CoveredRevision` 2 of the 3 revisions the edit leaves, and the same plan applied as a rewrite reports `PriorSignatureInvalidated` |
| 11 | Digital signatures: sign, validate, timestamp, report integrity and trust separately | PDFsharp: yes. PdfPig: no. | Must: detached CMS over a reserved byte range, X.509, optional caller-supplied RFC 3161 token, integrity and trust as separate results. | 1.1 | US4 trust | `PdfDocumentSignerTests.Writes_a_signature_that_verifies_against_its_own_bytes`, `Signing_a_second_time_keeps_the_first_signature_valid`, `Embeds_the_timestamp_token_the_caller_supplies` (T080, T087), `PdfDocumentSignatureValidatorTests.Reports_a_changed_byte_as_a_digest_mismatch`, `Keeps_integrity_independent_of_trust`, `Reports_a_request_for_an_online_check_without_making_one` (T081) | `python docs/tools/validate-signatures.py --trust-signer <anchor.pem> <signed.pdf>` (pyHanko, T093) and `uv run --with pikepdf python docs/tools/validate-pdf.py <signed.pdf>` | Met (2026-10-23) on pyHanko and qpdf: a signed revision reports `intact` with coverage `ENTIRE_FILE`, a twice-signed one reports `intact`/`ENTIRE_REVISION` then `intact`/`ENTIRE_FILE`, both `trusted` against the signer's own certificate as anchor, and qpdf `--check` reports no problems on either file. A timestamp token is embedded, never checked: the authority is the caller's. The `sign-and-archive` example (T094) writes a PDF/A-3b file and signs it afterwards — the order that keeps the archival bytes intact — and pyHanko reads what it wrote as field `ArchivalSignature`, `integrity intact (coverage ENTIRE_FILE)`, signed at the moment the options state (2026-10-24) |
| 12 | PDF/A-1b, -2b, -2u, -3b and -3u output | PDFsharp: PDF/A manager. PdfPig: no. | Must: embed every font, write XMP and an output intent, remove encryption and forbidden actions, refuse what cannot conform. | 1.1 | US4 trust | `PdfATests.Writes_the_structures_the_profile_requires`, `Refuses_a_font_it_cannot_embed`, `Refuses_transparency_for_pdf_a_1b_but_writes_it_for_2b` (T082) | `python docs/tools/validate-pdfa.py --verapdf <verapdf.bat> --profile 2b archive-2b.pdf`, and the same for every other profile: veraPDF 1.30.4 reports `PASS` for all five profiles of an authored page and of `SafeWebCore.pdf`, by hand and on every push (`compliance.yml`; T093, T096) | Met — the output intent is sRGB built in, or the caller's own ICC profile and condition, written as supplied and checked as ICC first; PDF/A-3 embedded files are associated through `/AF` with a stated relationship; levels B and U are written; a merge-time profile and level A are out of scope, and no conformance is claimed without a validator |
| 12 | PDF/A-1b, -2b, -2u, -3b, -3u and -4 output | PDFsharp: PDF/A manager. PdfPig: no. | Must: embed every font, write XMP and an output intent, remove encryption and forbidden actions, refuse what cannot conform. | 1.1 | US4 trust | `PdfATests.Writes_the_structures_the_profile_requires`, `Refuses_a_font_it_cannot_embed`, `Refuses_transparency_for_pdf_a_1b_but_writes_it_for_2b` (T082) | `python docs/tools/validate-pdfa.py --verapdf <verapdf.bat> --profile 2b archive-2b.pdf`, and the same for every other profile: veraPDF 1.30.4 reports `PASS` for all six profiles of an authored page and of `SafeWebCore.pdf`, by hand and on every push (`compliance.yml`; T093, T096) | Met — the output intent is sRGB built in, or the caller's own ICC profile and condition, written as supplied and checked as ICC first; PDF/A-3 embedded files are associated through `/AF` with a stated relationship; levels B and U are written, and PDF/A-4 writes the base level of ISO 19005-4; PDF/A-4f/-4u, a merge-time profile and level A are out of scope, and no conformance is claimed without a validator |
| 13 | Positioned letters, words and blocks; configurable segmentation and reading order | PDFsharp: not a reading API. PdfPig: yes. | Must: `PdfLetter` with Unicode, size, font name, box and baseline; word and block strategies; raw and column-aware reading order with the strategy in the result. | 1.1 | US3 reading | `PdfLayoutReaderTests.Reads_one_letter_per_glyph_in_content_order`, `Splits_a_two_column_page_into_one_block_per_column`, `Reads_a_page_of_two_columns_left_to_right_whatever_order_the_content_used` (T059–T060), `PdfLayoutCorpusTests.Meets_SC_004_on_the_labelled_corpus`, `PdfLayoutCorpusTests.Table_page_is_still_read_column_by_column` (T076) | `python docs/tools/score-layout.py <exports> --labels tests/SharpCorePDF.Tests/Assets/parity/labelled --known-order-mismatch table` (T075) | Met on the labelled corpus (T075–T076): recall and boxes 100% on all five documents, reading order 100% on four. `table` is recorded as a known order mismatch — a table is symmetric under the XY cut, so a cell becomes a block and the order comes out column by column, which is the order a two-column page needs; table semantics are out of contract. `PdfLayoutCorpusTests.Table_page_is_still_read_column_by_column` fails if the limitation ever goes away |
| 14 | Images, hyperlinks, form values, annotations, embedded files, metadata, bookmarks | PDFsharp: partial. PdfPig: yes. | Must: expose each resource through the read side, decode image pixels when asked, and warn on an unresolved destination or unsupported filter. | 1.1 partial, pixels in 1.2 | US3 reading | `PdfLayoutReaderTests.Reads_the_links_of_a_page_and_their_uris`, `Resolves_a_direct_and_a_named_destination`, `Keeps_an_unresolved_destination_and_says_so`, `PdfContentReaderTests.Returns_every_annotation_with_its_geometry_and_text`, `Returns_the_field_tree_with_qualified_names`, `PdfContentReaderTests.Exposes_the_samples_of_a_decoded_image_as_pixels`, `Does_not_expose_a_jpeg_as_pixels`, `Does_not_expose_the_pixels_of_a_filter_it_cannot_decode`, `Exposes_a_palette_image_as_the_colours_of_its_table`, `Exposes_a_palette_whose_table_is_a_string`, `Exposes_bilevel_samples_as_one_byte_per_sample`, `Exposes_four_bit_samples_at_the_scale_of_their_depth`, `Exposes_two_bit_samples_at_the_scale_of_their_depth`, `Exposes_a_cmyk_image_as_four_device_samples_per_pixel`, `Exposes_the_samples_of_an_iccbased_image`, `Does_not_expose_the_samples_of_a_separation_space`, `Does_not_expose_a_palette_image_whose_index_is_outside_its_table`, `Leaves_an_expansion_above_the_budget_out_of_the_record`, `Exposes_the_samples_of_an_image_that_declares_no_filter`, `Keeps_an_expansion_that_fits_the_budget_exactly`, `Exposes_four_bit_samples_of_a_three_channel_image`, `Does_not_expose_an_image_that_states_no_extent`, `Exposes_the_samples_of_a_profile_by_the_components_it_states`, `Does_not_read_a_palette_whose_table_is_empty`, `Refuses_to_resolve_a_colour_space_without_a_document`, `Resolves_the_calibrated_forms_of_the_device_spaces`, `Does_not_build_a_palette_over_a_palette_or_over_a_function`, `Reads_a_palette_whose_declared_index_is_zero`, `Clamps_a_declared_index_to_the_entries_the_table_holds`, `Does_not_read_an_icc_space_that_states_no_profile`, `Exposes_the_pixels_of_an_inline_image_stated_by_an_abbreviation` (T072) | `uv run --with pypdf python -c "from pypdf import PdfReader; ..."` and `validate-pdf.py` on the corpus, plus the `score-layout.py` run of T079 (5 documents, 0 short of a threshold) and an external parse of all four export formats (T079) | Met in 1.2 (2026-10-24): every resource the row names is exposed — images with their payload, geometry, mask and pixels, hyperlinks with resolved and unresolved destinations, form values through `PdfFormFieldInfo`, annotations, embedded files, metadata and bookmarks; pixels are `Gray8`, `Rgb24` or `Cmyk32` for every filter the library decodes and for an image whose stream declares no filter at all — a palette applied so an `Indexed` image yields colours, samples narrower than a byte widened, four device samples left as CMYK rather than converted — and `null` for a filter it does not decode, which is reported with `ImageFilterUnsupported` rather than dropped |
| 15 | Public read-only object graph and content-stream inspection | PDFsharp: partial. PdfPig: yes. | Must: immutable `PdfObjectView`/`PdfContentOperationView`, dangling references visible, operation offsets reported. | 1.1 tests, the rest 1.2 (completed 2026-11-06, Unreleased) | US3 reading | `PdfObjectInspectorTests.Returns_one_node_per_listed_object_in_number_order`, `Projects_a_reference_as_a_node_and_never_follows_it`, `Reports_a_dangling_reference_once_for_the_target_it_names`, `Reads_the_operations_of_a_page_in_the_order_it_states_them` | `python docs/tools/validate-pdf.py artifacts/graph.pdf` on the object-graph fixture, run 2026-11-06: qpdf names the file valid with warnings, and the warnings are exactly the two deliberate dangling references to object 99 the fixture states; an independent scan of the same bytes finds objects 1-7 and no object 99, which is what the inspector reports (seven nodes, three unresolved references). The mutation attempt is recorded too: 77.8% over `PdfObjectInspector.cs` | Evidenced (2026-11-06) - twelve tests in `PdfObjectInspectorTests` are in the suite, the external run above agrees with the inspector on which objects exist and which reference dangles, and the mutation score for the inspector is recorded rather than assumed |
Expand Down
4 changes: 2 additions & 2 deletions docs/tools/validate-pdfa.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
claim: it runs veraPDF, the reference validator, over the file and reports PASS or FAIL together with the
rules that failed. A file this library wrote is only an archival master once this says so.

--profile decides the flavour veraPDF checks against (1b, 2b, 2u, 3b or 3u). Without it veraPDF detects the
--profile decides the flavour veraPDF checks against (1b, 2b, 2u, 3b, 3u or 4). Without it veraPDF detects the
flavour the document declares, which is what a receiving archive usually does as well.

--format decides how the verdict is reached. `text` keeps veraPDF's own report and reads its PASS line,
Expand All @@ -36,7 +36,7 @@
import xml.etree.ElementTree as ElementTree
from pathlib import Path

FLAVOURS = ("1b", "2b", "2u", "3b", "3u")
FLAVOURS = ("1b", "2b", "2u", "3b", "3u", "4")
FORMATS = ("text", "xml")
VERSION_PATTERN = re.compile(r"veraPDF\s+(\d+(?:\.\d+)+)")

Expand Down
Loading
Loading