HTML5 Image Description Extension

W3C Editors' Draft 20 September 2012

This version:
Latest published version:
Latest editor's draft:
Charles McCathie Nevile, Яндекс.


This specification defines a longdesc attribute to extended descriptions to images in HTML5-based content

Status of This Document


This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is an editors' draft proposed to the HTML Working Group Accessibility Task Force as an HTML extension. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-html-a11y@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents


HTML 4 provided a longdesc attribute for the img element. This enabled a machine-discoverable description of an image to be linked to the image. This extension specification defines the same functionality for HTML5-based content.

<!-- pointing to something internal to the page -->
<img src="http://example.com/image" alt="" title="photo" longdesc="#photo1">
<!-- pointing to an external resource -->
<img src="image" alt="[figure 1]" longdesc="http://example.com/desc1">

<!-- pointing to fragment within an external resource -->
<img src="image" alt="[figure 1]" longdesc="http://example.com/descs#item3">

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, should, and may in this specification are to be interpreted as described in [RFC2119].

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.

If an algorithm calls into another algorithm, any exception that is thrown by the latter (unless it is explicitly caught), must cause the former to terminate, and the exception to be propagated up to its caller.

1.1 Dependencies

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]

Some of the terms used in this specification are defined in [DOM4], [HTML5].

2. Use Cases and Requirements

There are many ways to ensure that users do not need to see images in order to successfully interact with content. The alt attribute is designed to ensure that for everyday work, a user has enough information to replace an image, and often this is more helpful than a detailed description of every image.

Use Cases

Describing a well-known image
There are many well-known images which are widely reproduced - Mona Lisa, Washington crossing some river, the Da Vinci picture of the guy in a square and a circle, Gerníka, Cubbin's "Lost", Leunig's "ramming the shears". While different people know the images by different titles, and some images have no widely known titles, visually recognising the image is often an important part of framing a discussion. Where the image itself cannot be seen, a description can often be used to offer the same recognition.
Requires: Discoverability,
Describing a complex diagram
In many environments diagrams are used to explain a concept or transmit information efficiently. Where a user has a reduced ability to see the image (poor contrast vision and other conditions are as relevant here as a complete lack of vision), a description can enable that user to understand the information being presented
Requires: Structured Markup, Inline, Reuse, Simple Return
Teaching Accessible Development
In many environments producing content that is accessible to users regardless of disability is a legal and/or market requirement.
Requires: Maintenance, Backwards compatibility
A self-describing artistic work
For many pages the visual design of the page is an important part of the message it conveys to a fully-sighted user, but the author would like to convey as much of that design as possible to a user with low or no vision available.
Requires: No visual encumbrance
Referring to an existing description
Many well-known images are already described by other sources. The copyright on those sources is not necessarily compatible with repeating the description, but there is little value in making a new one, and
Requires: Reuse


No visual encumbrance
It must be possible to provide a description for an image without any visual encumbrance on the page.
Structured Markup
It must be possible to include rich markup (HTML5) in the description of the image.
It must be possible to associate a description in the body of a page with an image in that page
It must be possible to re-use a single description for multiple occurrences of an image
It must be simple to maintain a library of images and descriptions for dynamic assembly, or dis-assembly and re-assembly, of content.
It must be simple for a user agent to automatically discover a description provided for a given image.
Optional consumption
A user must be able to choose not to read the long description of a given image.
Simple return
A user must be able to return from the description to the image
Backwards Compatibility
It should be possible to use existing tools and techniques to associate an image with its description

The longer description mechanism MUST be easy to author, easy to maintain and have authoring support in terms of tools and educational material to accommodate authors of differing skill sets.
Backwards compatible
Any proposed mechanism MUST include a means of accessing content added by authors using the HTML4 and XHTML1 attribute longdesc

3. The longdesc attribute

The longdesc attribute must contain a valid URL potentially surrounded by spaces. The URL is a hyperlink to a description of the image that its parent img element represents.

Authoring requirement: the link is to part of a document, the description should be contained within an element which is the target of the link.

User agents should make the link available to users, and should expose the link to relevant APIs, especially accessibility-oriented APIs.

User agents should allow users to determine when images in a page contain a long description.

If a longdesc attribute has invalid content, user agents may make that content available to the user, since a common error is to include the text of a description instead of a URL as the value of the attribute.

3.1 Extension to the HTMLImageElement interface

partial interface HTMLImageElement {
             attribute DOMString longdesc;

3.1.1 Attribute

longdesc of type DOMString

The longdesc IDL attribute must be a valid non-empty URL potentially surrounded by spaces. It represents a hyperlink to a detailed description of the image its parent HTMLImageElement represents.

image.longdesc [ = value ]

Returns a DOMString that represents the attribute's contents.

Can be set, to replace the contents of the attribute with the given string.

//Make the first internal longdesc reference absolute

var baseURL = document.location.origin + document.location.pathname
var someImage = document.querySelector('img[longdesc^=#]');

someImage.longdesc = baseURL + someImage.longdesc;
//Open new windows for each longdesc found

var describedImages = document.querySelectorAll('[longdesc]');

for (i in describedImages) {
if (i.longdesc) //there are a couple of extra things matched

A. Acknowledgements

Thanks to the HTML Working group of the late 1990s for the original specification of longdesc, and to many many people involved with the development of HTML5 for the discussion that led to this specification. I haven't named them: the list might be larger than the content of the specification.

B. References

B.1 Normative references

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/

B.2 Informative references

Robin Berjon et. al., eds. HTML5. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/html5