Guide/text-alternatives

Note: You are welcome to add to this page. MIkeSmith set it up simply because he needed something to link to in demo validator error messages before we decide on an authoritative source for guidance that validators should ultimately link to.

At this point, this page only attempts to provide minimal information for understanding and dealing with error messages you may encounter when checking HTML documents using the unstable pilot version of the W3C Nu Markup Validation service, which currently is experimentally configured to emit error messages for cases of img elements that are missing alt attributes, except for a few exceptions.

In order to provide suitable text alternatives for images, you should consult detailed guidance such as the draft document HTML5: Techniques for providing useful text alternatives or the Requirements for providing text to act as an alternative for images section of the HTML5 draft specification, or @@add more here please@@.

Options for marking up text alternatives

The preferred means for marking up a text alternative for an img element is to use the alt attribute to provide a full equivalent for the image, or to provide an alt attribute with an empty value (to indicate that the image is purely presentational).

Note: The HTML Working Group does not yet have complete agreement on the appropriate set of markup options to address cases of img elements that lack alt attributes; handling of the markup cases described below has been experimentally implemented only, for proof-of-concept demonstration purposes, in the interest of having something tangible to compare notes on.

In the very rare and exceptional cases where a full equivalent for a non-presentational image is unknown or unavailable, or it is not preferable for some reason to specify the equivalent using the alt attribute directly, you can make your document conform to the current experimental expectations of the pilot version of the W3C Nu Markup Validation service by doing one of the following:

• wrap your img element in a figure element that is labelled with a figcaption element which has at least one non-empty, non-whitespace-only text node
• put an aria-labelledby attribute on the img element
• put a non-empty title attribute on the img element

Also, note that the unstable pilot version of the W3C Nu Markup Validation service is currently experimentally configured with an exception to not emit an error for cases of img elements that are missing alt in the following circumstance:

• if your document is automatically generated in some way by a system that adds a meta element with the name attribute set to "generator"

However, note that such a document is not conforming—only that the generator could not determine an appropriate equivalent. This exception is enabled in order to discourage markup generators from including "bogus" alternative text simply for the purpose of suppressing any error messages that will otherwise be emitted.

The unstable pilot version of the W3C Nu Markup Validation service is also currently experimentally configured to support the following additional markup option for indicating that an image is purely presentational:

• put a role attribute on the img element, with the value "presentation"

Note that the set of markup options given in the bulleted lists above currently represents the union of the markup options described in the following two documents:

• Guidance for conformance checkers subsection of the img-element section of the HTML5 draft specification
• HTML5 Change Proposal: Replace img Guidance for Conformance Checkers

However, because the W3C Nu Markup Validation service is not specifically intended for checking e-mail messages nor any other specialized class of documents, it does not provide any exception for the following case described in the HTML5 draft:

• The conformance checker has been configured to assume that the document is an e-mail or document intended for a specific person who is known to be able to view images