{"canonical_url":"https://engineer.company/glossary/structured-data/","content_markdown":"# Structured data\n\n## What it is\n\nA company's contact page says in a sentence where the office is; structured data\nsays it again as a `PostalAddress` with a street, a postcode and a country, so\nthat a program reading the page has no need to guess which word is the town. It\nis the practice of repeating what a page states in prose as typed statements in\na vocabulary that publishers and consumers agree on, so that search engines and\nother software can read the facts without interpreting the layout.\n\nThe vocabulary is usually schema.org, which Google's documentation names as the\none most structured data for its search uses. Google, Microsoft, Yahoo and\nYandex founded it, and since April 2015 a W3C community group has been its main\nforum. It defines types, such as `Organization`, `Person`, `Service`, `Review`\nor `DefinedTerm`, and the properties each one can carry, such as `name`,\n`address`, `author` or `price`.\n\nThe statements can be written in three syntaxes. Microdata and RDFa add\nattributes to the visible HTML elements themselves. JSON-LD keeps the statements\napart, as a block of JSON in a `script` element of type `application/ld+json`,\nand is a W3C Recommendation in its 1.1 version, published on 16 July 2020.\nGoogle accepts all three equally and recommends JSON-LD as the easiest to\nmaintain at scale.\n\n```html\n\u003cscript type=\"application/ld+json\"\u003e\n    {\n        \"@context\": \"https://schema.org\",\n        \"@type\": \"Organization\",\n        \"@id\": \"https://example.com/#organization\",\n        \"name\": \"Example Ltd\",\n        \"url\": \"https://example.com/\"\n    }\n\u003c/script\u003e\n```\n\nThe line that matters most in that block is `@id`. JSON-LD uses it to identify a\nnode, and a node without one is a blank node, with no document-independent\nidentifier. Blank-node identifiers can be shared by blocks within one document.\nWith a globally usable identifier, any other block on any other page can\nwrite `\"publisher\": {\"@id\": \"https://example.com/#organization\"}`, which the\nspecification calls a node reference: a pointer to a thing described elsewhere,\ninstead of a fresh description of it. Identifiers are what turn a scatter of\nblocks into one graph.\n\nThe neighbouring term is metadata. The title, the description and the Open Graph\ntags in a page's head describe the page as a document, while structured data\ndescribes the things the page is about: the company behind it, the person who\nwrote it, the service it offers or the word it defines.\n\n## Why it matters\n\nThe decision is how much to say, and the honest answer is usually less than the\nvocabulary allows, but complete. Nothing in the syntax stops a publisher from\nfilling in every property schema.org offers. Google's own guidance points the\nother way: supply fewer recommended properties, complete and accurate, rather\nthan every possible one with partial or wrong data, and mark up nothing a reader\ncannot see on the page, even when it is true.\n\nThe reason is that every marked-up fact is a second copy of something the page\nalready says, and a second copy can drift. A price edited in the visible table\nand forgotten in the JSON, a rating that appears only to machines, an address\ntyped slightly differently on each page: each makes the page say one thing to\npeople and another to programs. The cost of structured data lies less in writing\nit than in keeping it true, so the useful questions are which statements the\npage can stand behind and whether they come from the same source as the visible\ntext.\n\nWhat it buys is legibility. An engine or an agent that can join a hundred\nmentions into one company knows more than one reading a hundred unrelated names.\nPages that follow the guidelines may become eligible for rich results, listings\nwith extra detail, though eligibility guarantees none. What changes is how well\na machine understands what the page is about.\n\n## What it looks like in practice\n\nThe site's credits\n[commit it to marking only what is true and visible on the page](/credits/), and\nthe history of its structured data shows why that sentence needed writing down.\n\nBefore the July 2026 rework,\n[963 blocks restated the company 1,671 times, with no stable identifier anywhere](/portfolio/replaced-963-metadata-blocks-with-one-graph/),\nso no consumer had grounds to treat the organisation on one page as the\norganisation on another. The graph now rests on three identifiers minted from\nthe site's origin, for the organisation, the website and the founder, and every\nother block refers to them by `@id` instead of describing them again. The\nidentifiers are the same in every language: a comment in the template explains\nthat a separate Danish identifier would declare a second organisation with the\nsame company registration number. Sixteen types were recorded at that stage,\nand lists named their items by URL alone, because writing out the 107 entries\nthen on the portfolio index would have made the compressed page 52 per cent\nheavier.\n\nSeveral facts are read from the same source as the visible page. Service prices\ncome from the same data file as the prices on screen, so a machine and a reader\nare quoted the same rate. The period a piece of work covers comes from the\npartial that writes the sentence about it. Breadcrumbs follow the visible trail,\nand list positions follow the order on screen, never a ranking published only to\nmachines. The page's own node uses the same address as its canonical link, so\nthe markup and the head make one claim.\n\nThe refusals are as deliberate as the statements. The company's own write-ups of\nits work are not marked up as reviews, because that would invent an author for\nits own words. The testimonial template uses Review nodes only for entries published with granted consent, without adding a rating. Each glossary page, this one included, carries a `DefinedTerm`\nwhose description is the one-line gloss shown in the list, so the definition a\nmachine reads is the one a reader sees.\n\nA check over the built site asserts that every block parses, that every\nidentifier resolves, and that every URL the graph names was built, so a graph\npointing at a page that does not exist fails the gate. The same credits page\nlists the Schema Markup Validator for reading the data and Google's Rich Results\nTest for seeing what one engine does with it.\n\n## Where it goes wrong\n\n**Rich results stay out of reach although every validator passes.** The markup\nis valid JSON-LD and uses real schema.org types, yet the page keeps appearing as\na plain result. The data describes things a reader cannot see, such as a rating\nnobody gave, questions hidden from the page or a price that differs from the one\non screen, and Google warns that markup breaking its guidelines may leave a page\nineligible, however clean the syntax. Mark up only what the page shows, and\ngenerate both from one source so they cannot part.\n\n**Hundreds of blocks describe one company, and nothing joins them.** Every page\nrepeats the organisation's name, logo and address, sometimes with small\ndifferences, and correcting one detail means finding all of them. The nodes are\nanonymous, or each page and each language mints its own identifier for the same\nentity. Give every real thing one `@id` built from a stable URL with a fragment,\ndescribe it once, and refer to it everywhere else.\n\n**One template change breaks the markup on every page at once.** A stray quote,\na trailing comma or an empty value turns every block invalid, and consumers can\nuse none of it. Google's guide warns that templating can break markup after\ndeployment. The JSON was assembled as text, with values pasted between braces,\nso a missing field leaves an empty string or a broken structure. Build the\nstatement as a data structure and serialise it, as this site's templates do with\nHugo's `jsonify`, omit properties that have no value instead of emitting them\nempty, and parse every block in the built output.\n\n**The graph names pages that are missing.** URLs in the markup lead to a 404, a\nstaging host or a mirrored copy. The addresses were typed by hand or built by a\ndifferent rule from the links and the canonical. Derive every URL in the markup\nfrom the same function that produces the page's canonical address, and check\nthat each one was built.\n\n## Further reading\n\n- [schema.org](https://schema.org/) — the shared vocabulary of types and\n  properties, with a page for every type.\n- [JSON-LD 1.1](https://www.w3.org/TR/json-ld11/) — the W3C Recommendation for\n  the syntax, including node identifiers and node references.\n- [schema.org: DefinedTerm](https://schema.org/DefinedTerm) — the type each\n  glossary page uses to describe the word it explains.\n- [Google Search Central: introduction to structured data](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data)\n  — the three syntaxes, the visibility rule and how rich results are tested.\n- [Schema Markup Validator](https://validator.schema.org/) — reads any page's\n  structured data against the schema.org vocabulary.\n\n\u003chttps://engineer.company/glossary/structured-data/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"How structured data restates a page's facts in a shared vocabulary, why stable identity matters more than volume, and the markup that does harm.","formats":{"gemtext":"https://engineer.company/glossary/structured-data/index.gmi","gopher":"https://engineer.company/glossary/structured-data/gophermap","html":"https://engineer.company/glossary/structured-data/","json":"https://engineer.company/glossary/structured-data/index.json","markdown":"https://engineer.company/glossary/structured-data/index.md","pdf":"https://engineer.company/glossary/structured-data/index.pdf"},"kind":"page","language":"en","title":"What is structured data?","url":"https://engineer.company/glossary/structured-data/","version":1}