Inside an Analyzer Definition: Base, Config, and Schema

The unit of work you actually author

Every extraction job in Content Understanding runs against an analyzer, and an analyzer is a JSON document you write. That sentence sounds trivial until you notice what follows from it: there is no training run, no model artefact, no endpoint to deploy per project. What you produce is a definition, you store it under an identifier, and every later call names that identifier. Understanding the shape of that definition is most of what this slice of the syllabus asks of you.

The definition has four parts, and they answer four different questions. Identity properties say what this analyzer is called and what it is for. The model block says which generative models power it. The config block says how content is processed. The field schema says what structured output you want back. Learners who can name these four parts, and say which question each answers, can read any analyzer example they meet.

Identity, and why the description is not decoration

The identity properties are analyzerId, name, description and baseAnalyzerId. The identifier is how you reference the analyzer in API calls, and it is constrained: letters, numbers, dots and underscores, up to sixty-four characters.

The surprise is description. It looks like documentation for humans, but the model reads it as context while it extracts fields. A description that says the analyzer handles commercial invoices and pulls out vendor details, line items and totals genuinely improves results compared with a description that says nothing. This is a recurring pattern in Content Understanding: prose you write is prompt material, not comments.

Inheritance from a base analyzer

baseAnalyzerId points at a parent whose configuration your analyzer inherits. There are exactly four parents you may derive a custom analyzer from, one per modality: the document, audio, video and image base analyzers. That constraint is worth memorising, because a plausible-sounding exam distractor is that you can subclass any domain-specific analyzer directly. You cannot derive from an arbitrary analyzer; you copy or adapt its definition instead.

Inheritance behaves the way you would expect from any configuration system. You get the parent's defaults, and you override only what you care about. Practically, that means a short custom analyzer definition is normal and healthy: a base identifier, a couple of flipped switches, and a field schema.

The config block is modality-specific

The most common misconception in this area is that the configuration switches form one universal set. They do not. Document analyzers expose by far the richest surface: optical character recognition, layout, formula detection, barcode decoding, table and chart output formats, figure description and figure analysis, annotation format, segmentation, one-segment-per-page mode, and the flag that turns on field-level source and confidence. Video analyzers expose a much smaller set concerned with locales, segmentation and content categories. Audio analyzers expose detail-level output and locales. Image analyzers expose essentially one switch, the one that asks for detailed output.

The reason is not arbitrary. Each switch corresponds to something the extraction layer can actually do for that modality. There are no page bounding boxes in an audio file, so there is nothing for a grounding switch to return.

A second point about defaults: several document switches are already on. Optical character recognition, layout, formula and barcode detection default to enabled, and the guidance is to disable what you do not need — turning off character recognition for native digital PDFs, for instance — rather than to enable everything. Figure description and figure analysis are the opposite: off by default, because they cost generative model calls.

Models are named, not deployed, in the analyzer

The model block names a completion model and an embedding model. These are catalogue model names, not the names of your deployments, and they must be among the models the base analyzer supports. At runtime the service maps those names onto the deployments configured for your resource. That indirection is why the same analyzer definition can move between environments unchanged.

The embedding model matters only in specific circumstances — improving an analyzer with labeled samples — so a first custom analyzer that names only a completion model is perfectly ordinary.

How to read an unfamiliar definition

Given a definition you have never seen, work outside in. Look at the base identifier to learn the modality. Scan the config for switches that are unusual, because anything left out is at its default. Then read the field schema, which tells you what the analyzer is really for; the rest is machinery. Finally, note whether source and confidence estimation is on, because that single flag decides whether the output can be audited.

Creating the analyzer is a single call: you submit the definition to the analyzers endpoint under your chosen identifier, and the service returns a created response along with a header you can poll while the analyzer is built. From then on the identifier is the whole interface. Analysis requests name it and supply content; they do not resend the configuration.