Ваш preflight сообщает, что файл чист по PDF/UA. Тот же файл открывается в veraPDF и получает флаг Figure без alternate text по пункту 7.3. Оба инструмента правы, и разрыв между ними как раз и описывает всю проблему проверки accessibility простым сканированием байтов. Byte-level pass подтверждает лишь то, что файл говорит , будто он тегирован: находит /StructTreeRoot , /MarkInfo /Marked true , pdfuaid:part в XMP packet, заголовок документа и язык. Это marker формата, и они необходимы. Но они ничего не говорят о том, есть ли у реальной Figure на четвертой странице описание, которое screen reader сможет прочитать вслух. Ответ на этот вопрос живет в tag tree, и, чтобы получить его, нужно обходить дерево
PDFium Component - нативная VCL PDF-библиотека для Delphi и C++Builder, и ее ValidatePdfUa выполняет оба прохода. Byte-level pass занимается marker формата. Поверх него стоит проход по structure tree, который загружает живое дерево тегов, обходит каждый элемент и проверяет небольшой набор high-confidence правил содержимого, где отсутствие атрибута означает реальный accessibility defect, а не вкусовую стилистику. Эта статья посвящена именно второму проходу: что он проверяет, почему логика rules оформлена как pure function без DLL под ней и где именно она намеренно останавливается
Почему byte scan не видит отсутствующий Alt
ISO 14289-1, PDF/UA-1, накладывает слой требований поверх ISO 32000. Некоторые из этих требований структурные и видны в сырых байтах файла: catalog обязан объявлять structure tree, viewer preferences должны выставлять DisplayDocTitle , шрифты должны быть встроены. Token scanner, который сначала вычищает body stream и затем ищет name token с корректными delimiter boundary, может проверять все это, и ValidatePdfUaCompliance у PDFium именно так и делает для пунктов вроде 7.1, 7.18 и 7.21
Но требование "у каждой Figure есть alternate text" - это уже не свойство синтаксиса файла. Это свойство логической структуры , то есть дерева tagged element, которое связывает контент со смыслом. Запись Alt у Figure может находиться в словаре structure element, может приходить через span /ActualText или через custom type с role mapping. Надежно ответить на вопрос простым grep по /Alt в byte stream нельзя, потому что эта строка встречается и в посторонних контекстах, может оказаться сжатой внутри object stream и ничего не говорит о том, какому именно structure element она принадлежит. Честный способ ответить - спрашивать собственное structure tree документа, element by element, тем же способом, каким работают veraPDF и PAC. На этом и держится Tier-1 набор проверок PDFium: byte scan для формата, tree walk для контента
Чтение живого дерева тегов
Сырьем здесь служит TPdf.GetStructureElements , также доступный как свойство StructureElements , которое возвращает TPdfStructureElements - плоский массив записей TPdfStructureElement в порядке документа. Каждая запись является проекцией одного structure element через accessor PDFium, с полями, которые реально нужны правилам accessibility:
type
TPdfStructureElement = record
Level: Integer; // глубина в дереве тегов
ParentIndex: Integer; // индекс родительского элемента или -1
TypeName: WString; // standard /S name: Figure, Formula, Note...
Title: WString; // /T
AlternateText: WString; // /Alt (FPDF_StructElement_GetAltText)
ActualText: WString; // /ActualText
Expansion: WString; // /E
ID: WString; // /ID (FPDF_StructElement_GetID)
Language: WString; // /Lang
MarkedContentIDs: TPdfIntegerArray;
// ... поля учёта дочерних элементов ...
end;
Поле TypeName - это именно то, на чем строится validator. Оно приходит из FPDF_StructElement_GetType , который возвращает стандартный structure type элемента, то есть его имя /S , уже после того, как PDFium разрешил role map. AlternateText приходит из FPDF_StructElement_GetAltText , ActualText из FPDF_StructElement_GetActualText , а ID из FPDF_StructElement_GetID . Поскольку массив плоский и упорядоченный, validator может рассуждать обо всем документе целиком без рекурсии, а это важно для одного правила, которое является не локальным по элементу, а глобальным
Проверяющая функция чистая, и это сделано намеренно
Логика правил не живет внутри метода, который разговаривает с DLL. Это отдельная, публичная, pure function:
function ValidatePdfUaStructureElements(
const Elements: TPdfStructureElements): TPdfUaValidationIssues;
Она принимает плоский массив element и возвращает набор issues. Она не вызывает ни одной функции PDFium, не открывает документов и не трогает global state. Такое разделение выбрано сознательно, и оно окупается дважды. Во-первых, тестируемость: в unit test можно собрать синтетический массив TPdfStructureElements - Figure без Alt, Formula, у которой единственный доступный текст сидит в ActualText, две Note с одним и тем же ID - и проверить набор результатов без какого-либо pdfium.dll вообще. Логика rules проверяется офлайн, а обход DLL отдельно подтверждается живым smoke test, который просто пропускается, если библиотеки нет
Во-вторых, ясность ответственности. TPdf.ValidatePdfUa владеет грязной частью работы: загрузкой каждой страницы, извлечением ее элементов и накоплением их в общий массив. После этого он передает чистый массив pure checker. "Получить данные", DLL, side effect, lifetime, и "оценить правила", pure и deterministic, никогда не перемешиваются. Когда какое-то правило нужно изменить, вы правите функцию, в которой нет I/O
Что именно проверяют три правила
Проход по structure tree поднимает три значения issues, которые были добавлены в конец TPdfUaValidationIssues , чтобы enum оставался ABI-stable для существующих вызывающих сторон: pvuaiFigureMissingAlt , pvuaiFormulaMissingAlt и pvuaiNoteMissingId . Размер тела проверок настолько мал, что его можно понять целиком:
for I := 0 to High(Elements) do
begin
T := string(Elements[I].TypeName);
if T = 'Figure' then
begin
// §7.3 — Figure требует альтернативного представления:
// запись Alt или ActualText. Помечать только когда ОБЕ пусты
if (Elements[I].AlternateText = '') and (Elements[I].ActualText = '') then
Include(Result, pvuaiFigureMissingAlt);
end
else if T = 'Formula' then
begin
// §7.7 — то же правило, что для Figure: Alt или ActualText
if (Elements[I].AlternateText = '') and (Elements[I].ActualText = '') then
Include(Result, pvuaiFormulaMissingAlt);
end
else if T = 'Note' then
begin
// §7.9 — каждая Note должна иметь уникальный ID
NoteId := string(Elements[I].ID);
if NoteId = '' then
Include(Result, pvuaiNoteMissingId)
else
for J := 0 to I - 1 do
if (string(Elements[J].TypeName) = 'Note') and
(string(Elements[J].ID) = NoteId) then
begin
Include(Result, pvuaiNoteMissingId);
Break;
end;
end;
end;
Пунктом 7.3 регулируются figure: элемент Figure обязан предоставлять текстовую альтернативу. Очевидная реализация смотрит только на запись Alt, и такая проверка оказывается строже, чем эталонные валидаторы. PDF/UA принимает figure, чей доступный текст подаётся через ActualText — замещающий текст является допустимой альтернативной репрезентацией — поэтому правило помечает Figure, только когда пусты и Alt, и ActualText. Пункт 7.7 покрывает formula, и ветка Formula использует тот же тест Alt-or-ActualText, потому что Formula, несущая свой доступный текст в одном лишь ActualText, столь же конформна, а проверка только по Alt ложно отвергла бы её
Пункт 7.9 — другого рода. У Note обязан быть /ID, и этот ID должен быть уникальным по всему документу. Отсутствующий ID — это отказ отдельного элемента. А дублирующийся ID — отношение между двумя элементами, вот почему важен плоский массив: для каждой Note проверяющая функция сканирует назад по уже просмотренным элементам и помечает коллизию с любой ранней Note, несущей тот же ID. Цена — очевидные O(n²) по числу Note, что неважно для любого реального документа и оставляет функцию одним читаемым циклом без вспомогательного индекса, который пришлось бы синхронизировать
Накопление по страницам, чтобы уникальность была глобальной
PDFium открывает structure element по страницам, а не по документу, поэтому orchestration в ValidatePdfUa обязано сначала собрать их вместе. Оно проходит каждую страницу через FPDF_LoadPage / GetStructureElementsForPage / FPDF_ClosePage независимо от того, какая страница у компонента сейчас открыта, и дописывает элементы каждой страницы в один общий массив. Лишь после этого вызывается pure checker:
// внутри TPdf.ValidatePdfUa, после прохода по байтам
if (FDocument <> nil) and
(not (pvuaiMissingStructTreeRoot in Result.Issues)) then
begin
AllElems := nil;
PageTotal := FPDF_GetPageCount(FDocument);
for I := 0 to PageTotal - 1 do
begin
Page := FPDF_LoadPage(FDocument, I);
if Page = nil then Continue;
try
PageElems := GetStructureElementsForPage(Page);
finally
FPDF_ClosePage(Page);
end;
// добавить PageElems в AllElems ...
end;
Result.Issues := Result.Issues + ValidatePdfUaStructureElements(AllElems);
end;
Именно это накопление и делает проверку уникальности 7.9 корректной. Две Note на разных страницах вполне могут разделять один ID. Если валидировать страницу за страницей, столкновение никогда не станет видимым, потому что каждый page-level набор элементов будет выглядеть внутренне согласованным. Сборка единого массива по всему документу - единственный способ увидеть дубликат. Стоит отметить и guard в начале: tree walk запускается только если byte-level pass не сообщил pvuaiMissingStructTreeRoot . У нетегированного документа просто нет дерева, которое можно обходить, и он уже помечен за отсутствие structure root, поэтому page-level load полностью пропускаются. Глубокий проход ничего не стоит на документах, которым он все равно не поможет
Консервативно по замыслу: молчаливо пропустить, но никогда не кричать зря
Самое важное свойство этого validator заключается именно в том, чего он отказывается делать. Он сопоставляет только стандартные имена типа /S , которые FPDF_StructElement_GetType возвращает напрямую: Figure , Formula , Note . Документ, определяющий custom type и role-mapping его в Figure, в зависимости от того, как PDFium разрешит тип, может сообщить собственное имя. Когда это происходит, checker не узнает его и молчит. Это false negative, и именно такого поведения тут и добиваются. Дизайнерское правило - лучше недосообщить, чем хоть раз выдать ложноположительный результат , потому что preflight tool, который поднимает тревогу на conformant файлах, быстро приучает пользователей его игнорировать, а игнорируемый validator хуже, чем никакой. Декоративные изображения живут в artifact stream, а не в structure tree, поэтому как Figure они вообще не появляются. Жалобу на "missing Alt" для фоновой линии, корректно помеченной как artifact, вы здесь не получите
По этой же причине область ограничена всего тремя правилами. Вложенность уровней heading, пункт 7.4, scope у table header, 7.5, и обнаружение cycle в role map, 7.1, все это вполне реальные требования PDF/UA, но их качественная проверка требует серьезного graph и attribute analysis, а наивная проверка дает именно те false positive, которые этот дизайн запрещает. PDF/UA допускает шаблоны heading вроде H1, H2, H3, H3, а простое правило "уровень должен строго расти" ошибочно их отвергло бы. Такие проверки оставлены специализированным conformance tool. Tier-1 ограничен тем подмножеством, где отсутствие атрибута трактуется однозначно
Граница, сформулированная прямо
Два ограничения стоит знать до того, как вы встроите это в release gate. Первое: проверяющая функция ровно настолько хороша, насколько то, что PDFium способен прочитать из structure element. Часть файлов, которые эталонные валидаторы пропускают, подаёт alternate text через механизм, который accessor PDFium не показывает, так что FPDF_StructElement_GetAltText возвращает пустоту, хотя файл конформен. Pure checker тогда помечает отсутствующий Alt на неполных данных — вердикт исходит из того, что показывает движок, а не из логики правила. Ослабить правило, чтобы поглотить эти случаи, значит ослепить его и для реальных отказов, которые оно призвано ловить, поэтому правило остаётся строгим, и это ещё один довод отдать финальное слово по помеченному файлу полноценному валидатору
Второе: это preflight, а не сертификация. Tier-1 ловит высокодостоверные ошибки содержимого, которые byte scan структурно поймать не может, и делает это без ложных срабатываний — но полная конформность PDF/UA, включая семантику заголовков, структуру таблиц и корректность порядка чтения, остаётся за полноценным валидатором и в конечном счёте за живым ревьюером. Используйте ValidatePdfUa, чтобы быстро и дёшево отсекать очевидные дефекты в собственном pipeline, а финальное слово оставьте veraPDF или PAC. Тот же обход structure tree лежит в основе построения доступного PDF-ридера на Delphi, где tag tree управляет порядком чтения и озвучиваемым текстом, и дополняет работу с метаданными в разборе PDF-аннотаций из Delphi
Описанные здесь API для structure tree и validator ValidatePdfUa поставляются вместе с PDFium Component для Delphi и C++Builder, VCL, и Lazarus/FPC, LCL. На странице продукта есть ссылка на полный API reference, включая полную структуру записи TPdfStructureElement и перечисление issues, стоящее за этими проверками