Data in a template
A template does not query anything. It asks for an entity by name, gets an array, and echoes fields.
An entity is a file
data/service/branding.json is a Service. data('service/branding') returns it as a PHP array — @type, name, description, image, whatever it carries — localised to the language of the request, with @id and url derived. The path is folder plus file name; the folder is the type, lower-cased.
$service = data('service/branding');
echo e($service['name']);
An empty array means the entity does not exist — in no language it could fall back to; the shell answers with a 404. A slug map is read along the chain (regional variant → base → default), so an entity that exists only in en is filled when asked for under nl, with inLanguage: "en" and the English URL: a reference from a card links to the page where it does exist. For a page itself this never fires — the router resolved the exact slug before the shell runs. When you enumerate, filter with data_in_lang().
Language is resolved on read
An entity keeps its languages as layers inside itself: a translatable field is a small map, an invariant field a plain value.
{
"@type": "Service",
"identifier": "branding",
"slug": { "nl": "/diensten/branding", "en": "/services/branding" },
"name": { "nl": "Merkidentiteit", "en": "Brand identity" },
"price": "1200",
"image": { "@type": "ImageObject", "contentUrl": "/assets/images/branding.jpg" }
}
data() picks the language for every map it meets, at any depth, so the template only sees $service['name'] as a string. Languages are declared once, in config.php; any object whose keys are all declared languages is a map. Content falls back one step (regional variant → base → default); existence does not — the slug map decides. See Strings and languages.
locale_lang() gives the active language for <html lang> and your own formatters.
References are stubs, and you resolve them
An entity never embeds another entity. It points with a stub — type and identifier, nothing more:
"provider": { "@type": "Organization", "identifier": "braaf" },
"author": { "@type": "Person", "identifier": "joey" }
data_resolve($stub) loads the referenced entity at request time — no cache, no compile step. An overview reads rows, not files: rows('itemlist/service') gives the items of a curated list in its order (rows('service') every service in the index), each with the floor a card needs — loop, render a card per row, and an overview page is done; data($r['type'] . '/' . $r['id']) where a card needs the whole entity. See Overviews.
Because everything resolves on read, nothing is rebuilt when an entity changes: edit person/joey.json and every page that references Joey shows it on the next request.
Images
image is a URL string or an ImageObject with contentUrl and, ideally, name and caption. data_image_url($entity['image']) returns the URL either way. data_card_presentation($entity) returns the image URL plus a card’s colours — from the image when there is one, otherwise from the entity’s presentation block.
Those colours are content, written by whoever may write data. A shell that puts them in a style= attribute escapes and validates them as a colour (#hex, a known keyword); a raw echo into an attribute is an injection waiting to happen.
The one rule about echoing
e() on every field you echo, with one exception: content fields that carry HTML on purpose, such as articleBody, go through body():
<?php body($article['articleBody'] ?? ''); ?>
body() is the only place raw HTML reaches the page. It floors itself: markup with scripts, event handlers or dangerous URL schemes is refused and replaced by an HTML comment, live and in previews alike. An unescaped echo anywhere else is an audit finding: a key that may write content must never put active code on a visitor’s screen.
That is the whole rule — there is no separate escaper for URLs or for JavaScript, on purpose. A field that is a URL (url, sameAs, an image path) can never hold a script scheme: the engine refuses javascript:, vbscript: and data: URIs at the door, before a file enters data/, so <a href="<?= e($org['url']) ?>"> is safe as written. And data never ends up inside a <script>: that is what the site’s Content-Security-Policy forbids.
The functions.php habit
Anything a template would do twice belongs in theme/functions.php: a format_date($iso) in the active language, a schema_service($slug) wrapper around ld_entity('service/' . $slug), a breadcrumb builder. Keep the ISO value in the data and format on the way out — the machine views read the data.