wcag.json is a mess

[jribbens]

This repository used to contain a file wcag.json which had a machine-readable list of guidelines, success criteria, techniques, etc. This was apparently removed in #4301 and replaced by a file which is not in the repository but which seems to be available at https://www.w3.org/WAI/WCAG22/wcag.json, although I had to find this out by trial and error. This replacement file has some issues:

• The old file had a property techniques which (through a rather complicated structure) contained id and title for each technique. This has disappeared and instead there is a property techniquesHtml which has to be run through an HTML parser to try and extract similar information.
• Some technique titles are truncated in the middle (F7, F12, F36, F46, G10, G135).
• Technique SCR21 is missing completely (despite being listed at https://www.w3.org/WAI/WCAG22/quickref/).

[alastc]

One for @kfranqueiro. I think the first step is to document (e.g. in the readme) what the wcag.json is intended to do, including why techniques has been removed. Not sure about the truncation or SCR21.

[kfranqueiro]

Thanks for reporting these issues and feedback.

General background: wcag.json was originally generated through an XSLT process, but that process had not been run for quite some time, and had fallen quite out of sync with particular implementation details regarding its consumption by Quickref in particular.

techniques vs. techniquesHtml

• The old file had a property techniques which (through a rather complicated structure) contained id and title for each technique. This has disappeared and instead there is a property techniquesHtml which has to be run through an HTML parser to try and extract similar information.

The content of this property was parsed from the Techniques sections written in the Understanding documents for each SC. Unfortunately, between additional edge cases materializing in the prose, and manual edits performed on the Quickref side, this became exceedingly problematic to attempt to reverse-engineer in order to maintain the existing format. Moreover, the process largely involved converting from HTML, to JSON, then back into extremely similar HTML on the Quickref side.

As a result, we concluded that trying to update the existing format would involve more effort than it was worth, as we were not aware of anything else consuming that property. Given your feedback, it sounds like there are indeed other consumers interested in that field, so perhaps we should give it some more thought. 🙂 Ideally these relationships could be represented in data to begin with, and the prose for the Understanding pages would be built out of the data, rather than the other way around. I will bring this feedback to the WAI Team for consideration.

Truncation of titles in links

(Addressed by #4412)

• Some technique titles are truncated in the middle (F7, F12, F36, F46, G10, G135).

As it turns out, this was already being truncated by the old data used by Quickref; the difference is now it is apparent it's being truncated.

Looking at F7 as an example, this is how its title and h1 are written:

Failure of Success Criterion 2.2.2 due to an object or applet
that has blinking content without a mechanism to pause the content that blinks
for more than five seconds

Looking at how it was represented before and after the build change:

• Failure of Success Criterion 2.2.2 due to an object or applet for more than five seconds
• F7: Failure of Success Criterion 2.2.2 due to an object or applet … for more than five seconds

In both cases, its middle line is omitted. If I recall correctly, the former "silent" truncation was also a behavior of the XSLT build system for the Techniques and Understanding Docs themselves as well.

Regardless, I could see where such truncation would be undesirable when consuming this data, so it's something I'll discuss with the WAI Team for sure. If there's agreement on addressing it, we might be able to at least implement a workaround in the short term.

SCR21

(Addressed by #4411; will be further addressed by the next republish of Quickref)

• Technique SCR21 is missing completely (despite being listed at https://www.w3.org/WAI/WCAG22/quickref/).

SCR21 was removed early last year per discussion in #3652; however, when clicking through from Quickref, it is still accessible under the WAI website from when it was previously published. We should update this to mark it as obsolete, which was something I worked on across the repo in #3975, but had skipped a couple of files, including this one.

This is an instance of the published Quickref being out-of-date; as it does not list it when using the new data. I'll talk to the WAI Team about publishing an update (which the updates to the wcag.json process were intended to enable).

Need for updated docs

I think the first step is to document (e.g. in the readme) what the wcag.json is intended to do

Agreed, this is something we need to work on, and it is on our task list. The file requiring trial and error to find is coincident with this, as the intent was to provide adequate explanation when announcing where it is.