Data conventions
Baseline rules for entities: correct Schema.org, resolvable on read, true structured data. A site’s per-type conventions live with the site.
Three identifiers, kept apart
| Field | Question | Form |
|---|---|---|
@id |
Which entity is this? — identity, deduplication | an IRI |
url |
Where can you see it? — location | an absolute URL |
identifier |
What do we call it? — the business id | a string, a PropertyValue, or an array of both |
@id and url are not in the file: they derive on read from the slug and the active language. identifier is the language-invariant key and equals the file name. An organisation’s is typically an array: the slug first, then external registrations (a chamber-of-commerce number) as PropertyValue.
The one stored url is the organisation’s own address — display, identity data. The site’s origin is a host fact, set by CTXR when the site is stood up: every canonical, @id and sitemap line is built on it, never on data. The organisation entity never leaves live; change it with update and publish.
Stubs
Every reference to an entity the site owns is a stub:
{ "@type": "Person", "identifier": "joey" }
In author, provider, publisher, relatedLink, mentions, in an offers.itemOffered — in any field, at any depth, always these two fields. An ItemList item is the one place a reference may carry more: the list’s own floor for it (below). Resolver rule: file = lower(@type) + "/" + identifier + ".json". No paths in @id, no custom keys like @ref, no inline copies. External references (a citation, a publisher on another platform) stay inline full objects.
In the output every stub, wherever it sits, becomes an {"@id": "..."} reference, and every fragment reference in any field — an author, an organiser, a performer, a brand — is harvested into the page’s graph when it names a person or organisation the site owns.
The @id patterns
@id is where the entity lives, not a formula.
| Entity | @id |
|---|---|
| Has its own page | the page URL |
| Shown on a host page | <host-url>#<fragment> |
| No page, still the site’s (organisation, website, a person, a review) | <base-url>/#<fragment> |
The invariant fragment field carries the fragment: with a slug a page anchor, without one an identity anchor. Home never carries one — it is the root by designation, not an anchor; the audit refuses it and the render ignores it.
Two rules. One entity, one @id, however many pages show it — two is duplicate content; and the reverse, one @id, one owner: two entities carrying the same fragment on the same host in one language are one node to a JSON-LD consumer, so the audit refuses it as it refuses two entities on one slug. Until a duplicate slug is fixed, the first claim keeps the address and the other has none — everywhere an address is printed: the page, the sitemap and the hreflang (the other is never advertised at the first one’s page), rows(), the feed, llms.txt, the search, /graph, /data* and a reference to it in the JSON-LD; in a preview, a slug a live entity holds stays its own, whatever a staged claim says — the preview shows what publish would keep. The organisation never shares the home page’s @id: same @id means same entity to a JSON-LD consumer. Hence /#organization, always.
Folder structure
data/
├── organization/ Organization (or a subtype such as ProfessionalService)
├── person/ Person — people named on the site (authors, reviewers, team); not users — keys live in .actors/, see Who can do what
├── webpage/ the home designation and pages about nothing in particular
├── service/ Service
├── blogposting/ BlogPosting
├── faqpage/ FAQPage
└── itemlist/ ItemList — curated order: a type's own list, or a free one (a menu); never a page
Folder = the Schema.org type, lower-case, singular — the type you refer with, not necessarily the entity’s own @type (a ProfessionalService file is addressed as Organization). One entity per file, carrying @context, @type, identifier and, for pages, slug. Item lists may be empty.
An item list is a steering hand, not a necessity: the site’s index is the floor every overview stands on (rows('service') lists every service, newest first), and a list is what you curate on top of it — itemlist/service when you want your own order, a free list — itemlist/menu, itemlist/featured, itemlist/recent-work — for anything you choose by hand; the theme names the one it renders. An entity that is in no list is not hidden: it is in the index, in the overviews that read the index, and on its own page — the organisation’s rating, too, counts every review in data/review/ about it, on a list or not. An item is itemListElement[*].item — an entry without a ListItem around it is not read — and it is one of two things, the same to every reader (rows(), the feed, llms.txt, ld_itemlist()). A reference carries @type (for a multi-type thing, its first type picks the folder) and an identifier that is a non-empty string: it names that entity, wherever the entity lives and in whatever languages it exists. What else it carries — name (or headline), description (or abstract), image, url — is the list’s own word for the entity (a menu’s “Contact” for the contact page) and lays over its row in an overview; the entity itself stays the entity: the feed and llms.txt show it in its own words, and ld_itemlist() names it by its @id. Anything else — no identifier, one that is a list, an object or a number, an @id alone — is a thing written in the list: {"@type": "Thing", "name": …, "url": …, "description": …, "image": …}, the fields as language maps where they differ, for what the site does not own as an entity: an outside link, a section heading in a menu. It stays as written; nothing resolves it. A reference whose entity does not exist in the page’s language is left out there — curate per language with a language map as itemListElement, or a written item. The audit and /graph read a list the same way: a reference to nothing is refused at publish, and so is an unpublish that would leave one behind; an entry without its ListItem, an identifier that is not a non-empty string, an @id alone, or a reference that carries more than the floor (a price, an author — those are the entity’s) draws a warning, because it reads otherwise than it looks.
A list is not a page. It is curation, and it claims no address: a slug on a list makes no page — the path answers 404, stays out of the sitemap and the hreflang, derives no @id or url, and a reference to the list has url null — and the audit warns about it. The page that shows a list is a thing of its own with a slug (a WebPage, a CollectionPage) whose template reads rows('itemlist/<name>'). A slug on a list still limits the languages the list exists in, as a slug map does on any entity — drop it; to curate per language, make itemListElement a language map.
The file name is data/<type>/<name>.json with <name> lower-case, starting with a letter or digit, then a-z 0-9 _ - — no dot (the resolver cannot load one, so the file would render and list nothing), no upper case. The MCP admits nothing else, and the audit flags a file outside it, live or staged: rename it — a staged one, discard and stage again under a clean name.
Languages are layers inside the entity: an object whose keys are all declared languages is a map, picked on read. The slug map enumerates existence: no key for a language, no page in it.
A live data/ folder is public; every entity is a member of the index (/data.json) and the graph, slug or no slug, and every file is an address: /data/<type>/<name>.json is the file itself, /data/<type>/<name>.md its reading in the page’s language. The prefix belongs to the files: a page cannot claim data or data/… as its slug — the audit refuses it. What must stay internal does not belong here.
Key order on disk: @context, @type, slug, fragment, identifier, name, description, the rest.
Canonical shape, no translation
Files are canonical Schema.org; helpers strip and reference, never translate property names. Taxonomy follows the type, not a private tags field: a Service uses category (it has no keywords), a CreativeWork and its subtypes use keywords.
Articles carry their full body as articleBody, an HTML string, so translating is a data operation. The page graph strips it — the page is the content; the index serves it (/data.json, the full form), which is where full-text search sits (?q=, or the MCP’s search), and the entity’s .md reading shows it as prose.
Render fields
Presentation lives with the entity, is not schema, and is stripped from the JSON-LD. Two layers:
"presentation": { "featured": false, "surface": "#0b0b0b", "ink": "#eeefeb", "shell": "campaign.php" }
featured: false keeps the image in the structured data but shows it nowhere. surface and ink tint a card without an image. shell designates a template.
"image": { "@type": "ImageObject", "contentUrl": "/assets/images/x.jpg", "name": "…", "caption": "…", "focus": "50% 30%", "surface": "#1a1a2e", "ink": "#fafafa" }
focus, surface and ink on the image are stripped; name and caption are schema properties with a render role — a hero shows them as title and description. A card reads its colours from the image, otherwise from the entity.
The schema helpers
| Helper | Returns |
|---|---|
ld_organization() |
the organisation with its aggregate rating (the reviews in data/review/ about it) |
ld_page($type, $overrides) |
the page bundle: organisation + website + page entity, in one @graph |
ld_entity($path) |
any entity, cleaned, ready to merge into the bundle |
ld_itemlist($name) |
an ItemList: per item the entity’s @id plus the list’s floor, or a written thing |
ld_faqpage($slug) |
a FAQPage |
ld_breadcrumb($trail) |
a BreadcrumbList from a [path => label] trail |
One @graph per page for the identity layer; separate scripts for item lists, FAQ and breadcrumbs. Plural means a list, singular entity or bundle. Thin type wrappers go in functions.php.
What is deliberately not done
No custom JSON-LD keys. No UUIDs as @id for public entities. No entities copied into lists. No compile step. No url or name on the website node — its @id sits on the site’s origin and every page names it through isPartOf; its name is the organisation’s, through publisher. No relative URLs in a stored url. No legalName equal to name. No multiple @ids for one thing.