Checkpoint 21: Embedded Files

When PDFs contain embedded files (attachments), each file must have a proper file specification dictionary that includes both the F (file name) and UF (Unicode file name) keys. This ensures assistive technology can identify and describe embedded files to users.

What This Means

PDFs can contain embedded files as attachments. Common embedded file types include:

• Source documents: Original Word, Excel, or other files
• Supporting data: Spreadsheets, databases, or datasets
• Additional resources: Related documents or references
• Multimedia: Audio or video files
• Archives: ZIP files or other compressed archives

Each embedded file requires a file specification dictionary that describes the file. This dictionary must contain:

1. F key: The file name in a basic encoding (typically PDFDocEncoding or ASCII)
2. UF key: The file name in Unicode (UTF-16BE), supporting international characters

Both keys are required because:

• The F key provides backward compatibility with older PDF readers
• The UF key ensures correct display of file names containing non-ASCII characters (accented letters, Asian characters, symbols)
• Assistive technology uses these keys to announce the file name to users

Why It Matters

Proper file specification affects how users with assistive technology interact with embedded files:

File identification:

• Screen readers announce file names when users encounter attachments
• Without proper naming, users cannot know what files are embedded
• Missing or incorrect names prevent informed decisions about opening attachments

International character support:

• The UF key ensures file names display correctly regardless of language
• Without Unicode support, file names like "Rapport_financier_2024.xlsx" or "レポート.pdf" may display incorrectly
• Users may not recognize garbled file names

Link text equivalents:

• When embedded files are linked from document text, the file name often serves as or supplements the link text
• WCAG 2.4.4 (Link Purpose) requires that link purpose be determinable
• Proper file names help satisfy this requirement

Security awareness:

• Users need to see file names to make informed decisions about opening attachments
• Hidden or unclear file names could mask malicious content
• Accessibility supports security through transparency

Consider a user navigating a PDF with a screen reader. When they encounter an attachment:

Common Violations

The Matterhorn Protocol defines one failure condition for embedded files, which is machine testable.

21-001: File Specification Dictionary Missing F and UF Keys (Machine Testable)

What's Wrong: An embedded file's specification dictionary is missing either the F key, the UF key, or both. This prevents proper identification of the embedded file.

How to Identify:

• PDF/UA validators automatically detect missing F or UF keys
• In Acrobat, go to View > Show/Hide > Navigation Panes > Attachments
• If attachments show blank names or garbled characters, keys may be missing
• Validation tools will specify which key is missing

Technical Context: A proper file specification dictionary looks like:

<< /Type /Filespec
   /F (filename.pdf)
   /UF <FEFF0066006900...>  % Unicode UTF-16BE encoded filename
   /EF << /F (embedded stream reference) >>
   /Desc (File description)
>>

Common issues include:

• F key present, UF missing: File names with special characters may not display correctly
• UF key present, F missing: Older PDF readers may not show the name
• Both missing: File cannot be identified at all
• Empty values: Keys exist but contain no data

Why Both Keys Are Required:

• PDF/UA requires both for maximum compatibility
• F key: Works with older readers, uses restricted character set
• UF key: Supports full Unicode, required for international file names
• Together, they ensure all users can identify attachments regardless of reader or language

How to Fix in Adobe Acrobat

Adobe Acrobat provides tools for managing embedded files, though fixing file specification issues may require workarounds.

Viewing Embedded Files

1. Open your PDF in Adobe Acrobat Pro
2. Go to View > Show/Hide > Navigation Panes > Attachments
3. The Attachments panel shows all embedded files
4. Note any files with missing or incorrect names

Re-embedding Files with Proper Names

If file specifications are missing, re-embedding often fixes the issue:

1. In the Attachments panel, note the problematic file
2. If possible, save the attached file locally:
   • Right-click the attachment
   • Select Save Attachment
   • Save to a local folder
3. Delete the problematic attachment:
   • Right-click the attachment
   • Select Delete
4. Re-add the file with a proper name:
   • Click the Add Attachment button (paperclip icon)
   • Navigate to and select the saved file
   • Ensure the file has a proper, descriptive name before attaching

Checking File Properties

1. In the Attachments panel, right-click an attachment
2. Select Properties or Description (option varies by version)
3. Review the file name and description
4. Edit the description to add meaningful information

Adding Attachment Descriptions

While not a direct fix for F/UF keys, descriptions help:

1. Right-click an attachment
2. Select Edit Description
3. Add a clear description of the file's contents
4. This provides additional context for screen reader users

Using Preflight for Diagnostics

1. Go to Tools > Print Production > Preflight
2. Search for "embedded file" or "file specification" profiles
3. Run the check to identify missing keys
4. Review results for specific failures
5. Preflight may offer fixups for some issues

Advanced: Editing File Specifications

For technical users with PDF editing knowledge:

1. Some third-party tools allow direct dictionary editing
2. You can add missing F or UF keys manually
3. This requires understanding PDF structure and encoding
4. Tools like QPDF or iText can be used programmatically

How to Fix in Source Applications

Preventing file specification issues starts with how attachments are created.

Adobe InDesign

When embedding files in InDesign publications:

1. Use File > Place or the Links panel to add files
2. Ensure source files have proper, descriptive names before embedding
3. Avoid special characters in file names that may not encode properly
4. When exporting to PDF:
   • Check that embedded files are included
   • Test the resulting PDF for proper file specifications

Microsoft Word

Word can include embedded objects:

1. Use Insert > Object to embed files
2. Ensure the source file has a clear name
3. When saving as PDF:
   • Embedded objects may or may not transfer
   • Test the PDF to verify attachments
4. For true file attachments, consider using Acrobat after Word export

Adding Attachments via Script or Automation

When programmatically creating PDFs with attachments:

1. Always specify both F and UF parameters
2. Encode the UF value as UTF-16BE (big-endian Unicode)
3. Use the same file name in both F and UF (with appropriate encoding)
4. Include a description for accessibility

Example using a PDF library (conceptual):

// Pseudocode for proper attachment
pdf.attachFile({
  path: '/path/to/file.pdf',
  name: 'Annual_Report_2024.pdf',        // F key
  unicodeName: 'Annual_Report_2024.pdf', // UF key (auto-encoded)
  description: 'Complete annual report with financial details'
});

File Naming Best Practices

Before embedding files:

1. Use descriptive names: "Q4_Financial_Summary.xlsx" not "doc1.xlsx"
2. Avoid special characters: Stick to alphanumeric, underscore, hyphen
3. Include file type context: Name should hint at content type
4. Keep names reasonable length: Long enough to be clear, short enough to display
5. Use ASCII-compatible characters when possible: Reduces encoding complexity

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 21 results
4. PAC will report missing F or UF keys
5. The violation is machine testable with specific results

veraPDF:

1. Select PDF/UA-1 validation profile
2. Run validation
3. Look for file specification rule failures
4. Results will identify which files have issues

Adobe Acrobat Preflight:

1. Go to Tools > Print Production > Preflight
2. Run a PDF/UA compliance check
3. Review results for embedded file issues
4. Check for specific file specification failures

Manual Verification

1. Open the Attachments panel in Acrobat
2. Review each attachment name:
   • Names should be visible and readable
   • No blank entries or garbled characters
   • Names should describe the file content
3. Try to open each attachment to verify it's accessible

Screen Reader Testing

1. Open the PDF with a screen reader (NVDA, JAWS, VoiceOver)
2. Navigate to the attachments area
3. Verify the screen reader announces:
   • That attachments exist
   • The name of each attachment
   • Any available descriptions
4. Confirm users can access and open attachments

International Character Testing

If file names include non-ASCII characters:

1. Embed a file with international characters in the name
2. Open the PDF in different readers (Acrobat, browser, Preview)
3. Verify the name displays correctly in all viewers
4. Test with a screen reader to ensure proper pronunciation/spelling

Validation Checklist

• All embedded files have F key present
• All embedded files have UF key present
• F and UF values are not empty
• File names are descriptive and meaningful
• File names display correctly (no garbled characters)
• Attachments panel shows proper names
• Screen reader announces file names correctly
• File descriptions are provided where helpful
• Users can access and open attachments

Common Scenarios and Solutions

Scenario 1: File Names with Accented Characters

Problem: File name "Présentation_été.pdf" displays incorrectly.

Solution:

1. The UF key must be present for proper Unicode display
2. Re-embed the file ensuring the PDF tool supports Unicode
3. Alternatively, rename to ASCII-compatible: "Presentation_ete.pdf"

Scenario 2: Attachment from Legacy PDF

Problem: Old PDF has attachments without proper specification.

Solution:

1. Save existing attachments locally
2. Delete from the PDF
3. Re-attach using modern Acrobat
4. Verify F and UF keys are now present

Scenario 3: Programmatically Generated PDFs

Problem: PDF library doesn't add UF key by default.

Solution:

1. Check library documentation for Unicode file name options
2. Explicitly set both F and UF parameters
3. If library doesn't support UF, consider post-processing with another tool
4. File a feature request with library maintainers

Scenario 4: Multiple Languages in Attachment Names

Problem: Document has attachments in multiple languages.

Solution:

1. Ensure UF key is present for all (required for non-ASCII)
2. F key can use ASCII approximation if needed
3. Add descriptions in the document's primary language
4. Test with appropriate language screen reader settings

Additional Resources

Official Standards and Guidelines

• W3C WCAG 2.1 Success Criterion 1.1.1: Non-text Content
• W3C WCAG 2.1 Success Criterion 2.4.4: Link Purpose (In Context)
• PDF Association Matterhorn Protocol 1.02

PDF Technical Resources

• PDF Reference: File Specification Dictionaries
• ISO 32000-2 (PDF 2.0) Standard
• PDF/UA Technical Implementation Guide

Tools

• PAC (PDF Accessibility Checker) - Free PDF/UA validation
• veraPDF - Open-source PDF validator
• Adobe Acrobat Pro - Attachment management
• QPDF - Command-line PDF manipulation

This documentation is based on the Matterhorn Protocol 1.02, the definitive reference for PDF/UA validation. The embedded files checkpoint has one machine-testable failure condition. For the most current information, consult the PDF Association and W3C WCAG guidelines.