PDF/UA Accessibility Tagging and Validation

Section 508 is a U.S. law requiring digital documents to work with screen readers. REFRACT PDF tags each rendered PDF for PDF/UA (ISO 14289-1) - structured, with headings, alt text, and reading order - then checks the output, with a single template setting. Refract Logic does not certify conformance.

What Problem Does It Solve?

Without accessibility tags:

• Blind users can't read your PDFs with screen readers (NVDA, JAWS)
• PDFs look like unstructured blobs to accessibility software
• Your PDFs may not meet Section 508 requirements

With accessibility tags:

• Screen readers can read your PDFs naturally
• Headings, lists, and tables are properly structured
• REFRACT tags and checks your PDFs against Section 508 / PDF-UA requirements

How to Enable It

Simplest: Enable with Defaults

{
  "templateSettings": {
    "section508Accessibility": true
  }
}

Full Control: Configure Sub-Settings

{
  "templateSettings": {
    "section508Accessibility": {
      "enabled": true,
      "level": "pdf-ua",
      "mode": "full",
      "generateCertificate": false,
      "generateReport": false
    }
  }
}

Settings Reference

mode is a recognized settings field kept for backward compatibility, but it is not read by the render pipeline: setting it has no effect.

appendSummary and marginAnnotations have been removed. appendSummary appended a summary page, and marginAnnotations drew a compliance overlay in the document's margins; neither is drawn any more, and the Section 508 report carries the assessment. false is still accepted for compatibility, so existing templates load unchanged. true is refused: a render returns HTTP 400 with code SECTION508_SETTING_REFUSED, and template validation reports an error.

Note: section508Accessibility: true as a bare boolean is shorthand for enabled: true with all other settings at their defaults.

level - Validation Tier

"basic" (default)
Adds PDF structure tags required for Section 508 and WCAG 2.1 compliance. The engine inserts /MarkInfo, tags headings/tables/lists/images, and injects a language declaration from templateSettings.locale. Screen readers (NVDA, JAWS, VoiceOver) can navigate the document structure. Sufficient for most enterprise document workflows.

"pdf-ua"
Runs the full ISO 14289-1 (PDF/UA) validation pass. Adds everything in "basic" plus: heading hierarchy order, <TH> scope attributes on every table, alt text presence on every image, natural reading order enforcement, and font embedding verification. Documents that fail a validation rule are flagged in the audit trace. Required for government procurement, public sector, and documents subject to ADA litigation risk. This is the standard Adobe Acrobat's "Check for accessibility" tool tests against.

Use "pdf-ua" for regulated documents. Use "basic" for internal reports or when a lighter footprint is preferred.

generateCertificate and generateReport - Accessibility Certificate and Report

Neither flag produces a stored file at render time. What actually happens: the per-document PASS/WARNING/FAIL trace (see "PDF/UA: What Gets Validated" below) is written to a trace file, retrievable by correlationId or documentId. A separate, later authenticated API call - POST to the accessibility route, with type=certificate, type=report or type=zip and a body of { "correlationId": "..." } or { "documentId": "..." } - fetches that trace and builds the certificate or report PDF on demand, returning it directly in the HTTP response (inline or as an attachment, controlled by a disposition parameter). Nothing is written to SharePoint by this flow. Setting generateCertificate or generateReport does not produce a file at render time; it decides whether the later call may build one.

The trace is written whenever section508Accessibility is enabled, whatever these two flags say, and both flags are recorded in it. The on-demand call checks them: type=certificate is refused with HTTP 403 unless the trace has generateCertificate: true, and type=report unless it has generateReport: true. type=zip bundles whichever of the two are enabled together with the trace JSON, and is refused when neither is. A document rendered with a flag off has to be re-rendered with it on before that file can be built.

The certificate/report content includes the document ID, template name, render timestamp, accessibility level and the validation results. It is generated from the engine's own checks; it is not issued or verified by a third party.

Configuration Examples

Example 1: Simple Enable (Invoice)

{
  "templatePath": "Finance/Invoice.rpkg",
  "templateSettings": {
    "section508Accessibility": true,
    "locale": "en-US"
  }
}

Result: Accessibility tags

Example 2: Generate Certificate (For Auditors)

{
  "templatePath": "Compliance/ComplianceReport.rpkg",
  "templateSettings": {
    "section508Accessibility": {
      "enabled": true,
      "generateCertificate": true
    }
  }
}

Result: Accessibility tags + professional certificate PDF (on-demand)

Example 3: Full Audit Mode (Legal/Enterprise)

{
  "templatePath": "Legal/LegalAgreement.rpkg",
  "templateSettings": {
    "section508Accessibility": {
      "enabled": true,
      "mode": "full",
      "generateCertificate": true,
      "generateReport": true
    }
  }
}

Result: Accessibility tags + certificate + detailed report (both available on-demand)

Override Per-Document (API)

Enable/disable for specific documents via Dispatcher API:

// Enable with default settings
const response = await fetch('/api/render', {
  method: 'POST',
  body: JSON.stringify({
    templatePath: 'Invoice.rpkg',
    payloadPath: 'invoice-001.json',
    options: {
      features: {
        section508Accessibility: true
      }
    }
  })
});

// Or disable for a specific document
const response = await fetch('/api/render', {
  method: 'POST',
  body: JSON.stringify({
    templatePath: 'Invoice.rpkg',
    payloadPath: 'invoice-001.json',
    options: {
      features: {
        section508Accessibility: false
      }
    }
  })
});

What It Tags

Section 508 tagging recognizes and marks:

PDF/UA: What Gets Validated

PDF/UA (ISO 14289-1) is the international standard for universally accessible PDFs. It extends basic accessibility tagging with structural rules that screen readers, assistive technology, and compliance auditors rely on.

When section508Accessibility is enabled, the REFRACT Engine runs the following validations on every rendered document. Checks label the document; they do not block delivery:

Failures and warnings are written to the accessibility trace, retrievable later by correlationId or documentId. There is no summary page appended to the PDF: appendSummary has been removed (see the settings reference above).

Test It Works

Quick Test

1. Download your PDF
2. Open in Adobe Acrobat Reader
3. Go to Tools → Accessibility → Check Document
4. Should see: "✓ Tagged PDF"

With a Real Screen Reader

Free options to test:

• Windows: NVDA (https://www.nvaccess.org/) - Free, open-source
• Mac: VoiceOver (built-in - press Cmd+F5)
• Online Reader: Browse the PDF with NVDA/VoiceOver enabled

The PDF should read naturally without you seeing garbled text.

When Customers Need It

Required By Law

• U.S. Government: All government documents must be Section 508 compliant
• Public Universities: Many state laws require it
• Publicly Traded Companies: SEC requires accessible investor documents
• Government Contractors: Pre-requisite for doing business

Required By Contract

• Enterprise Customers: Many require Section 508 compliance in procurement
• Healthcare: HIPAA documents need to be accessible
• Finance: SOX-compliant docs often require Section 508 too

Good Practice

• Any Public Document: If humans might read it, accessibility helps everyone
• Internal Policies: Sets organizational compliance standard
• Batch Processing: Ensures consistency across document library

Common Questions

Q: Will it make my PDFs bigger or slower to render?
A: Tagging adds some size and render time, but no verified figure is available for how much - it depends on the document's structure. Measure it on your own templates if this matters to you.

Q: Does it require me to add alt-text?
A: REFRACT PDF automatically tags structure. Alt-text comes from your template data (describe images in your JSON payload).

Q: Can I enable it just for some PDFs?
A: Yes - set in template, or override per-document via API.

Q: What if my PDF generation fails?
A: REFRACT PDF tries to tag and continues if it fails (non-blocking).

Next Steps

1. ✅ Enable section508Accessibility: true in your template
2. ✅ Download a test PDF from the template
3. ✅ Verify with Adobe Acrobat Reader (Tools → Accessibility → Check)
4. ✅ Test with NVDA screen reader (free download)
5. ✅ Deploy to production

Done! Your PDFs are now accessible.

Performance

No render-time performance figures for tagging overhead, PDF size increase or license-check latency are documented here - none could be traced to a source in code, and earlier drafts of this page carried numbers that were never verifiable. If you need real numbers, measure them for your own templates and payloads.

Understanding the Output Files

What Gets Generated

There is no appended summary page or margin overlay (appendSummary and marginAnnotations have been removed; see the settings reference above), and no certificate or report file is written to SharePoint by any part of this flow. The only render-time output is the tagged PDF itself; the accessibility trace it produces is fetched later, by correlationId or documentId, to build a certificate/report/zip on request.

Premium Features in TemplateSettings

Three premium features can be configured in templateSettings:

Availability depends on your licence. A render that asks for section508Accessibility when the licence does not include it is refused before rendering: 403 FEATURE_NOT_LICENSED, with feature set to section508Accessibility (see Error codes). Without the licence, xmpMetadata and explainDocument are skipped and the render continues.

Enable multiple features together:

{
  "templateSettings": {
    "section508Accessibility": {
      "enabled": true,
      "generateCertificate": true
    },
    "xmpMetadata": true,
    "explainDocument": true
  }
}

Storage & File Organization

section508Accessibility does not write a certificate or report file to SharePoint at any point - there is no Reports/accessibility/ or AuditLogs/accessibility/ folder created by this feature. The only thing persisted from the accessibility check is the trace itself, kept so a later API call can look it up by correlationId or documentId to build a certificate, report or zip on request.

License Information

• Feature Name: section508Accessibility
• Availability depends on your licence.
• On-Demand: Cannot be enabled without license
• Verification: Check using /api/license/features/categorized

curl -H "Authorization: Bearer $ENTRA_ACCESS_TOKEN" \
  https://your-dispatcher.azurewebsites.net/api/license/features/categorized | jq '.section508Accessibility'

Every accessibility route requires an Entra JWT bearer token, validated by tenant scope inside the route - not a license key. Routes are registered as anonymous at the Azure Functions level with the JWT check enforced in code, so requests without a valid token are rejected regardless.

Troubleshooting

Tagging Not Applied

Problem: PDF doesn't contain /MarkInfo after render

Solutions:

1. Verify section508Accessibility: true in request
2. Check license includes feature: GET /api/license/features/categorized
3. Confirm render returned HTTP 200 (not error PDF)
4. Check audit logs for feature rejection reason

# Verify license
curl -X POST https://your-dispatcher.azurewebsites.net/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "templatePath": "...",
    "options": { "features": { "section508Accessibility": true } }
  }' \
  -w "HTTP %{http_code}\n"

Screen Reader Not Detecting Structure

Problem: Screen reader reads PDF as unstructured content

Solutions:

1. Verify tagging was applied (check for /MarkInfo)
2. Check source data has proper semantic structure (headings, lists, tables)
3. Ensure fonts are embedded and text is selectable (not scanned image)
4. Test with latest screen reader version

Large PDF Size After Tagging

Problem: PDF file size increased significantly

Solutions:

1. Some size increase from tagging is normal; the exact amount depends on document structure and is not independently verified
2. If the increase is large, likely causes: XMP metadata also enabled (use compression)
3. Consider enabling automatic cleanup: features.stripUnusedObjects: true

Related Features

• XMP Metadata Embedding - Add searchable metadata for ERP/SharePoint discovery
• Explain Document - Generate accessible summaries and detailed explanations
• Premium Features Overview - Complete guide to all enterprise features