Making JSON Formatters Accessible to Screen Reader Users

JSON is a ubiquitous data format, commonly used for data interchange in web applications. Developers often use JSON formatters or viewers to display, explore, and debug JSON structures, especially when dealing with complex or deeply nested data. However, the visual formatting that makes JSON readable for sighted users—like indentation, color-coding, and the placement of brackets, braces, and commas—poses significant challenges for users relying on screen readers.

The Problem with Visual Formatting

Screen readers interpret web pages linearly, reading out the text content and semantic structure. Standard JSON formatting relies heavily on visual cues:

• Indentation: Visually indicates nesting depth but is often ignored or flattened by screen readers.
• Symbols ({, }, [, ], :, ,): While read out, they provide little context. A screen reader might read "open brace key colon value comma" without conveying the hierarchical relationship.
• Color-coding: Helpful for differentiating strings, numbers, keys, etc., but inaccessible to users who cannot perceive color or whose screen reader doesn't announce styling changes.
• Collapsible Sections: Often implemented using buttons or icons without clear semantic grouping, making it hard for screen reader users to know what content belongs to a collapsed section.

When a screen reader encounters typical formatted JSON presented as plain text within a <pre> or <code> tag, it might read it line by line, or even character by character, resulting in a confusing jumble of symbols and values without a clear understanding of the data structure (objects, arrays, key-value pairs, nesting).

Strategies for Accessible JSON Display

To make JSON formatters accessible, we need to translate the visual structure into semantic structure that screen readers can understand and navigate. This primarily involves using appropriate HTML elements and ARIA attributes judiciously.

1. Leverage Semantic HTML Structures

The most powerful approach is to represent JSON structures using native HTML elements designed for lists and descriptions.

• Objects: A JSON object ({ }) is a collection of key-value pairs. The HTML <dl> (description list) is semantically perfect for this. Each key can be a <dt> (description term), and its corresponding value can be a <dd> (description description).
• Arrays: A JSON array ([ ]) is an ordered list of values. HTML <ul> (unordered list) or <ol> (ordered list) are suitable. Each array element becomes an <li> (list item).
• Nesting: HTML lists and description lists can be nested within <dd> or <li> elements, directly mirroring the nesting in JSON.

Example: JSON Object with <dl>

Consider this simple JSON object:

{
  "name": "Alice",
  "age": 30,
  "isStudent": true
}

An accessible HTML representation using a description list:

<dl>
  <dt>name</dt>
  <dd>"Alice"</dd>

  <dt>age</dt>
  <dd>30</dd>

  <dt>isStudent</dt>
  <dd>true</dd>
</dl>

A screen reader can announce this structure semantically, allowing users to navigate between terms (keys) and their descriptions (values).

Example: JSON Array with <ul>

A simple JSON array:

[
  "Apple",
  "Banana",
  "Cherry"
]

Accessible HTML using an unordered list:

<ul>
  <li>"Apple"</li>
  <li>"Banana"</li>
  <li>"Cherry"</li>
</ul>

Screen readers will announce this as a list with a specific number of items, allowing navigation item by item.

Example: Nested Structures

Combining objects and arrays:

{
  "items": [
    { "id": 1, "name": "Laptop" },
    { "id": 2, "name": "Keyboard" }
  ]
}

Accessible HTML using nested lists and description lists:

<dl>
  <dt>items</dt>
  <dd>
    <ul>
      <li>
        <dl>
          <dt>id</dt>
          <dd>1</dd>
          <dt>name</dt>
          <dd>"Laptop"</dd>
        </dl>
      </li>
      <li>
        <dl>
          <dt>id</dt>
          <dd>2</dd>
          <dt>name</dt>
          <dd>"Keyboard"</dd>
        </dl>
      </li>
    </ul>
  </dd>
</dl>

Screen readers understand the nested nature of these lists, allowing users to navigate into and out of the object and array structures.

2. Enhance with ARIA and Visual Aids for Screen Readers

While semantic HTML is key, sometimes explicit labeling is needed for clarity, especially with complex nesting or different data types.

• Identifying Types: You can use visually hidden text (e.g., using an <span class="sr-only">) to announce the type of value or structure. For example, before a string value, you could include <span class="sr-only">String:</span>. Before a nested object within an array item, you could add <span class="sr-only">Object item:</span>.
• Labeling Structures: Use aria-label on the container elements (<dl>, <ul>) to give them descriptive names, e.g., <dl aria-label="User Details Object">. This is particularly helpful if there are multiple JSON structures on a page.
• Roles: While native HTML elements have implicit roles, explicitly adding roles like role="group" to object containers or role="listitem" to array items can sometimes reinforce the structure for certain screen reader/browser combinations, but always prioritize native semantics first.
• Collapsible Sections: If implementing collapsible sections for large objects/arrays, use standard accordion or disclosure patterns with <button> elements, aria-expanded, and aria-controls to manage the visibility and announce the state (expanded/collapsed) to screen readers.

Example using sr-only spans:

<dl aria-label="Contact Information">
  <dt>
    <span class="sr-only">Key:</span>
    email
  </dt>
  <dd>
    <span class="sr-only">Value (String):</span>
    "user@example.com"
  </dd>

  <dt>
     <span class="sr-only">Key:</span>
    phoneNumbers
  </dt>
  <dd>
    <span class="sr-only">Value (Array):</span>
    <ul>
      <li>
        <span class="sr-only">Item (String):</span>
        "123-456-7890"
      </li>
      <li>
        <span class="sr-only">Item (String):</span>
        "987-654-3210"
      </li>
    </ul>
  </dd>
</dl>

<style>
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}
</style>

The sr-only class hides the span content visually but makes it available to screen readers, providing valuable context about the data structure and types.

3. Offer Alternative Formats

For very large or deeply nested JSON, even a well-structured HTML view can be overwhelming. Consider providing options for users to:

• Download the raw JSON file.
• View a simplified text representation (if applicable to the data).
• Switch to a table view if the data is an array of objects with consistent keys.

4. Keyboard Navigation and Focus Management (for interactive formatters)

While this page is static, a truly useful JSON formatter is often interactive (e.g., collapsible nodes). For interactive formatters, ensuring full keyboard navigability is crucial. Users should be able to:

• Tab through interactive elements like collapse/expand buttons.
• Use arrow keys to navigate within the tree/list structure (if complex).
• Understand where their focus is at all times (clear focus indicators).

Conclusion

Making JSON formatters accessible is essential for ensuring that developers and users who rely on screen readers can effectively work with structured data. By moving beyond purely visual presentation and leveraging the power of semantic HTML elements like <dl> and <ul>, supplemented with ARIA attributes and visually hidden text for clarity, we can build formatters that are not only powerful but also inclusive. Always test your implementations with actual screen readers (like NVDA, JAWS, or VoiceOver) to understand the user experience firsthand.