The vocabulary machines share
Florian Berger · Oct 5, 2026
Topic: Machine-readable website
Twenty years ago, web developers argued about whether a page should be built with tables or with stylesheets. The argument felt important at the time. It was, in the end, about how something looked.
The question that matters now is a different one, and it is older than the web: what do we call things, so that someone else knows what we mean?
A vocabulary, not a format
Most explanations of schema.org start with the format — the block of code, where it goes, which syntax. That is the least interesting part, and it is why so many implementations end up technically valid and practically useless.
Schema.org is a vocabulary. It is a public, finite list of things that can exist — a person, a place, an opening time, a job posting, a recipe — and of properties those things can have. Search engines agreed on it so they would not each need their own dictionary. That is the whole idea.
Which means the real work is not writing the block. It is choosing the right word from a list somebody else wrote.
The list is finite, and that is the point
Here is what people find hardest to accept: you cannot invent a property.
If your business has something genuinely unusual — a certification nobody else holds, a service that does not map onto any existing category — the temptation is to make up a name for it and mark it up anyway. It looks harmless. The block is still valid. Nothing errors.
But a made-up property is a word in a language nobody speaks. No consumer reads it, because no consumer was built to look for it. You have written something true into a place where it cannot be heard.
The honest alternative is to leave it out and put it in the visible text, where a human reader — and a language model reading the running text — will find it.
The rule we apply to ourselves
We have a working rule for this, and it is stricter than what the standard requires: every field must have been decided about. Either it maps to a real property, or there is a written reason why it does not.
"No place in the vocabulary" is a valid reason. Inventing one is not.
That rule exists because the alternative is worse than incompleteness. A vocabulary you half-respect produces markup that looks thorough and is quietly wrong — and wrong markup is harder to find than missing markup, because nothing complains.
Marked up is not the same as true
The second rule comes from Google directly, and it is the one most often broken: markup may only contain what is visible on the page.
Google's structured data documentation puts it plainly: "Don't add structured data about information that is not visible to the user, even if the information is accurate."
Read that last clause again. Even if the information is accurate. You are not allowed to declare a true fact that the visible page does not state. Not because it would mislead a reader, but because markup is a claim about the page — not about the world.
This is where most well-meant implementations go wrong. Somebody knows the business is open until six, the page says five, and the markup gets the "correct" value. Now the two disagree, and the machine believes the declared one.
What this looks like in practice
Three consequences, none of them technical:
Choose the type before the properties. Which kind of thing your business is decides which properties are even available to you. I wrote about that separately — what are you, to a machine? — because it is the decision that comes first and gets made last.
Generate, do not maintain. If the markup is written by hand, it is a copy of the page, and copies drift. If it is derived from the same data the visible page renders from, the two cannot disagree — there is no second place for them to disagree in.
Fewer properties, kept current, beat more properties, written once. This is not modesty. It is that stale markup is actively worse than absent markup: it makes a confident claim that happens to be false.
A typical mistake, worked through
Take a hotel with a restaurant that never appears when people search for somewhere to eat nearby. The markup is there. It was written by a competent developer. And it says, in the vocabulary's terms, hotel.
Nothing about that is false. The business genuinely is a hotel. But a machine handed the question "where can I eat tonight" looks for things that are restaurants, and this one has declared itself something else — accurately, and unhelpfully.
The fix takes a minute: declare both, and put the restaurant first for the pages about the restaurant. No new content, no redesign. All that changes is one decision about which word goes first.
There is a pattern in that. Not missing markup, not broken syntax — a true statement that answers a different question than the one being asked.
How to tell whether yours is any good
Three questions, none of which require reading code:
- Does the declared type match the question you want to be found for? Not the question you would ask, the one your customer asks.
- Does every declared value appear in the visible text? If not, one of the two is wrong, and you cannot tell which from the outside.
- When did it last change? If the answer is "when the site was built", it describes a business that existed then.
The third question is the one that catches most sites. Markup does not decay visibly. It just stops being true, quietly, one detail at a time.
What I am not claiming
I do not think schema.org markup improves rankings on its own. There is no solid evidence for that, and I am suspicious of anyone selling it.
What it does is narrower and more useful: it removes the guesswork. A machine that finds a declared opening time does not have to parse a sentence and hope. That is not a ranking factor — it makes being quoted correctly more likely than being quoted approximately.
And for questions where being approximately right is the same as being wrong — when you are open, what you charge, whether you cover a particular valley — that difference is the whole game.
What structured data is in general is explained in Structured data; which facts are worth declaring first, in which facts should a machine be able to read about your business.
Frequently asked questions.
Can an AI confuse my business with another one?
Yes, and it happens more often than people assume. AI systems map a name onto an entity — a single unambiguous thing in their model of the world. If the name is shared, or the data about it contradicts itself, statements land on the wrong company: someone else’s opening hours, someone else’s services, someone else’s reviews.
We know this from our own experience. Our name is held by several organisations worldwide, among them an AI company of the same name. Searching for the short form, we rank only sixth; for the full name, first — a snapshot, not a fixed value.
There is no trick for this, only unambiguity: the same spelling of name, address and phone number everywhere, machine-readable company details on your own site, and cross-references between the profiles that genuinely belong to you. The clearer the signals, the harder the confusion. A single entry is not enough — it is the sum that counts.
How do I keep opening hours and contact details up to date everywhere?
The core principle: one source instead of many copies. If opening hours, address and phone number are maintained in one central place, and the website, structured data and machine-readable formats automatically serve the same state, nothing can drift apart. That is exactly what a website built as a single source of truth delivers: change it once, current everywhere.
Externally, the effort stays manageable: above all, keep your Google Business Profile and the most important directories up to date — with exactly the same details as on your website. For seasonal hours, a fixed routine helps, say at the start and end of the season. The background: contradictory details are the most common reason AI assistants tell people wrong things about a business.
