PDF Optional Content Group (OCG)
A PDF Optional Content Group (OCG) is a named object that controls the visibility of associated page content. When an OCG is toggled off, the content stream regions marked as belonging to that group are not rendered. OCGs are the mechanism behind PDF layers — used in engineering drawings, multi-language documents, and print production overlays.
A PDF Optional Content Group (OCG) is a named object that controls the visibility of associated page content. Content stream regions marked as belonging to an OCG are rendered or hidden based on the OCG's current state (on or off). OCGs are the mechanism behind PDF layers — the feature that lets users show or hide different parts of a document independently.
OCGs are defined in ISO 32000 as part of the Optional Content model, introduced in PDF 1.5. They are stored in the document catalogue's <code>/OCProperties</code> dictionary and referenced from page content via <a href="https://pdftheguide.com/glossary/pdf-marked-content" target="_blank" rel="noopener">marked content</a> operators with the <code>/OC</code> tag.
OCG structure and the /OCProperties dictionary
Each OCG in a PDF is an indirect dictionary object with:
<strong><code>/Type /OCG</code></strong> — Identifies the object as an Optional Content Group. <strong><code>/Name</code></strong> — A human-readable string displayed in the Layers panel (e.g., "English text", "Electrical plan", "Watermark"). <strong><code>/Intent</code></strong> — Optional. Specifies the purpose of the OCG: <code>/View</code> (screen display), <code>/Design</code> (creation/design tools), or an array of both. <strong><code>/Usage</code></strong> — Optional. A dictionary specifying context-specific visibility rules: <code>/Print</code> (visibility when printing), <code>/View</code> (visibility on screen), <code>/Export</code> (visibility on export), and others. Usage entries can independently control whether an OCG is on for screen vs. on for print. <strong><code>/Creator</code></strong> — Optional. The application that created the OCG (informational).
All OCGs in a document are registered in the <strong><code>/OCProperties</code></strong> dictionary in the document catalogue:
<code>/OCGs</code> — An array of all OCG indirect references in the document. <code>/D</code> — The default configuration dictionary, specifying: default ON/OFF states for each OCG (<code>/ON</code> array and <code>/OFF</code> array), the display order for the Layers panel (<code>/Order</code>), and the <code>/AS</code> (auto-state) array linking Usage entries to rendering contexts. <code>/Configs</code> — Optional additional configurations (alternative layer states for different use cases).
OCMD: Optional Content Group Membership Dictionaries
Where an OCG simply has an on/off state, an <strong>Optional Content Group Membership Dictionary (OCMD)</strong> expresses boolean combinations of OCG states. This allows content visibility to depend on multiple OCG states simultaneously.
An OCMD contains: <strong><code>/Type /OCMD</code></strong> — Identifies the object as a membership dictionary. <strong><code>/OCGs</code></strong> — A single OCG reference or an array of OCG references. <strong><code>/P</code></strong> — The policy for the array: <code>/AllOn</code> (visible when all OCGs are on), <code>/AnyOn</code> (visible when any OCG is on), <code>/AllOff</code> (visible when all OCGs are off), <code>/AnyOff</code> (visible when any OCG is off).
<strong>Practical use of OCMDs</strong>: - A "Print" OCG that controls print-only content, combined via OCMD with each language layer: print layer visible only when BOTH the print OCG AND the relevant language OCG are on. - Mutual exclusion: Show Layer-A when Layer-B is off (using AnyOff policy on Layer-B). - "Derived" layers: A layer visible only when two specific base layers are simultaneously on.
OCMDs are used in page content via the same <code>/OC</code> marked content mechanism as OCGs — the OCMD reference replaces the OCG reference in the <code>/Properties</code> resource dictionary.
PDF/A and PDF/UA constraints
<strong>PDF/A-1 prohibits all optional content</strong> — Documents conforming to PDF/A-1 (ISO 19005-1) must not contain OCGs, OCMDs, or any optional content structures. This is an absolute prohibition.
<strong>PDF/A-2 and PDF/A-3 permit OCGs with conditions</strong>: 1. The document must be fully meaningful with all OCGs in their default state as specified in the <code>/OCProperties /D</code> configuration. The default-state document must be a complete and comprehensible record — you cannot archive a PDF/A-2 document that is blank or missing essential content when OCGs are at their defaults. 2. OCG usage entries that could affect the default-state appearance in ways not reflected in the document's archival intent are problematic.
In practice, PDF/A-2 layered documents should be designed so that the default view (all layers at default visibility) represents the canonical document. Layers that toggle between display modes should have both states considered for the archival record.
<strong>PDF/UA and OCGs</strong> — The interaction of optional content with accessibility is complex. The PDF/UA specification and Matterhorn Protocol indicate that: - Content that is hidden (OCG off by default) should still be tagged in the structure tree if it is meaningful content. - Artifact-tagged content in an OCG (e.g., a decorative background on a view-only layer) can be in an off OCG without structure tree entries. - Screen readers may not have access to layer-toggling UI, so documents targeting PDF/UA should ensure the default-visible content provides a complete accessible experience.
Frequently asked questions
What is the difference between an OCG and an OCMD?
An OCG (Optional Content Group) is a named object with a simple on/off state. Content marked as belonging to an OCG is shown when the OCG is on and hidden when it is off. An OCMD (Optional Content Group Membership Dictionary) is a more complex object that expresses boolean logic across multiple OCGs — content belonging to an OCMD can be made visible based on combinations of OCG states (all on, any on, all off, any off). OCGs are the fundamental building block; OCMDs build conditional visibility logic from multiple OCGs. In the vast majority of PDF layer workflows, OCGs are sufficient. OCMDs are used for complex conditional visibility requirements such as "show this content only when the Print layer AND the English layer are both on."
Can I add or remove layers from a PDF programmatically?
Yes, with PDF libraries that support optional content: iText 7 (Java/C#), PDFlib, Apache PDFBox, and PyMuPDF all have OCG APIs. To add an OCG: (1) create an OCG dictionary with /Name; (2) add it to the /OCProperties /OCGs array in the document catalogue; (3) add it to the /D default configuration /ON or /OFF arrays; (4) add it to the /Properties resource dictionary on each page that has content belonging to it; (5) wrap the relevant content stream segments with /OC OCG BDC ... EMC marked content operators. Removing an OCG involves removing the OCG reference from /OCProperties, from page resource dictionaries, and removing the BDC/EMC wrappers from content streams. Content that was inside the removed OCG becomes unconditionally visible.
How do PDF viewer applications handle OCG default states?
PDF viewer applications read the /OCProperties /D /ON and /OFF arrays to determine the initial visibility of each OCG when the document is first opened. The /D configuration is the "default" view; additional configurations in /Configs provide alternative layer state sets. Viewers that implement the interactive Layers panel (Adobe Reader, Acrobat Pro) allow users to toggle OCG states after the document opens. Viewers without a Layers panel (most browser viewers, many mobile readers) render the document using the default OCG states from /D and provide no layer-toggling UI. When designing layered PDFs, the default state should represent the primary intended view — the one that users with non-interactive viewers will always see.