Structured Data Markup

What a machine sees when it opens your page

Open a service page and you read it in one glance. You know which number is the price, which line is the delivery time, which block is the address. None of that is obvious on the other side of the wire. A crawler or a language model receives one continuous stream of text in which a price and a phone number look exactly alike. Structured data markup exists to close that gap: it restates what the page already says, this time in a vocabulary a machine can read field by field.

That vocabulary is schema.org, a shared set of type and property names that search engines and answer engines agree on. When a page declares that it describes a service, that the provider is a named company, that the area served is a specific region, nothing changes visually. The visitor sees the same page. What changes is how little guessing the reading software has to do.

For years this work was justified by one thing only: the star ratings and price badges that appear in search results. That justification is now the smaller half. Systems that answer questions directly need to know which fact belongs to whom before they can put your information into an answer and name you as the source. This makes structured data markup one of the few concrete fixes for the problems described in our piece on why AI systems cannot read a website.

Four decisions before you write a single line

This looks like a coding task and is mostly a decision task. Writing the block takes half an hour. Deciding what belongs in it is the actual work, and the order of the decisions matters because each one narrows the next.

• What is this page? A company page, one service, one product, an article, a question-and-answer page. One primary type per page.
• What does that type expect? Every type has its own property set. A service has a provider and an area served; an article has an author and a publication record.
• Does the page actually contain those facts? Markup cannot add information that is not on the page. A property with no visible counterpart is left out.
• Where will the block live and who maintains it? Hand-written once, or generated from the page's own data on every render.

Teams that skip these questions arrive in the same place: half the site is marked up, half is not, and part of what exists contradicts the page it sits on. Keeping the order costs an afternoon. Skipping it costs a cleanup project later.

Choosing the right type

The list of types is enormous and almost irrelevant. Most sites are served by five or six of them.

• Organization — the company itself: legal name, one address, contact channels, logo, the external profiles that represent it. Defined once for the whole site.
• LocalBusiness — used when customers physically come to an address, adding opening hours and location.
• Service — one block per service page, built around the provider, the service type and the area served.
• Product — for concrete items with a price, a currency and an availability state. If the page carries no price, do not force this type.
• Article and FAQPage — the blog post and the questions that close it.
• BreadcrumbList — where the page sits in the site. Small, and the thing that feeds the path shown under a result.

There is one test for the choice: what does the page promise a visitor? Labelling a service page as a product, or stacking several types onto one page hoping something sticks, produces confusion rather than reach. When a page genuinely needs two types, they are declared as separate blocks that reference each other rather than nested into one another.

Once the type is settled, the hardest part of structured data markup is behind you. What remains is filling declared properties with facts that already exist on the page. If you cannot decide what type a page is, the page is probably unclear to human readers too; fix the content first and let the markup follow.

Required, recommended, and the properties you should leave empty

Property lists are not shopping lists. Sorting them into three groups makes the work manageable. Required properties are the minimum that makes the type meaningful at all. Recommended properties are filled in when the page has a counterpart for them, and they make the resulting answer richer. The third group is the one that gets ignored: properties with no counterpart on the page. Those stay empty.

That third group is where most implementations break. Declaring a price the page does not show, inventing a rating no one submitted, listing reviews that were never collected — these are not merely policy violations. They are trust failures, and a system that finds one contradiction on a site tends to discount the rest of that site's declarations as well. The honest one-line answer to how structured data markup should be written is this: repeat what the page says, exactly as it says it.

Copy the values from the page rather than rewriting them. If the service is called one thing on screen, the markup carries that same name, not a shortened or polished variant. Every difference between the two is a seam where one will be updated and the other forgotten.

Where the structured data markup block goes

Three placement formats exist and in practice only one is worth using: JSON-LD. It carries the declaration as an independent block, separate from the visible HTML. The other two scatter attributes through the markup that renders the page, so every redesign breaks them. A JSON-LD block survives a redesign untouched.

Whether the block sits near the top or the bottom of the document is technically irrelevant. What matters is that every page has one and that it belongs to that page. The most common failure is a block hard-coded into a template: correct for the one page it was written for, then copied verbatim onto hundreds of pages that now all claim to be that page. The correct construction generates the block from the page's own record — title from the title field, description from the description field.

If the site has any content management layer, bind the markup to it rather than writing blocks by hand. New pages then arrive already described and nobody has to remember anything. This is the same principle behind the llms.txt file we wrote about separately: the machine-facing layer should be a natural output of the system, not an attachment that needs manual care.

Structured data markup in the first pass: which pages to start with

Rather than attempting the whole site in one weekend, begin with three groups: the page that defines the company, the service or product pages that earn money, and the handful of articles that receive steady traffic. Those three cover most of the available benefit. The rest follows on its own once the template construction is in place.

Validate instead of eyeballing

A block can look correct and do nothing. One missing comma makes the whole declaration invalid, and the page keeps rendering normally without a single warning. Validation is therefore not an optional final step; it is part of the job.

Three checks are enough. First, open the raw source of the published page and confirm the block is actually there — markup injected later by client-side code is invisible to many of the systems you are trying to reach. Second, run the block through a validator to catch format errors. Third, compare the declared values against the rendered page: is the name, the price, the description in the block the same as the one a visitor sees? That third check catches the expensive mistakes no automated tool will flag.

One expectation needs correcting here. Structured data markup does not guarantee rich results in search. It only makes that presentation possible. The decision still rests on the page's own quality, speed and credibility.

Define the company once, and consistently

Under the page-level declarations sits a layer most sites never build: the company itself. Marking up individual services while never describing the organisation is like writing a document that says "we" in every sentence and never gives a name. The organisation is declared once, and every other block points to it as the provider.

That declaration holds the legal name, a single address, verifiable contact channels, the logo, and the external addresses that represent the company — corporate social profiles, business registrations, industry directory listings. Those external addresses matter more than they look: they are the only signal that ties this website and that account to the same organisation. Without the tie, every source stands alone and none of them reinforces the others.

The quiet failure here is inconsistency: one legal name in the footer, a different spelling on the contact page, a third variant in the declaration. A human reconciles these instantly. A machine has no obligation to. Before starting on structured data markup, confirm that the company name, address and phone number are written identically everywhere they appear. That check is cheaper than the corrections it prevents.

Six mistakes that show up in almost every audit

• Template-frozen blocks. Hundreds of pages declaring the same title and description, which reads as one page repeated many times.
• Facts that are not on the page. A price in the declaration, none on screen. The mismatch can cause the entire block to be disregarded.
• The wrong type. A product label on an article, a single-product label on a category listing.
• A scattered identity. The company described slightly differently on every page, so the pieces never assemble into one organisation.
• Dead references. The logo, image or page address in the block no longer resolves. The block is valid and points at nothing.
• Blocks that outlive the page. The price list is updated, the declaration keeps announcing the old figure.

All six come from missing ownership rather than carelessness. If nobody is responsible for updating the declaration, it stays a photograph of the day it was written. Assigning structured data markup to a named person, even for ten minutes a month, prevents all six.

What to measure after it ships

The first disappointment is that nothing happens the next morning. Pages have to be recrawled, declarations processed, and any new presentation enabled. During that period the right indicator is not ranking but whether pages are being processed without errors; expecting a change in appearance before the error count reaches zero is premature.

The second measurement area is newer: are answer engines naming you as a source? That behaviour is separate from search ranking and has to be measured separately. We set out the method in our piece on how AI visibility is measured, and structured data markup is one of the technical items where improvement is reasonable to expect.

Keep the measurement window wide. Reading the effect of a markup change over a few days mostly means reading seasonal noise. Record the date of the change and compare two windows of several weeks each.

Maintenance, scale, and when to bring in help

This is the quietest layer of a website. When it breaks, pages still load, no error appears, nobody complains. So maintenance has to be scheduled rather than noticed: when a price changes, when a service scope is revised, when an address or phone number is updated, the declaration is updated in the same pass. Template-generated constructions do this by themselves. Hand-written blocks do not.

Scale decides the rest. On a thirty-page site you can inspect every block by hand. On three hundred pages you cannot, and the work shifts from editing pages to changing how pages are produced. Inherited sites add their own problem: it is common to find three contradicting layers of declarations on an older site, and the first task is deciding which one survives. Our technical search optimisation work runs that sweep as a standing item and reports the errors back to whoever owns the page.

The honest summary is that structured data markup is not a one-time installation recipe but a small habit of keeping a page and its machine-readable counterpart in step. Setup finishes in a day; the value only appears when it is sustained. If you want to see how your site currently reads to a machine before deciding anything, our AI visibility service page lists what gets checked and what the report delivers.