Convert a PDF document to PDF/A

The Pdf Tools SDK lets you convert a PDF document so that it meets a defined PDF/A standard and conformance level, making the minimum changes necessary to the PDF structure and objects so it complies. It provides detailed information about any changes that were made during the conversion process.

The Pdf Tools SDK supports conversion to the following PDF/A standards:

• PDF/A-1 (ISO 19005-1)
• PDF/A-2 (ISO 19005-2)
• PDF/A-3 (ISO 19005-3)

Within the PDF/A standards, the following conformance levels are supported:

• B (Basic)
• U (Unicode, only PDF/A-2 and PDF/A-3)
• A (Accessibility)

tip

For more information about supported PDF/A standards, see our PDF/A overview.

Steps to convert a document:

1. Create a Conformance object.
2. Create a Validator object.
3. Run the Analyze method.
4. Create a Converter object.
5. Run the Convert method.

---

Before you begin

You need to initialize the library.

Creating a Conformance object

The document conversion process begins with the creation of a Conformance object. The Conformance object defines the PDF/A standard and level to which the output document must conform.

This example uses the PDF/A-2 standard (2), with conformance level B (Conformance.PdfALevel.B).

.NET

// Create a conformance object that specifies the PDF/A standard and level against which the output document must comply.

Conformance conformance = new Conformance(2, Conformance.PdfALevel.B);

Java

Creating a Validator object

The Validator object analyzes the conformance of the input PDF document with the PDF/A standard and level defined in the Conformance object.

This step is similar to the first step of the PDF/A validation process. However, during the PDF/A conversion process, additional information is also generated about the potential conformance level of the document.

.NET

// Create the Validator object, and use the Conformance object to create an AnalysisOptions object that controls the behavior of the Validator.

Validator validator = new Validator();
AnalysisOptions analysisOptions = new AnalysisOptions() { Conformance = conformance };

Java

Running the Analyze method

In addition to evaluating the document's conformance with the defined PDF/A standard and level, the Analyze method also provides a recommendation on whether the input document should be converted to PDF/A.

The Analyze method recommends conversion in the following cases:

• If IsConforming is false, i.e., if the document does not conform to the required Conformance.
• If the document is conforming, but there are other issues where conversion is highly recommended. For example, if corner-cases of the PDF/A specification that are known to cause problems for PDF viewers are detected.

When conversion is recommended, the recommended output PDF/A standard and level is provided in the RecommendedConformance value of the AnalysisResult object. This RecommendedConformance is the highest possible PDF/A level to which the document can conform. Setting a higher level for the conversion typically results in a conformance exception.

Even if the RecommendedConformance is higher than the Conformance passed to the AnalysisOptions, you do not need to increase the level of the Conformance passed to the ConversionOptions, because this level is automatically updated to the highest achievable level. Therefore, you can always set the Conformance provided in the AnalysisOptions to the lowest acceptable level.

.NET

// Run the analysis, and check the results. Only proceed if conversion is recommended.

AnalysisResult analysisResult = validator.Analyze(inDoc, analysisOptions);
if (!analysisResult.IsConversionRecommended) {
    return; // No conversion is required.
}

Java

Creating a Converter object

The Converter object converts the input PDF document into an output document that conforms to the defined PDF/A standard and level.

When the Converter makes changes to the document during the conversion process, it emits ConversionEvent events that provide detailed information about the type of change and where the change has been made in the output PDF/A document.

Even if the output document meets all required standards, the conversion may have resulted in differences that are acceptable in some processes, but not in others. Because of this, a handler function should listen to the ConversionEvent events and execute business logic based on the information contained in them.

Each ConversionEvent has a Severity that indicates the following types of changes were made to the output document:

1. Information: Changes were made, but the change had no visible impact on the document.
2. Warning: Changes were made that may have visible impacts. Check the output file to decide if the result is acceptable.
3. Error: Changes were not successful. The document could not be converted to the desired conformance level.

.NET

// Create a converter object to convert the non-conforming document to the recommended conformance.
Converter converter = new Converter();

// Add a handler for the ConversionEvent that writes changes made during the conversion process to the console.
// Note that exceptions cannot be thrown from inside the event handler.
converter.ConversionEvent += (s, e) => Console.WriteLine("- {0}: {1}: {2} ({3}{4})", e.Severity, e.Category, e.Message, e.Context, e.PageNo > 0 ? " " + e.PageNo : "");

Java

Running the Convert method

After generating the AnalysisResult and creating the Converter objects, the final step is to call the Convert method.

By default, the Converter object attempts to convert the input PDF document to the PDF/A standard and level defined in the RecommendedConformance value in the AnalysisResult. It is possible to override this behavior and force conversion to a different PDF/A standard and level. You can force conversion by passing an optional ConversionOptions parameter to the Convert method. When ConversionOptions are passed to the Convert method but the required conformance level cannot be achieved, conversion aborts with a ConformanceException.

.NET

// Create a stream for the output PDF/A file.
using var outStr = File.Create(outPath);

// Convert the input document to the recommended conformance level using the converter object.
using var outDoc = converter.Convert(analysisResult, inDoc, outStr);
Console.WriteLine($"Converted document to {outDoc.Conformance}.");

Java

Here's an example of the output that is generated by this sample code:

- Information: ManagedColors: Created calibrated color space substitute for DeviceRGB. (content of page 1)
Converted document to PDF/A-2u.

Full example

.NET

// Open the PDF document to convert.
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);

// Create a Conformance object that specifies the PDF/A level against which the document is to be validated prior to conversion. Here, PDF/A-2b is specified.
Conformance conformance = new Conformance(2, Conformance.PdfALevel.B)

// Analyze the PDF/A conformance of the document against level PDF/A-2b.
Validator validator = new Validator();
AnalysisOptions analysisOptions = new AnalysisOptions() { Conformance = conformance };
AnalysisResult analysisResult = validator.Analyze(inDoc, analysisOptions);

// Check the results of the analysis, and do not proceed unless conversion is recommended.
if (!analysisResult.IsConversionRecommended) {
    return; // No conversion is required.
}

// Create a converter object to convert the non-conforming document to the recommended conformance.
Converter converter = new Converter();

// Add a handler that writes changes made during the conversion process to the console.
converter.ConversionEvent += (s, e) => Console.WriteLine("- {0}: {1}: {2} ({3}{4})", e.Severity, e.Category, e.Message, e.Context, e.PageNo > 0 ? " " + e.PageNo : "");

// Create a stream for output file.
using var outStr = File.Create(outPath);

// Convert the input document to the recommended conformance level using the converter object.
using var outDoc = converter.Convert(analysisResult, inDoc, outStr);

Java