Configure generation of alt-text and extended image descriptions aligned to accessibility guidelines

Alt text is not a short caption. It is a functional substitute for an image — what a person would need in order to get the same information from the page without seeing it — and that changes what belongs in it. Configuring generation for accessibility means encoding those conventions into the field schema, and knowing which images should have no alt text at all.

Why This Matters

Purpose decides content. The same photograph needs different alt text on a news article, a product page, and a link. What the image is for determines what the text must convey.

Decorative images take empty alt text. A purely decorative image should carry alt="" so assistive technology skips it. Describing it is a failure, not a courtesy.

Two lengths serve two roles. Short alt text substitutes; an extended description covers complex images — charts, diagrams, maps — where a sentence cannot carry the content.

Prerequisites

• The analyzer and fieldSchema model, and the generate and classify methods.
• That extract is documents only.
• Confidence scores and grounding.
• The caption-design objective — field descriptions as specifications.

Learning Objectives

By the end of this lesson you will be able to:

1. Distinguish decorative, informative, and complex images and treat each correctly.
2. Write alt text that conveys function, not appearance.
3. Configure a schema producing alt text and extended descriptions.
4. Handle images that are primarily text.
5. Place human review where accessibility requires it.

Building Blocks

The image roles.

Alt-text conventions.

• Convey the information, not the appearance. What would a sighted reader take from it here?
• Be concise. Assistive technology reads it inline; a paragraph is disruptive.
• Do not begin with "image of" or "picture of". The technology already announces it as an image.
• Do not repeat adjacent text. If the caption already says it, the alt text should not.
• Avoid unverifiable inference — identity, emotion, intent — unless it is the point of the image.

Extended descriptions carry the content of complex visuals: the data, trend, and axes of a chart; the components and connections of a diagram.

Schema mechanics. Alt text and extended descriptions are generate fields — extract is documents only. Image role is a classify field with an enum. Every field carries a confidence score from 0 to 1.

The text-primary exception. "Image analyzers are not optimized for scenarios where analysis is based primarily on extracted text… consider using a document field extraction schema instead."

Deep Dive

Function over appearance

The question that produces good alt text is not "what does this show?" but "what would a reader lose if the image were removed?"

A photograph of a technician on a safety page may exist to show correct protective equipment — so the alt text names the equipment, not the person's expression or the colour of the wall. The same photograph on an "about us" page may be purely atmospheric, in which case it is decorative and takes empty alt text.

That is why the same image needs different alt text in different places, and why a purely image-derived pipeline has a ceiling: the model sees the picture, not the page. Two mitigations follow.

Encode purpose in the schema. Add a classify field for the image's role, and generate alt text conditioned on that role rather than uniformly.

Supply page context where the pipeline allows it. Section heading, surrounding text, or a content-type tag lets generation respect the "do not repeat adjacent text" convention, which is otherwise impossible to satisfy — the model cannot avoid repeating text it never saw.

The three roles, and the one that surprises people

Decorative images carry no information — dividers, background textures, purely atmospheric photographs. The correct treatment is empty alt text, so a screen reader passes over them silently. This is the case a naive pipeline always gets wrong: instructed to describe every image, it produces "a blue gradient background", which a person navigating by audio must now listen to on every page. Describing a decorative image degrades accessibility.

Informative images carry content — a diagram of a process, a photograph showing a defect, a screenshot of an error. The alt text carries the same information as concisely as it can.

Functional images act — a magnifying-glass icon that runs a search, a logo linking home. The alt text names the action: "Search", "Home". Describing the picture ("magnifying glass") tells the listener nothing about what will happen.

Complex images exceed what a sentence can hold. A chart's alt text might identify it and state the headline finding, with an extended description giving the axes, series, and values. Attempting to compress a chart into one sentence loses the data; attempting to put the data in the alt text makes it unusable inline.

Text in images, and the accuracy problem

When an image is mostly text — a screenshot, a scanned notice, a poster — the text is the alt text. Paraphrasing it withholds information a sighted reader has.

Which raises accuracy. Alt text that misquotes a price, a date, or an error message is worse than absent, because it is confidently wrong to the one reader who cannot check it. And the platform's documented exception points the right way: image analyzers "are not optimized for scenarios where analysis is based primarily on extracted text… consider using a document field extraction schema instead", where the extract method is available and the service is built for exactly this.

The design rule: classify text-primary images and route them down a document path, rather than generating a description of them.

Writing the conventions into the schema

The conventions are only useful once they are in the field description, where they act as a specification.

A workable description for the alt-text field reads roughly: "A substitute for this image for a reader who cannot see it. Convey the information the image carries in this context. One sentence, under 125 characters where possible. Do not begin with 'image of' or 'picture of'. Do not describe purely visual style. Do not infer identity, emotion, or intent. If the image contains text that carries the meaning, reproduce that text. If the image is decorative, return an empty string."

Every clause maps to a convention, and the final clause matters most: it makes empty output a valid result, which is the "give the model an out" technique applied to accessibility. Without it, a model asked to describe a decorative image will describe it.

The extended-description field gets its own specification: "For charts, diagrams, and schematics only. State the type, what is being measured, the axes or components, and the main relationships or values. Do not repeat the alt text."

Worked Examples

Example 1 — every image described. An automated pass adds alt text to a site, and screen-reader users report noise: "a blue gradient background", "decorative swirl", between every section.

Decorative images must take empty alt text so assistive technology skips them. Add a classify field for image role with an enum, generate alt text only for informative, functional, and complex images, and make empty output explicitly valid in the alt-text field description.

Example 2 — an icon that runs a search. A magnifying-glass icon is a button; generation returns "a magnifying glass icon".

This is a functional image, so the alt text names the action — "Search". Describing the picture tells the listener what it looks like and nothing about what it does.

Example 3 — a chart on a financial page. A revenue chart gets one sentence: "a bar chart showing revenue".

That is informative that a chart exists and carries none of its content. Treat it as complex: short alt text identifying the chart and its headline finding, plus an extended description giving axes, series, period, and the values or trend. If the image is largely rendered text and figures, route it through a document field extraction schema, where extract is available.

Visual Explanations

Role decides treatment:

Where the pipeline needs help:

Common Mistakes

Describing decorative images. They take empty alt text.

Starting with "image of" or "picture of".

Describing a functional image instead of naming its action.

Compressing a chart into one sentence. Use an extended description.

Repeating the caption in the alt text.

Paraphrasing text that is the image's content.

Generating descriptions for text-primary images. Use a document schema.

Inferring identity, emotion, or intent from a photograph.

Shipping generated alt text without review. It is a draft.

Practice Exercises

1. Name the image roles and the correct treatment of each.
2. Why is describing a decorative image an accessibility failure?
3. Distinguish alt text, caption, and extended description by audience and content.
4. What should the alt text be for an icon that opens a menu?
5. Why can an image-only pipeline not fully satisfy the conventions, and what mitigates it?

Summary & Concept Map

Alt text is a functional substitute, so the governing question is what a reader would lose without the image — not what the image shows. Classify the role first: decorative takes empty alt text, informative takes concise text carrying the information, functional names the action, complex takes short alt text plus an extended description, and text-primary images are best routed to a document field extraction schema where extract is available and accuracy is the service's strength. Encode the conventions in the field description — length, no "image of", no unverifiable inference, no repetition of adjacent text, and empty output as a valid result. Because the model sees the image and not the page, supply role and context where you can, route low-confidence items to review, and treat generated alt text as a draft that people sign off.

Sources and freshness

Written against current Microsoft Learn documentation for the AI-103 skills measured (16 April 2026), reviewed 2026-08-20. Microsoft Learn controls every changing product contract — availability, preview status, quotas, limits, regional support, naming, and retirement dates all move independently of this lesson. Where a scenario turns on a specific number or a GA/preview boundary, confirm it against the product's own page before relying on it.