Matterhorn 20-001 · PDF/UA-1 UA1:7.10-1
Unnamed alternate layer configuration in a PDF
Optional content (layer) configurations must be nameable so a user can identify and toggle them.
The condition, as the protocol states it. “Name entry is missing or has an empty string as its value in an Optional Content Configuration Dictionary in the Configs entry in the OCProperties entry in the Catalog dictionary.”
Matterhorn Protocol 1.1, checkpoint 20, index 20-001, section UA1:7.10-1. Software can decide this one on its own.
What a screen reader actually does
The layers panel presents unnamed entries the user cannot meaningfully choose between.
What a configuration is
Layers in a PDF are optional content groups. Whether each one is on when the file opens is not stored on the layer. It is stored in a separate dictionary, a configuration, and the catalog’s /OCProperties holds up to three things:
/OCProperties <<
/OCGs [ 12 0 R 13 0 R 14 0 R ] % every layer in the file
/D << /Name (Plan view) % the default configuration
/Order [ 12 0 R 13 0 R 14 0 R ]
/OFF [ 14 0 R ] >>
/Configs [ % alternates, optional
<< /Name (Print set) /OFF [ 13 0 R ] >>
<< /OFF [ 12 0 R ] >> % no /Name: condition 20-001
]
>>The default configuration, /D, is applied when the document opens. The ones in /Configs are alternatives: a different combination of layers on and off, a different order in the layer list, perhaps some layers locked. A drawing might carry one preset for the plan, one for the services overlay and one for print.
ISO 32000-1 makes /Name optional in all of them and describes it as a name fit to show in a user interface. PDF/UA-1, clause 7.10, makes it compulsory. This page is the alternates; the default is 20-002.
The condition is a dictionary in /Configs with no /Name, or with an empty one. Taggart also treats a name made of nothing but spaces as empty, because it reads the same.
What breaks, and for whom
The name has one job: to be the label a viewer shows when it offers the presets as a choice. Where a viewer does that, an unnamed configuration is an entry in a list with nothing in it, or a placeholder the viewer made up, and a screen-reader user moving through the list hears no more than that. Two unnamed presets cannot be told apart at all.
Many people will never meet the list. Adobe’s documentation of Acrobat’s Layers panel covers showing and hiding layers, their properties, reordering, merging and flattening (PDF layers overview), and says nothing about switching configurations. That makes this one of the quieter conditions in the protocol. It is still decided by software, so it is still a blocker: a file that fails it cannot claim PDF/UA-1, however rarely its presets are shown.
Where it comes from
Adobe names InDesign, AutoCAD and Visio as typical sources of layered PDFs. Alternate configurations are much rarer than layers, since a producer only writes them when it has more than one preset view to offer. Because ISO 32000 never required the name, a producer that is not aiming at PDF/UA has no reason to write one.
How to check it free
Acrobat Pro will tell you whether the file has layers at all (Menu → View → Show/Hide → Side panels → Layers), but it does not display configurations, so it cannot show you this condition.
qpdf can. Rewrite the file in its readable QDF form and open the result in a text editor:
qpdf --qdf --object-streams=disable drawing.pdf readable.pdfFind /OCProperties in the catalog, follow it to /Configs, and look for a /Name in each dictionary of the array.
veraPDF reports the failure against clause 7.10 when validating PDF/UA-1. Its test is that the name exists and is not empty, so it accepts a name made only of spaces, which Taggart does not.
How to fix it free
If the published copy does not need layers, flatten them. In Acrobat Pro: Layers panel → Options → Flatten Layers. Adobe is plain about what that does: it removes all layer structure, keeps only what was visible, and permanently discards hidden layer content, with no undo (Merge and flatten layers). Turn on the layers the reader needs first, and work on a copy. Adobe’s page does not say what flattening does to the tags, so open the Tags panel afterwards and look.
If the layers are worth keeping, name the configuration by hand. It is one key. In the QDF file from above, add /Name (Services overlay) inside the unnamed dictionary, then repair the cross-reference offsets the edit moved and write a normal file again:
fix-qdf readable.pdf > named.pdf
qpdf named.pdf drawing-fixed.pdffix-qdf ships with qpdf. Name the preset for what it shows, because that string is the whole of what a person choosing between presets is told.
Or re-export from the source with layers on, and check the new file with veraPDF or Taggart. Whether a given application names its alternates is not something its export dialog will tell you.
What Taggart does
The check walks /OCProperties /Configs and reports each dictionary whose /Name is missing, empty or only spaces, by its position in the array:
Optional content configuration 0 in /OCProperties /Configs has a missing or empty /Name entry.
The repair is optional-content-names, marked safe, so Fix All Safe applies it. It writes Layer configuration Configs[0] (and Configs[1], Configs[2] for any further unnamed ones), names an unnamed default configuration in the same pass (20-002), and removes any /AS entry it finds (20-003). Nothing else in the configuration changes: the on and off lists, the order and the locks stay as they were.
The name is accurate and generic. Taggart has no way to take a better one from you. If the presets are meant to be chosen by people, the descriptive name has to come from the source or from the hand edit above.
How Taggart handles it
Taggart checks for this condition automatically and reports it as a blocker, with where in the file it found it.
The fix is Name optional content configurations. It is mechanical, so “Fix All Safe” applies it along with the others in one pass and lists what it changed. Your original file is never modified.
Whatever Taggart changes, the page still looks identical. Fixes edit the PDF object model, not the content streams, and every remediation is re-rendered and compared against the original at structural similarity ≥ 0.999 before you get the file back. A tool that quietly reflows your document is worse than no tool.
Frequently asked questions
Is this about a layer with no name?
No. Each layer (an optional content group) has its own /Name, and ISO 32000 already requires that one. This condition is about a configuration: a preset that says which layers are on, which are off, and how the layer list is ordered. PDF/UA-1 asks for those to be named too.
Does anyone actually see these names?
Only in a viewer that offers the alternate configurations as a choice. Adobe's documentation for Acrobat's Layers panel describes showing, hiding, renaming, merging and flattening layers, and nothing about switching configurations. The condition is machine-checkable all the same, so it blocks a PDF/UA claim whether or not a viewer ever displays the name.
Will flattening the layers fix it?
Yes, by removing the thing that needs a name. Adobe says Flatten Layers removes all layer structure from the PDF and permanently discards the content of hidden layers, so decide what should be visible before you do it, and keep a copy.
What name does Taggart write?
"Layer configuration Configs[0]", "Layer configuration Configs[1]" and so on, by position. It is accurate and unique, and it does not describe anything. If people are meant to choose between the presets, give them names that say what each one is for.
Where this sits in the standards
| Standard | Reference |
|---|---|
| Matterhorn Protocol 1.1 | Checkpoint 20 (Optional Content), index 20-001 |
| PDF/UA-1 (ISO 14289-1) | Clause 7.10-1 |
| WCAG 2.1 | 1.3.1 Info and Relationships — Level A |
| EN 301 549 / Section 508 / ADA Title II | All three point at WCAG 2.1 Level AA for non-web documents, so a Level A or AA criterion here is in scope for each of them. |
Related conditions
- 20-002 Name missing or empty in the default Optional Content Configuration DictionaryThe default optional-content configuration has no name.
- 20-003 An AS entry appears in an Optional Content Configuration DictionaryAutomatic state (usage application) entries let content appear or disappear based on zoom or print state, which can hide content from a reader unpredictably. PDF/UA-1 forbids them.
Other conditions in checkpoint 20
Checkpoint 20 covers optional content. These are its other failure conditions; the ones without a link are in the rule set but do not have a written page yet.
- 20-002 Name missing or empty in the default Optional Content Configuration DictionaryThe default optional-content configuration has no name.
- 20-003 An AS entry appears in an Optional Content Configuration DictionaryAutomatic state (usage application) entries let content appear or disappear based on zoom or print state, which can hide content from a reader unpredictably. PDF/UA-1 forbids them.
Check your own file. Taggart’s validator is free and unlimited — 75 of the 87 Matterhorn conditions software can decide, with the other 12 listed for you to confirm; no watermark, no expiry, and no account needed up to 60 pages.
Checked with Taggart on a generated file that fails this condition on . The Acrobat steps follow Adobe’s documentation and were not walked through by hand. Last updated .