Articolo tecnico

Quali parti PDF/A richiedono un extension schema XMP?

Un numero fattura ERP aggiunto all'XMP di un file PDF/A-2b si prende un rilievo di proprietà non dichiarata, eppure lo stesso packet in un file PDF/A-4 è conforme. Le parti da 1 a 3 esigono una descrizione pdfaExtension:schemas per ogni proprietà personalizzata e la parte 4 no, così il validatore PDF/A di PDFium Component per Delphi legge pdfaid:part prima di scegliere un set di regole

Flusso decisionale di PDFium Component per Delphi che legge pdfaid:part per scegliere i controlli extension schema sotto le parti PDF/A da 1 a 3 e le regole a livello di packet sotto PDF/A-4
Il validatore legge prima pdfaid:part, così un packet che dichiara parte 4 salta i quattro rilievi extension schema che le parti da 1 a 3 alzano in PDFium Component per Delphi

Cosa chiedono le parti PDF/A da 1 a 3 a una proprietà personalizzata?

Una descrizione del suo namespace, più una riga in quella descrizione che nomina la proprietà. ISO 19005-1 §6.7.2 ammette proprietà XMP solo dagli schema predefiniti o dagli extension schema conformi a §6.7.8, che vuole ogni descrizione nello stesso stream di metadati; ISO 19005-2 §6.6.2.3.1 porta la regola nelle parti 2 e 3. Una descrizione non è un permesso generico. Nomina le proprietà una per una attraverso pdfaProperty:name, così un packet che descrive inv:InvoiceNumber e scrive anche inv:DueDate fallisce sulla seconda. PDFium Component riporta questi casi sotto quattro valori TPdfAValidationIssue, un rilievo per difetto: un prefisso rinominato, per esempio, produce solo il rilievo sul prefisso

Valore di issueRiportato quandoClause
pvaiMissingExtensionSchemaUn namespace non predefinito è in uso e il packet non ha un contenitore pdfaExtension:schemas19005-1 §6.7.8, 19005-2 §6.6.2.3.1
pvaiXmpPropertyUndeclaredIl contenitore esiste ma nessuna descrizione in esso nomina la proprietà19005-1 §6.7.2, 19005-2 §6.6.2.3.1
pvaiExtensionSchemaPrefixUn namespace di descrizione è legato a un prefisso diverso da quello richiesto19005-1 §6.7.8, 19005-2 §6.6.2.3.2
pvaiExtensionSchemaEntryMissingUna descrizione omette un campo che la sua tabella elenca19005-1 §6.7.8, 19005-2 §6.6.2.3.3

Quale dei primi due vi capiti dipende dal produttore. Molti writer PDF/A descrivono già lo schema di identificazione pdfaid in un contenitore, SaveAsPdfA di PDFium Component incluso, così un campo aggiunto dopo atterra accanto a un contenitore che non ha voce per lui. La routine qui sotto stampa solo i rilievi extension schema. Atteso: un file PDF/A-2b scritto da SaveAsPdfA stampa pac2b e pvaiXmpPropertyUndeclared, un packet parte 1 o 2 senza contenitore stampa pvaiMissingExtensionSchema, e un file PDF/A-4 stampa da solo la sua riga di conformità

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;

Il set predefinito si è spostato tra XMP 2004 e ISO 16684-1

Parte 1 e parte 2 non sono d'accordo su cosa significhi predefinito. ISO 19005-1 §6.7.2 rimanda all'XMP Specification di gennaio 2004, ISO 19005-2 §6.6.2.3.1 a ISO 16684-1, la cui lista è più lunga. Il divario si vede nei file di tutti i giorni in crs (impostazioni Camera Raw), aux (dati EXIF aggiuntivi) e xmpDM (media dinamici), che il TechNote 0008 del PDF/A Competence Center mette a nota come nuove nella specifica XMP 2005. Una proprietà crs:AutoBrightness o xmpDM:videoColorSpace vuole una descrizione sotto parte 1 ed è predefinita dalla parte 2 in poi. Il corpus pubblico di veraPDF ha file di fallimento PDF/A-1b che aggiungono una proprietà simile e nient'altro, mentre il generatore di file di test di veraPDF stesso scrive un suggerimento camera-raw o dynamic-media nei suoi file PDF/A-2b, quindi un checker cieco al numero di parte sbaglia da un lato. Anche le dichiarazioni si sono spostate: photoshop:SupplementalCategories è Text nel 2004 e un bag di Text in ISO 16684-1, così la forma bag fallisce PDF/A-1 ed è corretta in PDF/A-2

La scorciatoia opposta fallisce pure. Chiamare extension tutto ciò che sta fuori dalle dieci tabelle di schema del TechNote 0008 segnalerebbe le strutture sType e il namespace qualificatore Identifier che le normali voci xmpMM:History usano, e il TechNote 0008 ammette quei URI in PDF/A-1. PDFium Component legge la parte da pdfaid:part: un packet parte 1 senza blocco di descrizione che usa crs, aux o xmpDM prende pvaiMissingExtensionSchema, un packet parte 2 non prende alcun rilievo extension schema. Per output PDF/A-1, togliete le proprietà camera-raw e dynamic-media che nessuno a valle legge. Una descrizione crs completa corre su decine di voci, ognuna un'occasione per un rilievo di voce mancante

Prefissi richiesti e # finale negli URI di schema

I namespace XML di norma lasciano allo writer la scelta di qualunque prefisso. §6.7.8 toglie quella libertà per il vocabolario delle descrizioni, dando a ogni struttura un URI e un prefisso richiesto: pdfaSchema, pdfaProperty, pdfaType per un value type e pdfaField per un field di uno; ISO 19005-2 §6.6.2.3.2 ribadisce tutti e quattro. Legare http://www.aiim.org/pdfa/ns/property# a nonpdfaProperty è XML equivalente e fallisce lo stesso, e i file del corpus veraPDF per questa clause tengono ogni URI corretto e rinominano un prefisso. Il vostro schema è un'altra faccenda: pdfaSchema:prefix registra un prefisso preferito, quindi inv è una raccomandazione. Tenetelo uguale al prefisso che il packet lega comunque

Anatomia dei quattro vocabolari extension schema PDF/A che mostra prefissi richiesti, URI di schema e campi obbligatori, con la normalizzazione dell'hash finale che PDFium Component applica in Delphi
Ogni vocabolario di descrizione porta un URI e un prefisso richiesto, e il componente toglie un # finale da entrambi i lati prima di confrontare gli URI di namespace

Gli URI hanno una bizzarria. La prosa di ISO 19005-1 §6.7.8 stampa http://www.aiim.org/pdfa/ns/schema senza # finale, mentre le sue tabelle e i file conformi chiudono l'URI con uno, così un confronto rigoroso contro la prosa non trova nulla. PDFium Component toglie un # finale da entrambi i lati prima di confrontare. Scrivete la forma con #, e copiate il vostro namespace in pdfaSchema:namespaceURI carattere per carattere. La frase di chiusura di ISO 19005-2 §6.6.2.3.2 vuole poi ogni campo che le tabelle di §6.6.2.3.3 elencano, e un vuoto viene riportato come pvaiExtensionSchemaEntryMissing:

  • Schema (pdfaSchema): schema, namespaceURI e prefix, più le liste property e valueType, che uno schema senza nulla da dichiarare può lasciare fuori
  • Property (pdfaProperty): name, valueType, category e description, dove category è o internal o external
  • Value type (pdfaType): type, namespaceURI, prefix, description e field, richiesti perché un value type personalizzato è una struttura
  • Field (pdfaField): name, valueType e description

Come si scrive una voce strutturata in RDF/XML?

In qualunque di tre modi, purché la voce resti una struttura. ISO 32000-2 §14.3.2 affida la grammatica di uno stream di metadati a ISO 16684-1, che scrive XMP come sottoinsieme di RDF/XML. La forma breve mette rdf:parseType="Resource" sul rdf:li ed elenca i campi sotto di lui; la forma lunga li avvolge in un rdf:Description annidato, e entrambe significano la stessa struttura anonima. Una terza ortografia sposta i campi testo in attributi su quel rdf:Description. Lì ci sta solo testo: pdfaSchema:property contiene una sequenza e resta un elemento. Togliete rdf:parseType da una voce in forma breve e il risultato non è RDF/XML. Un parser si aspetta allora testo o un node element dentro il rdf:li, prende pdfaSchema:schema per un typed node, e un node element non può contenere testo non bianco, così il primo campo rompe già la grammatica. Un XSLT che ricostruisce le voci di lista, o un template che rigenera il blocco da un dizionario, può perdere l'attributo tenendo ogni elemento. Rileggete un simile output con un parser RDF diverso da quello che l'ha scritto per vedere il danno

Tre ortografie legali RDF/XML di una stessa voce extension schema PDF/A, e la rottura di grammatica quando rdf:parseType viene tolto, così come PDFium Component le conserva in Delphi
Forma breve, forma lunga e scorciatoia ad attributi descrivono tutte la stessa struttura, e togliere rdf:parseType da una voce in forma breve rompe la grammatica RDF al primo campo
<!-- Forma breve: lo schema della fattura descritto per intero -->
<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 lunga: la stessa struttura come nodo annidato -->
<rdf:li>
  <rdf:Description>
    <pdfaSchema:schema>Invoice data from the ERP</pdfaSchema:schema>
    ...
  </rdf:Description>
</rdf:li>

<!-- Scorciatoia ad attributi: i campi testo come attributi, la lista resta un 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>

PDFium Component conserva qualunque ortografia sia arrivata. Ogni valore nel TPdfXmpPacket che TPdf.ReadXmpPacket restituisce registra il rdf:parseType del suo elemento sorgente, Resource, Literal o Collection, e ToXml lo riscrive; una struttura senza registro esce con rdf:parseType="Resource". Quel writer serve SaveAsWithXmpPacket e NormalizePdfAMetadata, la chiamata che mette in linea le voci Info e i loro equivalenti XMP, e un blocco di estensione in qualunque delle tre ortografie valida uguale prima e dopo un ciclo di lettura e salvataggio. Scrivete le nuove voci in forma breve. Ogni campo resta un elemento, il che tiene uniformi le modifiche, e combacia con la voce pdfaid che SaveAsPdfA scrive

Aggiungere la vostra descrizione al contenitore che c'è già

Unite la nuova voce al rdf:Bag esistente. Un contenitore per packet. Il parser XMP di veraPDF si rifiuta di leggere un packet con un secondo elemento pdfaExtension:schemas (Duplicate property or field node 'pdfaExtension:schemas'), e i fallimenti atterrano sulle regole generali dei metadati. Ogni proprietà vuole name, value type, category e description, le voci che una fattura Factur-X compila per dichiarare le sue proprietà fx in un extension schema. Il listato innesta una voce in forma breve prima di </rdf:Bag>, che ToXml scrive sulla riga propria del contenitore. La voce dichiara da sé pdfaSchema e pdfaProperty, quindi parsa uguale ovunque atterri

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 una voce di schema descrive Uri, quale ortografia essa usi
function DescribesNamespace(const V: TPdfXmpValue; const Uri: string): Boolean;
var
  Q: Integer;
begin
  for Q := 0 to High(V.Qualifiers) do      // campi come attributi su 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    // elementi
    (Pos('namespaceURI="' + Uri + '"', string(V.RawXml)) > 0);   // attributi
end;

// Restituisce un nuovo packet; il chiamante lo 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);                // già descritta
  Xml := Packet.ToXml;
  P := Pos(ContainerEnd, Xml);
  if P > 0 then
    Insert(InvoiceSchemaItem, Xml, P)      // entra nel bag esistente
  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);         // dal primo listato
  finally
    Written.Free;
  end;
end;

Atteso: per una sorgente PDF/A-1, -2 o -3 scritta da SaveAsPdfA, TagInvoice stampa la riga di conformità e nessuno dei quattro valori extension schema, con la voce della fattura in forma breve accanto a quella pdfaid. Una seconda esecuzione lascia stare il bag quale ortografia usi la voce esistente: DescribesNamespace cerca in RawXml e, per gli attributi su un rdf:li vuoto, nei qualificatori. Un contenitore sotto altro prefisso alza un'eccezione, dato che uno nuovo sarebbe il duplicato che veraPDF rifiuta. Quando l'ERP aggiunge una data di scadenza, allungate la sequenza pdfaSchema:property esistente

PDF/A-4 controlla proprio gli extension schema?

No. ISO 19005-4 §6.7.2.1 tiene solo le regole a livello di packet: la chiave Metadata del catalogo, gli attributi di header deprecati bytes e encoding, XML ben formato e UTF-8. Una proprietà non descritta, una descrizione sotto nonpdfaSchema e una senza pdfaSchema:schema lasciano tutte un file conforme sotto il profilo PDF/A-4 di veraPDF, e PDFium Component fa girare i suoi quattro controlli extension schema solo quando pdfaid:part è 1, 2 o 3. Lo schema di identificazione tiene le sue regole ovunque. Sotto §6.7.3 della parte 4 il suo namespace deve ancora legarsi a pdfaid, e il suo set di proprietà cresce con la parte: part, conformance e, dall'Amendment 1 del 2007, amd nella parte 1, corr da ISO 19005-2 §6.6.4 in poi, rev nella parte 4. Un prefisso sbagliato viene riportato come pvaiXmpIdPrefixWrong e un nome in più come pvaiXmpIdPropertyUnknown in ogni parte

Per confrontare le parti su un solo documento, cambiate il packet e nient'altro: inserite il binding del namespace dentro l'XMP e cancellate altrettanti byte di white space tra i tag, così /Length, gli offset di cross-reference e l'header %PDF-2.0 restano al loro posto. Una riscrittura con pypdf può ridare un file PDF/A-4 con un header %PDF-1.3 i cui fallimenti seppelliscono il risultato dei metadati. Per l'output di produzione, scrivete la descrizione anche nei packet PDF/A-4: costa qualche centinaio di byte, il validatore del PDFium Component la lascia stare sotto parte 4, e il packet potrà più tardi migrare immutato in un deliverable PDF/A-3