Accessibility Rules Format 1.0

From MemberWiki

Jump to: navigation, search

Accessibility Home | WCAG Rules | Rule Format 1.0 | Cache | Rule Review | Testsuite | Evaluation Results | Reporting Practices

Contents

Introduction

This document describes the requirements for the structure of OpenAjax Accessibility (OAA) validation rules and rulesets. Rulesets allow validation rules to be organized based on popular web accessibility requirements like the W3C Web Content Accessibility Guidelines and Section 508. Each OAA validation rule is associated with a requirement in a ruleset file, the primary ruleset for the OpenAjax Alliance is W3C Web Content Accessibility Guidelines 2.0. Validation rules may be applied to a specific Document Object Model (DOM) node or to a set of DOM nodes or the entire document. The rules are written Javascript and rely on the W3C DOM implementation with common browser DOM extensions (i.e. getCalculatedValue). Tools can trigger the evaluation of rules based on user interaction or external events. It is beyond the scope of this document to describe how or when rules are processed and applied by a given tool. The aim is to describe a way of expressing validation rules that will enable them to be readily consumable by accessibility tool venders and open-source or third-party components and applications and that these rules will be reusable among their various applications.

Main Features

  • Define accessibility rules using Javascript functions and data structures
  • Open source so can be freely shared among evaluation tools
  • Extensible, so rules can be extended and optimized for specific needs of a project

Severity of Rules

For a given accessibility requirement a rule can be assigned 1 of 4 of the following severity values.

  • Violation: Failing a rule with the severity of "Violation" means the associated accessibility requirement has not been met (i.e. WCAG 2.0 Success Criteria)
  • Potential Violation: Failing this rule requires some type of human inspection to determine if the the accessibility requirement has been achieved, passing this rule means that the rule does not apply to the resource
  • Recommendation: Passing this rule means that you have exceeded the minimum accessibility requirement and are using a best practice for web accessibility
  • Potential Recommendation: Failing this rule means that you may have exceeded the minimum accessibility requirement and using a best practice. Human inspection is needed to determine if the the accessibility enhancements has been achieved, passing this rule means that the rule does not apply to the resource

Extending Rules Beyond Accessibility Evaluation

This document focuses upon validation rules that are derived from WCAG 2.0 and, in particular, the accessibility of web content as understood by that specification, the aim is to permit these requirements to determine the codification of other types of rules. For instance, these requirements might be useful in describing rule formats for specifying privacy and security policies of corporate web sites, a company's branding strategy and legal policies via logos, templates, and page layouts and disclaimers and notices, or rules that are derived from other open standards, including other accessibility standards.

Rule Files and SVN Repository

The rules, rules sets, national language message, utility and tests suite are contained in a SVN Sourceforge for OpenAjax Accessibility Rules and Tests repository.

Organization of Rules and Rulesets

Name Space and Caching
Sets up A11y namespace
Cache setting
Rule Files
Code for individual rules
Rules are independent of rulesets
A rule may not be a part of every ruleset
Rules are loosely divided up to to logical groups related to the markup they check
Ruleset Files
Define the relationships between accessibility requirements and the rules
Each rule can be associated with one accessibility requirement
Rules sets can provide information on related links for more accessibility information
National Language Support (NLS) Files
Rulesets refer to IDs for messages and rule descriptive titles that can be localized to a specific language
Each ruleset needs a file for each translation
Utility Files
Set of common functions used by rules for processing rules
Functions support content processing, caching, browser abstraction, XPath and other shared resources used by the rules
WAI-ARIA File
A JSON object that define valid ARIA design patterns
Test Cases
Set of test cases for validating each rule

a11y Namespace and Caching

SVN uri: https://openajaxallianc.svn.sourceforge.net/svnroot/openajaxallianc/accessrules/src/rules/oaa-a11y.js

This file sets up the OpenAjax namespace (OpenAjax.a11y) and provides a beta implementation of the cache.

Rules Directory

SVN uri: https://openajaxallianc.svn.sourceforge.net/svnroot/openajaxallianc/accessrules/src/rules

This contains the rule information and message references to the NLS message files. The rules have been divided up into several files based on logical grouping of tests:

  • oaa-rules_accesskey.js
  • oaa-rules_audio_video.js
  • oaa-rules_data_table.js
  • oaa-rules_form_and_widget.js
  • oaa-rules_frame.js
  • oaa-rules_image_area.js
  • oaa-rules_landmark_header.js
  • oaa-rules_lang.js
  • oaa-rules_layout.js
  • oaa-rules_links.js
  • oaa-rules_scripting.js
  • oaa-rules_style.js

Ruleset Directory

SVN uri: https://openajaxallianc.svn.sourceforge.net/svnroot/openajaxallianc/accessrules/src/rulesets

The following ruleset files have been defined:

National Language Support (NLS) File Directory

SVN uri: https://openajaxallianc.svn.sourceforge.net/svnroot/openajaxallianc/accessrules/src/nls

This directory contains files for language specific messages and labels for the rules and rulesets files:

  • wcag20-ruleset_en-us.js - English translation of WCAG 2.0 messages
  • iitaa10-ruleset_en-us.js - English translation of IITAA 1.0 messages

Utility Scripts File Directory

SVN uri: https://openajaxallianc.svn.sourceforge.net/svnroot/openajaxallianc/accessrules/src/scripts/

This directory contains files that are used for content processing, caching, browser abstraction, XPath and other shared resources used by the rules:

  • colorUtil.js - Supports color contrast calculation through the use of DOM extensions to calculated styles (browser specific code)
  • cross-browser-util.js
  • javascript-xpath.js - Javascript implementation of XPath
  • util.js

WAI ARIA Directory

SVN uri: https://openajaxallianc.svn.sourceforge.net/svnroot/openajaxallianc/accessrules/src/wai-aria/

This directory contains a JSON file that defines the allowed Accessible Rich Internet Accessibility (ARIA) design patterns:

  • wai-aria-definitions.js - JSON object of allowed ARIA design patterns, used in some rules for ARIA validation

Test Directory (under development)

SVN uri: https://openajaxallianc.svn.sourceforge.net/svnroot/openajaxallianc/accessrules/src/test/

This directory contains test cases for validating OAA Rules:

  • style - directory of CSS style sheets used in test cases
  • images - directory of images used in test cases
  • media - directory for audio and video files used in test cases
  • script - directory of scripts used in test cases
  • tests - test files

Rule Files

Rule Object Properties and Methods

The following table lists the proposed properties that are associated with a rule in the rule file. For each property, the table has the following headings:

Property Name Type Required Default Description
id String Yes a unique token that can be used to pick out a particular rule from the collection of rules
messageCode String Yes null reference to a localizable description of the problem that is to be repaired when a rule fails
groupCode String Yes null reference to a group code for grouping related rules
language Array No [] list of language tokens that the rule applies, if array is empty rule applies to all languages
dependencies Array No null a list of ids of rules that must have been executed and have passed prior to this rule's execution
context String, Function Yes context expression or function describing the criteria under which the rule is applicable (see below)
validateParams Object No null parameters specific to the validation function for this rule (see below)
validate Function Yes function encapsulating the logic for a given rule (see below)

id Property

The id is a unique string value used as a programmatic reference to the Rule object properties and methods from a Ruleset. A Rule should only be assigned to one requirement per Ruleset.

Message Code Property

The messageCode property is a reference to the rules dictionary in the Natural Language Support (NLS) file. The rules dictionary is used for messages and titling information of the rule. The messageCode value is unique value for all the rules.

Group Code Property

The group_code is a reference used to identify groups of related rules and the code is also used as a reference to the group dictionary in the NLS file. NLS dictionary values reference an object that includes a title and description of the rule relationships.

Dependencies Property

The dependencies property is an array of Rule id values. If a rule appears in the list and fails then this rule will also fail. For example if an img element does not have an alt attribute there is no reason to rule rules that examine the quality of the rule.

Contexts Property

A 'rule context' is a JavaScript object that represents key features of the environment that are required to execute a given rule. This environment might include the document object, a single node or set of nodes, an element with a given attribute (possibly with a particular value), a dispatched event and its associated target and type, and related configuration or state information as well as other tool-dependent properties.

The purpose of the rule context is to make rule execution more efficient, permitting the evaluation or validation tool to invoke only those rules that are appropriate given the conditions or characteristics of the environment at hand. Rule contexts also minimize rewriting conditions under which rules are to be executed, thus decoupling the rule logic of a rule from its environment and encouraging good coding practices and code reuse.

The group has defined the following rule contexts:

document
the rule is to be applied at the document-level, requiring the context of the entire document to be successfully executed. Such rules would, for instance, include checks for unique element ids or for appropriate heading hierarchies.
frame/iframe
the rule applies to the content of a frame or iframe. (This may turn out to be collapsable into the document context.)
element
the rule applies to a DOM node with nodeType = ELEMENT_NODE regardless of attributes or event handlers. In HTML validations, for example, tags for element-oriented contexts might include 'img' or 'input', which would specify that rules with that tag only be executed in the context of elements with that tag name.
element with attribute (possibly with a specific value)
rule applies to an element with a particular attribute or set of attributes (e.g. elements with tabindex attribute ) or with attributes with a particular value (e.g. tabindex = -1).
element pattern
the rule applies to a set of elements with certain child/parent relationships (e.g. header nesting, fieldset/legend, list elements and widgets)
element text
the rule applies to the text nodes of a given element
browser or W3C DOM events
rules to be applied when a particular browser event (e.g. onfocus) or DOM event (DOMNodeInserted) is fired by the user agent.

In addition to the above contexts, two special 'exclusionary' context are defined:

exclusive of element
the rule applies to all but an element with a given node name. For example, in HTML, a rule might apply to all elements except <img> elements.
exclusive of attribute
the rule applies to all elements except to those with the specified attributes. For example, in HTML, a rule might apply to all elements except <img> elements that have an alt attribute.

Specifying Rule Contexts

Since we have defined several types of rule contexts, we need a notation for expressing those contexts somewhere in the rule or ruleset objects. The following proposed notation is used to specify rule contexts in a rule or ruleset. The item on the left is the rule context as defined above and the expression on the right represents the syntax for expressing that context. This expression is called a 'rule context expression', a predefined notation for expressing the rule contexts to be used in rule or ruleset objects to associate rule logic with the context in which that logic is to be executed.

In the following grammar, whitespace is optional and present only for readability. Any context expression parsing apparatus should ignore whitespace in places where it appears in the grammar:

contextExpr ::= document

   | frame
   | element ("|" element)*
   | element_attrs_present ("|" element_attrs_present)*
   | element_attrs_values ("|" element_attrs_values)*
   | element_hierarchy_pattern
   | events
   | exclusionary_context_expr
  1. document ::= "document"
  2. frame ::= "frame" | "iframe"
  3. element ::= elemName( "|" elemName)*
  4. element_attrs_present ::= elemName "[@" attrName "]"("[@" attrName "]")*
  5. element_attrs_values ::= elemName "[@" attrName op attrValue "]"("[@" attrName op attrValue "]")*
  6. exclusionary_context_expr ::= exclusionary_element_context | (exclusionary_attr_context (| exclusionary_attr_context)*
  7. exclusionary_element_context ::= "!(" element ")"
  8. exclusionary_attr_context ::= elemName "[!(@" attrName ("|@" attrName )* ")]"
  9. op ::= "==" | "!="
  10. events ::= eventType (| eventType)*
  11. element_hierarchy_pattern ::= >not yet defined>

Note: eventTypes are: DOMFocusIn, DOMMutation, DOMNodeInserted, DOMNodeDeleted, User

In this simple grammar, both 'elemName' and 'attrName' are qualified names as described in Namespaces in XML 1.0. The 'elemName' may also be the wildcard character '*' (which represents all elements with nodeType == ELEMENT_NODE). The identifier 'eventType' can be an event type taken from either the DOM Level 2 Events or HTML 4.01 specifications.

Context Examples

Following are some examples of context expressions that might be used in a rule object:

"document"
the ruleContext handed to the validate function must be the document object (i.e. window.document or window.content.document in FF)
"img"
the ruleContext handed to the validate function must be an <img> element
"img | input"
the ruleContext handed to the validate function must be either an <img> or <input> element
"*"
the ruleContext handed to the validate function can be any element (i.e. ruleContext.nodeType == Node.ELEMENT_NODE)
"img[@alt]"
the ruleContext handed to the validate function must be an <img> element with an alt attribute (which may be empty)
"img[@alt][@title]"
the ruleContext handed to the validate function must be an <img> element with both an alt and title attribute
"img[@alt=='foo']"
the ruleContext handed to the validate function must be an <img> element with an alt attribute with a value of exactly 'foo'
"img[@alt!='foo']"
the ruleContext handed to the validate function must be an <img> element with either a missing alt attribute or an alt attribute that does not have the value 'foo'
"*[@alt]"
the ruleContext handed to the validate function can be any element with an alt attribute
"!(img)"
the ruleContext handed to the validate function must not be an <img> element
"!(img | input)"
the ruleContext handed to the validate function must be neither an <img> nor <input> element
"img[!(@alt)]"
the ruleContext handed to the validate function must be an <img> element that does not have an alt attribute
"img[!(@alt | @title)]"
the ruleContext handed to the validate function must be an <img> element that has neither an alt nor a title attribute
"*[!(@alt)]"
the ruleContext handed to the validate function can be any element that does not have an alt attribute

Note that these examples could be combined using the disjunct operator '|' to form compound context expressions. However, exclusionary contexts may not be combined with non-exclusionary contexts.

Validation Parameters Array

The logic of some validation rules will depend upon parameters that are determined by the ruleset in which the rule is placed or by the native language of the content. The group will offer suggested values for such parameters but tool developers may expose ways to overwrite the properties or values of these parameters.

The 'validateParams' property of a rule logic object serves to define such parameters. The validateParams object is a JavaScript object, the keys of which are the names of the variables (i.e. the identifiers) to be referenced in the validate function for that rule. Each identifier/key is associated with an object that contains additional information about the parameter, including the only required property, its value.

For example, the range within which the length of an alt text attribute value might fall will likely depend upon the native language of the content being validated and by the specification embodied by a given ruleset. Hence, this range could be expressed as two parameters, 'min_alt_text_length' and 'max_alt_text_length'. A rule that wishes to utilize these parameters might look as follows:

 {
   id : 'RULE_1',
   messageCode : 'MESSAGE_1',
   groupCode :  'GROUP_1',
   context : 'img',
   validateParams : {
       min_alt_text_length : {value:10, type:"integer"},
       max_alt_text_length : {value:150, type:"integer"}
   },
   validate : function (ruleContext) {
       var params = this.validateParams;
       var length = ruleContext.alt.length ;
       var passed = length >= params.min_alt_text_length.value && length <= params.min_alt_text_length.value;
       :
   },
   :
} 

Of course, the 'type' property is optional and many other properties could be defined, depending upon application requirements.

Validate Function

The rule logic for a given rule is always expressed as a JavaScript function and associated with the 'validate' method of the Rule Object. The definition of this function is as follows:

validate : function (ruleContext)

where 'ruleContext' is one of the predetermined context objects discussed earlier (e.g. document object, particular element, etc.). The body of the function must contain standard JavaScript code to be executed upon the rule being invoked by a validation or rules engine responsible for consuming and processing the rule objects in a given ruleset. This code can include:

  1. standard variable declarations
  2. standard control-flow structures
  3. calls to other JavaScript functions
  4. references to predefined constants or variables

With regard to items (3) and (4), constants, variables, functions, and other JavaScript artifacts upon which the validate function depends must be found in modules that are loaded and interpreted by the same JavaScript engine responsible for processing rule and ruleset objects and in the same execution context as these objects. The mechanism for ensuring that all appropriate JavaScript modules are loaded and for the evaluation of such constants, variables, and functions is left to tool developers.

The object that contains the definition of the validate function must also contain the rule id as described earlier and any dependencies and a context expression. All other properties are optional or may be specified in the ruleset requirement that leverages this rule object.

Validate Function Result

The validate function must return a JavaScript object of type Object ValidationResult with the following properties:

Name Type Required Description
result boolean Yes whether or not the rule was executed successfully:
  • 'true': means that the rule was executed successfully or that the criterion that the rule embodies was satisfied
  • 'false' means that that criterion was not satisfied
  • '-1': means the rule failed to execute properly, this may because a rule requires a value or calculation requires a DOM property or method that is not available from the DOM processing the rules
nodes Array No
  • If the result' is 'false' the nodes array is a list of the nodes that failed, which may be empty or null if the rule was executed successfully (i.e. the 'result' property is 'true'),
  • If the result id 'true' the 'nodes array may include the list of the nodes that passed, which may be empty or null
attrs Array No
  • if the result is 'false' the list of node attributes that did not pass, which may be empty or null if the rule was executed successfully (i.e. the 'result' property is 'true') or if the element had no attributes
  • If the result' is 'true' the list of nodes maybe empty or null
textContent String No The message text describing the rule requirements and results
msgArgs Array No
  • if the result is 'false' an array of parameters for the message
  • If the result is 'true' the array is null

Message arguments given in the 'msgArgs' property are used when a rule fails (i.e. its 'result' property is 'false') and additional information is necessary to complete the message reported to the user. The additional information is only available during execution time or once the rule is executed. The processing of message parameters and the tokens that indicate the placement and ordering of the values of these parameters is tool-dependent but it is expected that such tokens would appear in the localized strings indicated by the 'message_code' property.

Example Rule File Code

The following is example code for two rule objects. The objects are part of an array of rule objects.

  //
  // OpenAjax Alliance Rules 
  // Rule group: Image and Area Rules
  //
  with (OpenAjax.a11y) {
    addRules([
          
      // ------------------------
      // Rule 1: Images must have valid alt text.
      // Group 4: Image and Area Rule
      // ------------------------
           
    {
      id: "RULE_1",
      context: "img[@role != 'presentation']",
      validateParams: {
        max_decorative_width: { value: 8, type: 'Integer' },
        max_decorative_height: { value: 8, type: 'Integer' },
      },
      validate: function (ruleContext) {
        var vparams = this.validateParams;
        //
        // Don't flag images that are smaller than 9x9 pixels.  
        // If image is greater than 9x9, make sure is has an alt attribute.
        //
        var passed = (ruleContext.clientWidth  <= vparams.max_decorative_width.value   &&
                      ruleContext.clientHeight <= vparams.max_decorative_height.value) ||
                      OpenAjax.a11y.xbrowser.hasAttribute(ruleContext, "alt");
  
        return new ValidationResult(passed, [ruleContext], , , []);
 
      } // endfunction
 
    },          
 
      // ------------------------
      // Rule 2: Image file name is not valid alt text.
      // Group 4: Image and Area Rule
      // ------------------------     
 
    {
      id: "RULE_2",
      context: "img[@role != 'presentation']",
      validateParams: {
        alt_forebidden_file_ext_pattern: { value: /.+\.(bmp|jpg|jpeg|jfif|gif|png|tif|tiff)$/i, type: 'Regular Expression' },
      },
      dependencies: ["rule_1",],
      validate: function (ruleContext) {
        var found = this.validateParams.alt_forebidden_file_ext_pattern.value.test(ruleContext.alt);
        return new ValidationResult(!found, [ruleContext], 'alt', , []);
      }
    },
     .
     .
     .
     .
     .
     .
     .
     .
     .
  ]  // end rule object array
 ); 
}

Ruleset Files

Ruleset Object

Rulesets are defined as JSON objects and have the following properties:

Name Type Required Default Description
id String Yes a unique identifier that can be used to identify a ruleset from the collection of rulesets
nameCode String Yes the ID of a localizable, human-readable name of or label for the ruleset
descriptionCode String No null the ID of a localizable, human-readable description for the ruleset
rulesetUrl String No null the URL defining the specification or guidelines embodied by this ruleset
baseReqUrl String No null the base URL for resolving any relative URLs given as the value of the 'requirementUrl' property of rule objects
versionCode String Yes Yes Version number of the current ruleset
date String Yes No Date the ruleset was last modified
requirements Array Yes an array of requirements objects as defined below

Requirement Object Array

Each object in the requirements array has a set of properties to identify a rule and the severity, priority and message in relation to the requirement. This includes a 'rules' property, which is a dictional list that associates Rule Objects to the requirement using the id of the Rule Object. A Rule Object should only be associated with one requirement within a rule set. All other properties for that rule are obtained from the requirements object or from the rule logic object (the object containing the definition of the validate function). Thus, the value of a given rule property can be obtained from the following sources, in the following order:

  1. the rule logic object itself in which the validate function is defined
  2. the rule object within the requirements object (ruleset.rule) that defines properties specific to a given rule
  3. the requirements object in which a rule is included

Ruleset Requirement Object

Name Type Required Default Description
requirementNumber String Yes The identifying number, index, tag, or other distinguishing identifier within a given checklist, specification, or set of guidelines for the rule (e.g. "1.1.1" in WCAG20 or "1194.21d" of U.S. Section 508
requirementLevel String Yes Localizable compliance or stringency level as taken from the original set of guidelines that corresponds to the value of a given 'requirementNumber' property
requirementURL String No null A relative or absolute URL at which the rule is defined and where more information about the rule and how to satisfy it is available
enabled Boolean No True A boolean value indicating whether the requirement should be tested as part of the current evaluation, default value is True, but could be temporarily disabled through a testing tool
rules Object List Yes A list of rule ids associated with the requirement. Each rule id defines an object that is used to define the severity, relative priority with the requirement and the message associated with the rule

Ruleset Rule Object List

Rule Object ids are generated from OAA Accessibility Support web site and the values are represented as strings in the rule object. Rule Object ids are assigned from a range of numeric values with a prefix of "RUKE_NN". The Rule ids are generated by the support site so the ids can be more easily referenced to test cases, rulesets and National Langauge Support (NLS) messages for the rules.

A ruleset is a collection of rules, usually meant to embody a specific set of guidelines, a policy, or set of compliance requirements. For example, a ruleset might represent the accessibility standards defined by | WCAG20 or the by | U.S. Section 508.

Rulesets have their own unique properties (discussed in the next section) and subgroups of rules called 'requirements'. A 'requirement' object represents a colection of rules that corresponds to a specification, or checklist. For example, each of the success criteria of the W3C Web Content Accessibility Guidelines (WCAG) 2.0 would be a Requirement Object in an OAA ruleset representing WCAG 2.0.

Ruleset Rule Object

Name Type Required Values Description
severityCode String Yes
  • SEVERITY_VIOLATION
  • SEVERITY_POTENTIAL_VIOLATION
  • SEVERITY_RECOMMENDATION
  • SEVERITY_POTENTIAL_RECOMMENDATION
One of four localizable token describing the impact to the application or content that results when failing this rule
priorityCode String Yes
  • PRIORITY_P1
  • PRIORITY_P2
  • PRIORITY_P3
One of three localizable token describing the priority of importance of the rule relative to the other rules in the requirement
statusCode String Yes
  • STATUS_ACCEPTED
  • STATUS_PROPOSED
  • STATUS_DEPRECATED
One of three localizable token describing the status of using the rule to evaluate content
messageCode String Yes null reference to a localizable description of the problem that is to be repaired when a rule fails
groupCode String Yes null reference to a group code for grouping related rules
enable Boolean No default value is true A boolean value indicating whether a rule should be evaluated

severityCode

This is the importance of a rule in meeting the minimal and optimal implementation of an accessibility requirement. Violations are assigned to rules for minimum compliance and recommendations are assigned to rules that define improved or optimal accessibility.

severityCode Values Description
SEVERITY_VIOLATION This rule defines a coding pattern for basic or minimum implementation of a accessibility requirement
SEVERITY_POTENTIAL_VIOLATION If this rule fails it requires a human inspection to determine if code meets accessibility requirement. If the rule passes if means that it is not applicable to the current resource or passed the requirement.
SEVERITY_RECOMMENDATION This rule identifies coding patterns that improve the implementation of an accessibility requirement
SEVERITY_POTENTIAL_RECOMMENDATION If this rule fails it requires a human inspection to determine if the code exceeds an requirement. If the rule passes if means that it is not applicable to the current resource or passed the requirement.

priorityCode

These are the advisory relative priorities for implementation of a rule requirement. If more than one rule fails for a requirement these priorities help developers understand which rules are more important in improving accessibility. The priorities to not affect the severity of the requirement, all rules must be satisfied to fully meet a requirement.

priorityCode Values Description
PRIORITY_P1 Rule coding practices that are priority P1 should be satisfied before P2 and P3 rules
PRIORITY_P2 Rule coding practices that are priority P2 should be satisfied before P3 rules
PRIORITY_P3 Rule coding practices that are priority P3 should be satisfied after P1 and P2 requirements

statusCode

The status code indicates whether the rule has been accepted and reviewed for general use, proposed for review or has been deprecated. Evaluation tools may want to filter rules for inclusion in a report based on the status of rules.

statusCode Values Description
STATUS_ACCEPTED This rule defines a coding pattern for basic or minimum implementation of a accessibility requirement
STATUS_PROPOSED If this rule fails it requires a human interpretation to determine if code meets basic or minimum implementation of a accessibility requirement
STATUS_DEPRECATED This rule identifies coding patterns that improve the implementation of an accessibility requirement

messageCode

This is dictionary value for use in looking up messages associated with the Rule Object in the rules dictionary object in the National Language Support (NLS) file for a ruleset.

groupCode

The groupCode is dictionary value for grouping related Rule Objects. An evaluation tool could provide a way to enable and disable the execution of groups of rules. The groupCode is also a dictionary value for use in looking up messages associated with the group in the groups dictionary object in the National Language Support (NLS) file for a ruleset.

Example Ruleset File Code

For example abbreviated WCAG 2.0 ruleset definition:


//
// OpenAjax Alliance (OAA) Rule Set for WCAG 2.0 (Beta)
//
 
OpenAjax.a11y.addRuleset(
   {
       //
       // Basic info
       // 
   	id : 'WCAG_2_0',                      // Unique ID reference for ruleset
       nameCode : 'name',                    // Reference to the name of requirements document in the NLS file
       descriptionCode : 'description',      // Reference to the description of the requirements document in the NLS file 
       versionCode : 'version',              // Reference to the ruleset version in the NLS file
       date: '2011-02-25',                   // Date this file was last modified

                
       // rulesetUrl - URL of the checklist/ruleset as a whole
       rulesetUrl : 'http://www.w3.org/TR/WCAG20/',
       
       // baseReqUrl - used to resolve relative urls of requirementUrls only
       baseReqUrl : ' ',
       
       //
       //  WCAG 2.0 Success Criteria mapping of OAA Rules
       //        
       requirements : [   
  
                //
                // WCAG 2.0 Success Criteria 1.1.1 Non-text Content
                //
              {
                requirementNumber : '1.1.1',
                requirementLevel  : 'LEVEL.A',
                requirementUrl    : 'http://www.w3.org/TR/WCAG20/#text-equiv',
                enabled           : 'true',  
                rules : {
                               // 
                               // Rule 1: Images must have valid alt text.
                               // Group 4: Image and Area Rule
                               // 
                    'RULE_1' : {
                               severityCode : 'SEVERITY_VIOLATION',
                               priorityCode : 'PRIORITY_P1',
                               statusCode   : 'STATUS_ACCEPTED',
                               messageCode  : 'MESSAGE_1',
                               groupCode    : 'GROUP_4',
                               enabled      : 'true',   
                             },
                               // 
                               // Rule 2: Image file name is not valid alt text.
                               // Group 4: Image and Area Rule
                               // 
                    'RULE_2' : {
                               severityCode : 'SEVERITY_VIOLATION',
                               priorityCode : 'PRIORITY_P1',
                               statusCode   : 'STATUS_ACCEPTED',
                               messageCode  : 'MESSAGE_2',
                               groupCode    : 'GROUP_4',
                               enabled      : 'true',   
                             },
                               // 
                               // Rule 3: Certain words cannot be used as a part of valid alt text
                               // Group 4: Image and Area Rule
                               // 
                    'RULE_3' : {
                               severityCode : 'SEVERITY_VIOLATION',
                               priorityCode : 'PRIORITY_P1',
                               statusCode   : 'STATUS_ACCEPTED',
                               messageCode  : 'MESSAGE_3',
                               groupCode    : 'GROUP_4',
                               enabled      : 'true',   
                             },
                               // 
                               // Rule 4: Length of alt text.
                               // Group 4: Image and Area Rule
                               // 
                    'RULE_4' : {
                               severityCode : 'SEVERITY_RECOMMENDATION',
                               priorityCode : 'PRIORITY_P1',
                               statusCode   : 'STATUS_ACCEPTED',
                               messageCode  : 'MESSAGE_4',
                               groupCode    : 'GROUP_4',
                               enabled      : 'true',   
                             },
                               // 
                               // Rule 5: Longdesc must have valid URI.
                               // Group 4: Image and Area Rule
                               // 
                    'RULE_5' : {
                               severityCode : 'SEVERITY_VIOLATION',
                               priorityCode : 'PRIORITY_P1',
                               statusCode   : 'STATUS_ACCEPTED',
                               messageCode  : 'MESSAGE_5',
                               groupCode    : 'GROUP_4',
                               enabled      : 'true',   
                             },
                               // 
                               // Rule 6: If an image has an alt or title attribute, it should not have a presentation role.
                               // Group 4: Image and Area Rule
                               // 
                    'RULE_6' : {
                               severityCode : 'SEVERITY_VIOLATION',
                               priorityCode : 'PRIORITY_P1',
                               statusCode   : 'STATUS_ACCEPTED',
                               messageCode  : 'MESSAGE_6',
                               groupCode    : 'GROUP_4',
                               enabled      : 'true',   
                             },
                               // 
                               // Rule 78: ALT text must describe content or purpose of image
                               // Group 4: Image and Area Rule
                               // 
                    'RULE_78' : {
                               severityCode : 'SEVERITY_POTENTIAL_VIOLATION',
                               priorityCode : 'PRIORITY_P1',
                               statusCode   : 'STATUS_PROPOSED',
                               messageCode  : 'MESSAGE_78',
                               groupCode    : 'GROUP_4',
                               enabled      : 'true',   
                             },
                }   // end list of rules
        
              }, // end success criteria 1.1.1
              .
              .
              .
              .
              .
 ]  // end array of requiremnts
} // end ruleset object

National Language Support (NLS) Files

The National Language Support (NLS) files provide a way to localize the language of all the text resources associated with the OAA rules and a ruleset.

Title and URL Properties

Provide human readable text in the national language of the NLS file and a URL to the national language of the requirements document.

Level Property

The levels dictionary list allows human readable labels to be assigned to requirement levels for specific languages. Some accessibility requirements, like the W3C Web Content Accessibility Guidelines (WCAG) 2.0, prioritize the importance of the accessibility of each requirement. The level property is designed to represent these priorities of importance and can be used by evaluation tools to filter rule results. For example, some developers may only be interested in the Level A requirements of WCAG 2.0 and therefore would only want to see rule results associated with those requirements.

Severity Property

The severities dictionary list allows human readable labels to be assigned to the possible results of a rule evaluation for specific languages.

Priority Property

The priorities dictionary list allows human readable labels to be assigned to relative importance of implementing a rule for specific languages.. If multiple rules fail the priority provides developers with advisory information on which rules within a requirement are more important.

Status Property

The status dictionary list provides human readable labels for the status of the rule for specific languages.

Requirements Object List

The requirements dictionary list provides human readable content for information related to the accessibility requirement for specific languages. Each object in the list is an object that include the following properties:

  • title: The title of the requirement
  • description: A longer description of the requirement
  • url: A url to a translation of the requirement to the localized language
  • references: An array of Reference Objects to support the implementation or interpretation of a requirement

Requirements Reference Object

The Reference Object consists of three properties:

  • title: Title of the URL reference
  • url: URL reference to the reference
  • type: Label for the type of resource
    • TYPE_TECHNIQUE: Link to a techniques for implementing the requirement
    • TYPE_MANUAL: Testing procedures for manual checks of the requirement
    • TYPE_INFORMATION: More information or discussions about the requirement
    • TYPE_AUTHORING: Authoring tools that support implementation of the requirement
    • TYPE_OTHER: Other related resources

Rules Object List

The rules dictionary list provides human readable content for the title and messages related to the rules for specific language. Each object in the list is an object that include the following properties:

  • title: The title of the rule, used in documenting the rule in rule and ruleset files
  • message: The message string that is used to report the results of a rule, may contain arguments

Rule Group Object List

The groups dictionary list provides human readable content for the title and descriptions related to the grouping of rules for specific language. Each object in the list is an object that include the following properties:

  • title: The title of the group
  • description: Description of the relationship between rules in a rule group

Example NLS File Code

//
// OpenAjax Alliance WCAG 2.0 Ruleset National Language Support (NLS): English
//

OpenAjax.a11y.addNLSForRuleset('WCAG_2_0', 'en-us', 
 {
   name : 'WCAG 2.0',
   description : 'Web Content Accessibility Guidelines v2.0',	  
   version: 'beta',
   date: '2011-02-24'
  
   //
   // Level of important of a requirement
   //
   levels : {
       'LEVEL_A'   : 'A',     // Most important requirements
       'LEVEL_AA'  : 'AA',    // Important requirements
       'LEVEL_AAA' : 'AAA',   // Lower importance requirements
   },
    
   //
   // Severity of not meeting a requirement  
   //
   severities : {
       'SEVERITY_PASS'                     : 'Pass',
       'SEVERITY_NA'                       : 'N/A',
       'SEVERITY_VIOLATION'                : 'Violation',
       'SEVERITY_POTENTIAL_VIOLATION'      : 'Potential Violation',
       'SEVERITY_RECOMMENDATION'           : 'Recommendation',
       'SEVERITY_POTENTIAL_RECOMMENDATION' : 'Potential Recommendation'
   },
    
   //
   // Relative implementation priorities of complying to rule requirements  
   //
   priorities : {
       'PRIORITY_P1' : 'First Priority',
       'PRIORITY_P2' : 'Second Priority',
       'PRIORITY_P3' : 'Third Priority',
   },		
 
   //
   // Status of a rule for evaluating a requirement  
   //
   status : {
       'STATUS_ACCEPTED'   : 'Accepted',
       'STATUS_PROPOSED'   : 'Proposed',
       'STATUS_DEPRECATED' : 'Deprecated',
   },

   //
   //  WCAG 2.0 requirements National Language Support (NLS)
   //
   requirements : {
    '1.1.1' : {
                label       : '1.1.1 Non-text Content',
                description : 'All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for the situations listed below.',
                url         : 'http://www.w3.org/TR/WCAG20/#text-equiv',
                references  : [],
              },
    '1.2.1' : {
                label       : '1.2.1 Audio-only and Video-only (Prerecorded)',
                description : 'For prerecorded audio-only and prerecorded video-only media, the following are true, except when the audio or video is a media alternative for text and is clearly labeled as such: (1) Prerecorded Audio-only: An alternative for time-based media is provided that presents equivalent information for prerecorded audio-only content. (2) Prerecorded Video-only: Either an alternative for time-based media or an audio track is provided that presents equivalent information for prerecorded video-only content.',
                url         : 'http://www.w3.org/TR/WCAG20/#media-equiv-av-only-alt',
                references  : [],
              },
    '1.2.2' : {
                label       : '1.2.2 Captions (Prerecorded)',
                description : 'Captions are provided for all prerecorded audio content in synchronized media, except when the media is a media alternative for text and is clearly labeled as such.',
                url         : 'http://www.w3.org/TR/WCAG20/#media-equiv-captions',
                references  : [],
              },
              .
              .
              .
              .
              .
 
   },
 
 
   //
   //  OAA Rules title and mesage string National Language Support (NLS)
   //
   rules : {
     'MESSAGE_1' : {
                      message: 'Rule 1 Non-decorative images that convey meaning must have valid alt text.' ,
                      title:   'Rule 1 Images must have valid alt text.' ,
                   },
     'MESSAGE_2' : {
                      message: 'Rule 2 An image file name may not be specified for valid alternative text.' ,
                      title:   'Rule 2 Image file name is not valid alt text.' ,
                   },
     'MESSAGE_3' : {
                      message: 'Rule 3 Alt text containing the words image, picture, graph, photo are not valid for an image.' ,
                      title:   'Rule 3 Certain words cannot be used as a part of valid alt text' ,
                   },
     'MESSAGE_4' : {
                      message: 'Rule 4 Make sure the alt attribute length is >= alt_min_length and <= alt_max_length.' ,
                      title:   'Rule 4 Length of alt text.' ,
                   },
     'MESSAGE_5' : {
                      message: 'Rule 5 The longdesc must point to a legitimate alternative resource (e.g. an .html file).' ,
                      title:   'Rule 5 Longdesc must have valid URI.' ,
                   },
                    .
                    .
                    .
                    .
                    .
                    .
 
   },
   
   //
   //  OAA Rule Groups title and message string National Language Support (NLS)
   //
   groups: {
     'GROUP_1' : {
                    title:       'Unassigned Rule' ,
                    description:  ,
                 },
     'GROUP_2' : {
                    title:       'Landmark and Header Rule' ,
                    description:  ,
                 },
     'GROUP_3' : {
                    title:       'Data Table Rule' ,
                    description:  ,
                 },
                 .
                 .
                 .
                 .


   },

 }
);

Rule Test Cases

When a rule is submitted to the task force in the format given above, the contributor is also responsible for submitting a test case for that rule. The test case is an HTML document that can demonstrate that the rule, when executed, returns a passing result on those nodes that satisfy the context of the rule and the rule logic and returns a failing result for those that satisfy the rule context but fail the rule logic. Thus, nodes that do not satisfy the rule context should be ignored.

Test cases will be managed by the support OAA Accessibility Website that includes management of Test Cases for each rule. There is a web based editor for managing the test cases and assoicated rules and pass/fail ids.

As part of the test case a JSON data structure must be included to provide information on test results. This information is encoded in JSON using a rulesCoverage object that looks like the following:

Example Test Case Meta Data

  <script type="text/javascript">
         var OpenAjax = OpenAjax || {} ;
        OpenAjax.a11y = OpenAjax.a11y || {} ;
        OpenAjax.a11y.test = OpenAjax.a11y.test || {} ;

        OpenAjax.a11y.test.testId    = "25";
        OpenAjax.a11y.test.testTitle = "Some Form Controls Violate Rules";
        OpenAjax.a11y.test.testDate = "Last updated on Dec. 12, 2010, 8:51 p.m.";
        OpenAjax.a11y.test.testUrl = "http://www.oaa-accessibility.org/testsuites/test/25/";
        
        OpenAjax.a11y.test.nextUrl = "http://www.oaa-accessibility.org/testsuites/test/26/";
                
        OpenAjax.a11y.test.ruleTestResults = [ 
        {
           ruleId: "rule_47",
           ruleLabel: "Each fieldset element should contain a legend element.",
           ruleFailIds: ['id6','id8'],
           rulePassIds: ['id1']
        },        
        {
           ruleId: "rule_49",
           ruleLabel: "Each input element with type=text | password | checkbox | radio | file and each select and textarea element should either be referenced by the for attribute of a label element via its id attribute, or have a title attribute.",
           ruleFailIds: ['id9','id10'],
           rulePassIds: ['id2','id3','id4','id5','id7','id11','id12']
        },
        {
           ruleId: "rule_50",
           ruleLabel: "Input element of type=[image] must have an alt or a title attribute.",
           ruleFailIds: ['id13'],
           rulePassIds: []
        },
        {
           ruleId: "rule_57",
           ruleLabel: "Form controls must have unique ids.",
           ruleFailIds: ['id7'],
           rulePassIds: ['id2','id3','id4','id5','id9','id10','id11','id12','id13']
        },
        ]
        
    </script>

The ruleCoverage object should be defined in the OpenAjax.a11y namespace for clarity and interoperability of tooling and is an array of objects. Each object in this array consists of three properties:

  1. 'ruleId': specifies the rule for which test results are being given
  2. 'ruleTitle': specifies a human readable title for the rule
  3. 'ruleFailIds': list of IDs of node that the rule should mark as failed
  4. 'rulePassIds': list of IDs of node that the rule should mark as passing a rule

No test harness is maintained by this group at this time for verifying the correctness of the test case or of its validity with regard to the rule(s) that it purports to test.

Personal tools