# The vocabulary machines share Topic: [Machine-readable website](https://btlabs.dev/en/ai-website) > Schema.org is a dictionary, not a format. Why you cannot invent a property, and why markup may only state what the visible page states. 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](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data) 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?](https://btlabs.dev/en/posts/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: 1. **Does the declared type match the question you want to be found for?** Not the question you would ask, the one your customer asks. 2. **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. 3. **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](https://btlabs.dev/en/glossary/structured-data); which facts are worth declaring first, in [which facts should a machine be able to read about your business](https://btlabs.dev/en/posts/what-structured-data-to-add). --- Source: https://btlabs.dev/en/posts/schema-org-vocabulary-explained Last-Modified: 2026-10-05T07:00:01.938Z Languages: [de](https://btlabs.dev/llms/de/posts/schema-org-vokabular) · [it](https://btlabs.dev/llms/it/posts/vocabolario-schema-org) See also: [llms.txt](https://btlabs.dev/llms.txt) · [ai.txt (Policy)](https://btlabs.dev/ai.txt) · [identity.json](https://btlabs.dev/identity.json)