Artigo Técnico

Quais partes do PDF/A exigem um XMP extension schema?

Um número de fatura de ERP adicionado ao XMP de um arquivo PDF/A-2b rende um finding de propriedade não declarada, mas o mesmo packet num arquivo PDF/A-4 conforms. As partes 1 a 3 exigem uma descrição pdfaExtension:schemas para toda propriedade customizada e a parte 4 não, então o validador PDF/A do PDFium Component para Delphi lê o pdfaid:part antes de escolher um conjunto de regras

Fluxo de decisão do PDFium Component para Delphi lendo pdfaid:part para escolher checagens de extension schema nas partes 1 a 3 do PDF/A e regras de nível de packet no PDF/A-4
o validador lê o pdfaid:part primeiro, então um packet que se declara parte 4 pula os quatro findings de extension schema que as partes 1 a 3 levantam no PDFium Component para Delphi

O que as partes 1 a 3 do PDF/A exigem de uma propriedade customizada?

Uma descrição do namespace dele, mais uma linha nessa descrição nomeando a propriedade. A ISO 19005-1 §6.7.2 permite propriedades XMP só dos schemas predefinidos ou de extension schemas em conformidade com a §6.7.8, que quer cada descrição no mesmo metadata stream; a ISO 19005-2 §6.6.2.3.1 leva a regra às partes 2 e 3. Uma descrição não é licença geral. Ela nomeia propriedades uma a uma pelo pdfaProperty:name, então um packet que descreve inv:InvoiceNumber e também escreve inv:DueDate reprova no segundo. O PDFium Component relata esses casos sob quatro valores de TPdfAValidationIssue, um finding por falta: um prefixo renomeado, por exemplo, rende só o finding de prefixo

Valor de issueRelatado quandoCláusula
pvaiMissingExtensionSchemaUm namespace não predefinido está em uso e o packet não tem container pdfaExtension:schemas19005-1 §6.7.8, 19005-2 §6.6.2.3.1
pvaiXmpPropertyUndeclaredO container existe mas nenhuma descrição nele nomeia a propriedade19005-1 §6.7.2, 19005-2 §6.6.2.3.1
pvaiExtensionSchemaPrefixO namespace de uma descrição está ligado a um prefixo diferente do exigido19005-1 §6.7.8, 19005-2 §6.6.2.3.2
pvaiExtensionSchemaEntryMissingUma descrição deixa de fora um campo que a tabela dela lista19005-1 §6.7.8, 19005-2 §6.6.2.3.3

Qual dos dois primeiros você leva depende do produtor. Muitos writers PDF/A já descrevem o schema de identificação pdfaid num container, incluindo o SaveAsPdfA do PDFium Component, então um campo adicionado depois cai ao lado de um container que não tem entrada para ele. A rotina abaixo imprime só os findings de extension schema. Esperado: um arquivo PDF/A-2b escrito pelo SaveAsPdfA imprime pac2b e pvaiXmpPropertyUndeclared, um packet de parte 1 ou 2 sem container imprime pvaiMissingExtensionSchema, e um arquivo PDF/A-4 imprime só a linha de conformance dele

uses
  System.SysUtils, System.Classes, System.TypInfo,
  PDFium, FPdfPdfa, FPdfXmp;

const
  InvoiceNs = 'http://ns.example.com/invoice/1.0/';
  ExtensionIssues: TPdfAValidationIssues = [pvaiMissingExtensionSchema,
    pvaiXmpPropertyUndeclared, pvaiExtensionSchemaPrefix,
    pvaiExtensionSchemaEntryMissing];

procedure PrintExtensionIssues(Source: TStream);
var
  Res: TPdfAValidationResult;
  Issue: TPdfAValidationIssue;
begin
  Res := ValidatePdfAComplianceEx(Source, TPdfAValidationOptions.Default);
  Writeln(GetEnumName(TypeInfo(TPdfAConformance), Ord(Res.Conformance)));
  for Issue in Res.Issues * ExtensionIssues do
    Writeln('  ', GetEnumName(TypeInfo(TPdfAValidationIssue), Ord(Issue)));
end;

procedure ProbeCustomProperty(const FileName: string);
var
  Pdf: TPdf;
  Packet: TPdfXmpPacket;
  Output: TMemoryStream;
begin
  Output := TMemoryStream.Create;
  try
    Pdf := TPdf.Create(nil);
    try
      Pdf.FileName := FileName;
      Pdf.Active := True;
      Packet := Pdf.ReadXmpPacket;
      if Packet = nil then
        raise Exception.CreateFmt('%s has no XMP packet', [FileName]);
      try
        Packet.SetSimpleValue(InvoiceNs, 'inv', 'InvoiceNumber', 'INV-2026-0412');
        if not Pdf.SaveAsWithXmpPacket(Output, Packet) then
          raise Exception.Create('Saving the edited packet failed');
      finally
        Packet.Free;
      end;
    finally
      Pdf.Free;
    end;
    Output.Position := 0;
    PrintExtensionIssues(Output);
  finally
    Output.Free;
  end;
end;

O conjunto predefinido mudou entre o XMP 2004 e a ISO 16684-1

A parte 1 e a parte 2 discordam sobre o que predefinido significa. A ISO 19005-1 §6.7.2 aponta para a XMP Specification de janeiro de 2004, a ISO 19005-2 §6.6.2.3.1 para a ISO 16684-1, cuja lista é mais longa. O vão aparece nos arquivos do dia a dia pelo crs (configurações Camera Raw), pelo aux (dados EXIF adicionais) e pelo xmpDM (mídia dinâmica), que a TechNote 0008 do PDF/A Competence Center nota de rodapé como novas na especificação XMP 2005. Uma propriedade crs:AutoBrightness ou xmpDM:videoColorSpace precisa de descrição na parte 1 e é predefinida da parte 2 em diante. O corpus público do veraPDF tem arquivos de reprovação PDF/A-1b que adicionam uma dessas propriedades e nada mais, enquanto o próprio construtor de arquivos de teste do veraPDF escreve uma dica camera-raw ou dynamic-media nos arquivos PDF/A-2b dele, então um checador cego ao número da parte erra de um lado. As declarações também mudaram: photoshop:SupplementalCategories é Text em 2004 e um bag de Text na ISO 16684-1, então a forma bag reprova no PDF/A-1 e está correta no PDF/A-2

O atalho oposto também reprova. Chamar de extensão tudo que está fora das dez tabelas de schema da TechNote 0008 marcaria as estruturas sType e o namespace de qualifier Identifier que entradas xmpMM:History comuns usam, e a TechNote 0008 permite esses URIs no PDF/A-1. O PDFium Component lê a parte do pdfaid:part: um packet de parte 1 sem bloco de descrição que usa crs, aux ou xmpDM leva pvaiMissingExtensionSchema, um packet de parte 2 não leva finding de extension schema nenhum. Para saída PDF/A-1, arranque propriedades camera-raw e dynamic-media que ninguém downstream lê. Uma descrição crs completa chega a dezenas de entradas, cada uma uma chance de finding de entrada faltante

Prefixos exigidos e o # final nos URIs de schema

Namespaces XML normalmente deixam o writer escolher qualquer prefixo. A §6.7.8 tira essa liberdade do vocabulário de descrição, dando a cada estrutura um URI e um prefixo exigido: pdfaSchema, pdfaProperty, pdfaType para um value type e pdfaField para um campo de um; a ISO 19005-2 §6.6.2.3.2 reafirma os quatro. Ligar http://www.aiim.org/pdfa/ns/property# a nonpdfaProperty é XML equivalente e ainda reprova, e os arquivos do corpus do veraPDF para essa cláusula mantêm todo URI certo e renomeiam um prefixo. O seu próprio schema é outra história: o pdfaSchema:prefix registra um prefixo preferido, então inv é uma recomendação. Deixe-o igual ao prefixo que o packet liga de qualquer forma

Anatomia dos quatro vocabulários de extension schema do PDF/A mostrando prefixos exigidos, URIs de schema e campos obrigatórios, com a normalização do hash final que o PDFium Component aplica em Delphi
cada vocabulário de descrição carrega um URI e um prefixo exigido, e o componente descarta um # final dos dois lados antes de comparar URIs de namespace

Os URIs têm uma manha. A prosa da ISO 19005-1 §6.7.8 imprime http://www.aiim.org/pdfa/ns/schema sem # final, enquanto as tabelas dela e os arquivos em conformidade terminam o URI com um, então uma comparação estrita contra a prosa não casa nada. O PDFium Component descarta um # final dos dois lados antes de comparar. Escreva a forma com #, e copie o seu próprio namespace para o pdfaSchema:namespaceURI caractere por caractere. A frase final da ISO 19005-2 §6.6.2.3.2 então quer todo campo que as tabelas da §6.6.2.3.3 listam, e um vão é relatado como pvaiExtensionSchemaEntryMissing:

  • Schema (pdfaSchema): schema, namespaceURI e prefix, mais as listas property e valueType, que um schema sem nada a declarar pode deixar de fora
  • Property (pdfaProperty): name, valueType, category e description, onde category é internal ou external
  • Value type (pdfaType): type, namespaceURI, prefix, description e field, exigidos porque um value type customizado é uma estrutura
  • Field (pdfaField): name, valueType e description

Como escrever uma entrada estruturada em RDF/XML?

Qualquer uma de três formas, contanto que o item continue sendo uma estrutura. A ISO 32000-2 §14.3.2 entrega a gramática de um metadata stream à ISO 16684-1, que escreve XMP como um subconjunto de RDF/XML. A forma curta põe rdf:parseType="Resource" no rdf:li e lista os campos sob ele; a forma longa os embrulha num rdf:Description aninhado, e ambas significam a mesma estrutura anônima. Uma terceira grafia move campos de texto plain para atributos nesse rdf:Description. Só texto cabe ali: o pdfaSchema:property guarda uma sequência e segue elemento. Tire o rdf:parseType de um item de forma curta e o resultado não é RDF/XML. Um parser então espera texto ou um elemento node dentro do rdf:li, toma o pdfaSchema:schema por um typed node, e um elemento node não pode guardar texto fora de whitespace, então o primeiro campo já quebra a gramática. Um XSLT que reconstrói itens de lista, ou um template que regenera o bloco a partir de um dicionário, pode derrubar o atributo mantendo todo elemento. Leia essa saída de volta com um parser RDF diferente do que a escreveu para ver o dano

Três grafias legais em RDF/XML de uma entrada de extension schema do PDF/A, e a quebra de gramática quando o rdf:parseType é removido, como o PDFium Component as preserva em Delphi
forma curta, forma longa e abreviação por atributo descrevem a mesma estrutura, e remover o rdf:parseType de um item de forma curta quebra a gramática RDF no primeiro campo
<!-- Forma curta: o schema da fatura descrito por completo -->
<rdf:li rdf:parseType="Resource">
  <pdfaSchema:schema>Invoice data from the ERP</pdfaSchema:schema>
  <pdfaSchema:namespaceURI>http://ns.example.com/invoice/1.0/</pdfaSchema:namespaceURI>
  <pdfaSchema:prefix>inv</pdfaSchema:prefix>
  <pdfaSchema:property>
    <rdf:Seq>
      <rdf:li rdf:parseType="Resource">
        <pdfaProperty:name>InvoiceNumber</pdfaProperty:name>
        <pdfaProperty:valueType>Text</pdfaProperty:valueType>
        <pdfaProperty:category>external</pdfaProperty:category>
        <pdfaProperty:description>Invoice number assigned by the ERP</pdfaProperty:description>
      </rdf:li>
    </rdf:Seq>
  </pdfaSchema:property>
</rdf:li>

<!-- Forma longa: a mesma estrutura como node aninhado -->
<rdf:li>
  <rdf:Description>
    <pdfaSchema:schema>Invoice data from the ERP</pdfaSchema:schema>
    ...
  </rdf:Description>
</rdf:li>

<!-- Abreviação por atributo: campos de texto como atributos, a lista segue elemento -->
<rdf:li>
  <rdf:Description pdfaSchema:schema="Invoice data from the ERP"
      pdfaSchema:namespaceURI="http://ns.example.com/invoice/1.0/"
      pdfaSchema:prefix="inv">
    <pdfaSchema:property>...</pdfaSchema:property>
  </rdf:Description>
</rdf:li>

O PDFium Component mantém a grafia que chegar. Cada valor no TPdfXmpPacket que o TPdf.ReadXmpPacket retorna registra o rdf:parseType do elemento de origem dele, Resource, Literal ou Collection, e o ToXml o grava de volta; uma estrutura sem registro sai com rdf:parseType="Resource". Esse writer serve ao SaveAsWithXmpPacket e ao NormalizePdfAMetadata, a chamada que põe em linha as entradas Info e os equivalentes XMP delas, e um bloco de extensão em qualquer das três grafias valida igual antes e depois de um ciclo de leitura e save. Escreva entradas novas na forma curta. Todo campo segue elemento, o que mantém as edições uniformes, e casa com a entrada pdfaid que o SaveAsPdfA grava

Adicionando a sua descrição ao container que já está lá

Mescle a entrada nova no rdf:Bag existente. Um container por packet. O parser XMP do veraPDF recusa um packet com um segundo elemento pdfaExtension:schemas (Duplicate property or field node 'pdfaExtension:schemas'), e as reprovações caem nas regras gerais de metadata. Cada propriedade precisa de nome, value type, categoria e descrição, as entradas que uma fatura Factur-X preenche para declarar as propriedades fx dela num extension schema. O listing emenda um item de forma curta antes do </rdf:Bag>, que o ToXml grava na linha própria do container. O item declara pdfaSchema e pdfaProperty nele mesmo, então parseia igual onde quer que caia

const
  ExtensionNs = 'http://www.aiim.org/pdfa/ns/extension/';
  ContainerEnd = '</rdf:Bag></pdfaExtension:schemas>';
  TopDescriptionEnd = '</rdf:Description>'#10' </rdf:RDF>';

function InvoiceSchemaItem: string;
begin
  Result := '<rdf:li rdf:parseType="Resource"' +
    ' xmlns:pdfaSchema="http://www.aiim.org/pdfa/ns/schema#"' +
    ' xmlns:pdfaProperty="http://www.aiim.org/pdfa/ns/property#">' +
    '<pdfaSchema:schema>Invoice data from the ERP</pdfaSchema:schema>' +
    '<pdfaSchema:namespaceURI>' + InvoiceNs + '</pdfaSchema:namespaceURI>' +
    '<pdfaSchema:prefix>inv</pdfaSchema:prefix>' +
    '<pdfaSchema:property><rdf:Seq><rdf:li rdf:parseType="Resource">' +
    '<pdfaProperty:name>InvoiceNumber</pdfaProperty:name>' +
    '<pdfaProperty:valueType>Text</pdfaProperty:valueType>' +
    '<pdfaProperty:category>external</pdfaProperty:category>' +
    '<pdfaProperty:description>Invoice number assigned by the ERP' +
    '</pdfaProperty:description>' +
    '</rdf:li></rdf:Seq></pdfaSchema:property></rdf:li>';
end;

// True quando uma entrada de schema descreve Uri, seja qual grafia ela usa
function DescribesNamespace(const V: TPdfXmpValue; const Uri: string): Boolean;
var
  Q: Integer;
begin
  for Q := 0 to High(V.Qualifiers) do      // campos como atributos no rdf:li
    if (V.Qualifiers[Q].Name = 'namespaceURI') and
       (string(V.Qualifiers[Q].Value) = Uri) then
      Exit(True);
  Result := (Pos('>' + Uri + '</', string(V.RawXml)) > 0) or    // elementos
    (Pos('namespaceURI="' + Uri + '"', string(V.RawXml)) > 0);   // atributos
end;

// Retorna um novo packet; o chamador o libera
function WithInvoiceSchema(Packet: TPdfXmpPacket): TPdfXmpPacket;
var
  Xml: string;
  Index, J, P: Integer;
  HasContainer: Boolean;
begin
  HasContainer := Packet.TryGetProperty(ExtensionNs, 'schemas', Index);
  if HasContainer then
    for J := 0 to High(Packet.Properties[Index].Values) do
      if DescribesNamespace(Packet.Properties[Index].Values[J], InvoiceNs) then
        Exit(Packet.Clone);                // já descrito
  Xml := Packet.ToXml;
  P := Pos(ContainerEnd, Xml);
  if P > 0 then
    Insert(InvoiceSchemaItem, Xml, P)      // entra no bag existente
  else if HasContainer then
    raise EPdfXmpError.Create('Extension container uses an unexpected prefix')
  else
  begin
    P := Pos(TopDescriptionEnd, Xml);
    if P = 0 then
      raise EPdfXmpError.Create('Unexpected XMP packet layout');
    Insert('<pdfaExtension:schemas xmlns:pdfaExtension="' + ExtensionNs +
      '"><rdf:Bag>' + InvoiceSchemaItem + ContainerEnd + #10'  ', Xml, P);
  end;
  Result := TPdfXmpPacket.Parse(Xml);
end;

procedure TagInvoice(const SourceFile, TargetFile, InvoiceNo: string);
var
  Pdf: TPdf;
  Packet, Described: TPdfXmpPacket;
  Written: TFileStream;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := SourceFile;
    Pdf.Active := True;
    Packet := Pdf.ReadXmpPacket;
    if Packet = nil then
      raise Exception.CreateFmt('%s has no XMP packet', [SourceFile]);
    Described := nil;
    try
      Packet.SetSimpleValue(InvoiceNs, 'inv', 'InvoiceNumber', InvoiceNo);
      Described := WithInvoiceSchema(Packet);
      if not Pdf.SaveAsWithXmpPacket(TargetFile, Described) then
        raise Exception.CreateFmt('Could not write %s', [TargetFile]);
    finally
      Described.Free;
      Packet.Free;
    end;
  finally
    Pdf.Free;
  end;
  Written := TFileStream.Create(TargetFile, fmOpenRead or fmShareDenyWrite);
  try
    PrintExtensionIssues(Written);         // do primeiro listing
  finally
    Written.Free;
  end;
end;

Esperado: para uma origem PDF/A-1, -2 ou -3 escrita pelo SaveAsPdfA, o TagInvoice imprime a linha de conformance e nenhum dos quatro valores de extension schema, com a entrada da fatura na forma curta ao lado da pdfaid. Uma segunda execução deixa o bag em paz seja qual for a grafia da entrada existente: o DescribesNamespace busca no RawXml e, para atributos num rdf:li vazio, nos qualifiers. Um container sob outro prefixo levanta exceção, já que um novo seria o duplicado que o veraPDF recusa. Quando o ERP adicionar um vencimento, estenda a sequência pdfaSchema:property existente

O PDF/A-4 confere extension schemas de fato?

Não. A ISO 19005-4 §6.7.2.1 mantém só regras de nível de packet: a chave Metadata do catálogo, os atributos de header descontinuados bytes e encoding, XML bem formado e UTF-8. Uma propriedade sem descrição, uma descrição sob nonpdfaSchema e uma sem pdfaSchema:schema deixam todas um arquivo conforme sob o perfil PDF/A-4 do veraPDF, e o PDFium Component roda as quatro checagens de extension schema só quando o pdfaid:part é 1, 2 ou 3. O schema de identificação mantém as regras dele em toda parte. Sob a §6.7.3 da parte 4 o namespace dele ainda deve estar ligado ao pdfaid, e o conjunto de propriedades dele cresce por parte: part, conformance e, desde a Amendment 1 de 2007, amd na parte 1, corr a partir da ISO 19005-2 §6.6.4, rev na parte 4. Um prefixo errado é relatado como pvaiXmpIdPrefixWrong e um nome extra como pvaiXmpIdPropertyUnknown em toda parte

Para comparar partes num único documento, mude o packet e nada mais: insira a ligação de namespace dentro do XMP e apague tantos bytes de whitespace entre tags quantos inserir, para o /Length, os offsets de cross-reference e o header %PDF-2.0 ficarem no lugar. Um rewrite do pypdf pode devolver um arquivo PDF/A-4 com header %PDF-1.3 cujas reprovações enterram o resultado de metadata. Para saída de produção, escreva a descrição também em packets PDF/A-4: custa poucas centenas de bytes, o validador do PDFium Component a deixa em paz na parte 4, e o packet pode depois migrar para um entregável PDF/A-3 sem mudança