Checkpoint 20: Optional Content

PDF documents with Optional Content Groups (commonly called layers) must have proper configuration. Each layer must have a meaningful name, and the document must not use automatic state (AS) keys that could hide content based on viewer conditions.

What This Means

Optional Content Groups (OCGs) are a PDF feature that allows different "layers" of content that can be shown or hidden. Common uses include:

• CAD drawings: Different layers for electrical, plumbing, structural elements
• Maps: Layers for roads, buildings, terrain, labels
• Multi-language documents: Different layers for each language version
• Print vs. screen versions: Different content for different output media
• Version comparisons: Show/hide tracked changes

Each OCG has a configuration that includes:

1. Name entry: A human-readable identifier for the layer
2. Default state: Whether the layer is visible by default
3. Intent: Purpose of the layer (View or Design)
4. AS (Auto-State) keys: Automatic visibility rules based on conditions

For accessibility, PDFs must:

• Provide meaningful names for all optional content configurations
• Avoid AS keys that could automatically hide content without user control
• Ensure users can understand and control layer visibility

Why It Matters

Optional content affects accessibility in several ways:

Layer names enable understanding:

• Screen reader users need to know what layers exist and what they contain
• Meaningful names help users decide which content to display
• Generic or missing names make layer management impossible for assistive technology users

Auto-state keys can hide content:

• AS keys automatically show/hide content based on conditions like zoom level or viewer type
• If accessible content is automatically hidden, users cannot access it
• Users should have control over what content is visible
• Automatic hiding based on viewer conditions may affect assistive technology differently

Content visibility affects navigation:

• Hidden layers are typically not included in the tag structure read by screen readers
• If important content is in a hidden layer, it becomes inaccessible
• Layer management should be transparent and user-controllable

Consider a technical drawing with safety warnings on a separate layer. If that layer is automatically hidden based on zoom level (via AS key), users zoomed out may miss critical safety information.

Common Violations

The Matterhorn Protocol defines three failure conditions for optional content. All are machine testable.

20-001: Name Entry Missing or Empty in Optional Content Configuration Dictionary (Machine Testable)

What's Wrong: An Optional Content Configuration Dictionary exists but lacks a Name entry, or the Name entry is empty. Without a name, users cannot identify what the configuration represents.

How to Identify:

• PDF/UA validators automatically detect this
• In Acrobat, go to View > Show/Hide > Navigation Panes > Layers
• Look for layers with blank or missing names
• Check if any configurations are unnamed

Technical Context: The Optional Content Configuration Dictionary should include:

<< /Name (Configuration Name)
   /BaseState /ON
   /Order [...]
   ...
>>

When the Name key is missing or empty, the configuration cannot be identified.

20-002: Name Entry Missing or Empty in Default Optional Content Configuration Dictionary (Machine Testable)

What's Wrong: The default Optional Content Configuration (the one used when the document opens) lacks a proper Name entry. This is more critical than 20-001 because it affects the initial document state.

How to Identify:

• PDF/UA validators flag this specifically
• The default configuration is referenced from the document catalog
• Check the Layers panel for the default/initial layer configuration
• Validators distinguish between default and non-default configurations

Technical Context: The default configuration is specified in the OCProperties dictionary in the document catalog:

/OCProperties <<
  /D << /Name (Default Configuration) ... >>  % Default configuration
  /Configs [...]  % Additional configurations
>>

The /D entry (default configuration) must have a valid Name.

20-003: The AS Key Appears in an Optional Content Configuration Dictionary (Machine Testable)

What's Wrong: An Optional Content Configuration Dictionary contains an AS (Auto-State) key. This key defines automatic visibility rules that change layer visibility based on conditions, which can unexpectedly hide accessible content.

How to Identify:

• PDF/UA validators detect AS keys automatically
• These keys are not visible through the normal Acrobat interface
• Requires examining PDF structure or using validation tools

Technical Context: The AS key defines automatic state changes:

<< /Name (Print Configuration)
   /AS [<<
     /Event /Print
     /Category [/Print]
     /OCGs [...]
   >>]
>>

This example would automatically change layer visibility when printing, which could hide content in printed output without user awareness.

Why AS Keys Are Prohibited:

• Users lose control over content visibility
• Automatic hiding may affect accessibility features
• Content may be visible on screen but hidden when printed (or vice versa)
• Assistive technology may not detect automatically hidden content
• Creates unpredictable behavior for users

How to Fix in Adobe Acrobat

Adobe Acrobat Pro provides tools for managing optional content, though some fixes require advanced editing.

Viewing Existing Layers

1. Open your PDF in Adobe Acrobat Pro
2. Go to View > Show/Hide > Navigation Panes > Layers
3. The Layers panel shows all Optional Content Groups
4. Click the options menu (gear icon) for layer settings

Renaming Layers

1. Open the Layers panel
2. Right-click on a layer with missing or poor name
3. Select Properties
4. In the Layer Properties dialog:
   • Enter a meaningful Name
   • Set appropriate visibility defaults
5. Click OK

Checking Layer Configurations

1. In the Layers panel, click the options menu
2. Look for configuration options
3. Check if multiple configurations exist
4. Ensure each configuration has a name

Removing AS Keys (Advanced)

AS keys cannot be removed through the standard Acrobat interface:

1. Use Preflight to detect AS keys
2. If found, options include:
   • Export to PostScript and re-distill (may lose AS keys)
   • Use a PDF editing library (programming required)
   • Recreate the document without AS configurations
   • Use specialized PDF remediation tools

Flattening Layers

If optional content is causing issues:

1. Go to View > Show/Hide > Navigation Panes > Layers
2. Make all required content visible
3. Go to Tools > Print Production > Flattener Preview
4. Or use File > Save As Other > Optimized PDF
5. In the PDF Optimizer, look for options to flatten layers
6. This merges all visible content into a single layer

Caution: Flattening removes the layer functionality entirely. Only do this if layers are not essential to the document's purpose.

Using Preflight for Diagnostics

1. Go to Tools > Print Production > Preflight
2. Search for "optional content" or "OCG" profiles
3. Run a check to identify issues
4. Review results for name and AS key problems
5. Some fixups may be available for simple issues

How to Fix in Source Applications

Adobe InDesign

InDesign creates layer-based PDFs from its native layers:

1. Review your InDesign layers panel
2. Ensure all layers have meaningful names
3. When exporting to PDF:
   • Go to File > Export > Adobe PDF
   • In the General tab, check "Create Acrobat Layers"
   • Only enable if layers are needed for the document's purpose
4. Layer names from InDesign transfer to the PDF

Adobe Illustrator

1. Name all layers meaningfully in Illustrator
2. When saving as PDF:
   • Choose File > Save As > PDF
   • In the options, configure layer handling
3. Consider whether layers are necessary in the PDF
4. For accessibility, simpler is often better

CAD Applications

For CAD software exporting to PDF:

1. Review layer names in the CAD application
2. Ensure all layers have descriptive names
3. Check export settings for layer naming options
4. Test the exported PDF for proper configuration
5. Avoid automatic visibility settings that create AS keys

Avoid Creating AS Keys

When creating PDFs with layers:

1. Do not use "auto-visibility" or condition-based layer features
2. Set layers to be visible or hidden statically
3. Let users control visibility through the Layers panel
4. Avoid print-specific or zoom-specific layer configurations

Testing Your Fix

Automated Testing

PAC (PDF Accessibility Checker):

1. Open the PDF in PAC
2. Run the PDF/UA check
3. Navigate to Checkpoint 20 results
4. All three failure conditions are machine testable
5. PAC will identify specific issues with names and AS keys

veraPDF:

1. Select PDF/UA-1 validation profile
2. Run validation
3. Look for optional content-related rule failures
4. Review specific failures for name and AS key issues

Adobe Acrobat Preflight:

1. Go to Tools > Print Production > Preflight
2. Run a PDF/UA profile
3. Check for optional content violations
4. Review detailed results

Manual Verification

1. Open the Layers panel in Acrobat
2. Verify all layers have meaningful names
3. Check that names describe the layer content
4. Test layer visibility toggle to ensure all content is accessible

Screen Reader Testing

1. With all layers visible, test with a screen reader
2. Toggle layers off and on
3. Verify screen reader detects content changes appropriately
4. Ensure important content is not in optional layers that may be hidden

Validation Checklist

• All Optional Content Configuration Dictionaries have Name entries
• No Name entries are empty strings
• Default configuration has a meaningful name
• No AS (Auto-State) keys are present
• Layer names are descriptive and meaningful
• All important content is visible in default state
• Layer visibility can be controlled by users
• Screen reader can access content when layers are visible

Best Practices for Optional Content

When to Use Layers

Use optional content layers when:

• Technical drawings require showing/hiding different systems
• Multi-language content needs to be switchable
• Complex documents benefit from progressive disclosure
• Users need to customize their view of the document

When to Avoid Layers

Consider avoiding layers when:

• The document is primarily text-based
• Layers would create accessibility complexity
• Content should always be visible to all users
• The layer functionality serves only the author, not the reader

Naming Conventions

Good layer names:

• Describe the content (e.g., "Electrical Systems", "Spanish Text")
• Are consistent across similar documents
• Are concise but informative
• Avoid technical jargon when possible

Poor layer names:

• "Layer 1", "Layer 2" (non-descriptive)
• "" (empty)
• "Temp" or "New Layer" (placeholder names)
• Extremely long names that truncate in viewers

Default Visibility

• Set the most important content to be visible by default
• Consider what content is essential for all users
• Test the default view for accessibility
• Document which layers contain what content

Additional Resources

Official Standards and Guidelines

• W3C WCAG 2.1 Success Criterion 1.3.1: Info and Relationships
• PDF Association Matterhorn Protocol 1.02
• ISO 32000-2: Optional Content

PDF Technical Resources

• PDF Reference: Optional Content Groups
• PDF/UA Technical Implementation Guide
• Adobe: Working with Layers in Acrobat

Tools

• PAC (PDF Accessibility Checker) - Free PDF/UA validation
• veraPDF - Open-source PDF validator
• Adobe Acrobat Pro - Layer management tools

This documentation is based on the Matterhorn Protocol 1.02, the definitive reference for PDF/UA validation. All three failure conditions for optional content are machine testable. For the most current information, consult the PDF Association and W3C WCAG guidelines.