What is a SiteSpec — the JSON document a site actually is

A SiteSpec is the JSON document a website is stored as. Not a build artefact, not a cache, not an export: the thing itself. When you describe a site to the builder, when you edit it in the studio, and when a renderer serves it, all three read the same document.

The name comes from specification. It specifies what the site contains — not how it was built, and not what a particular framework should do with it.

What it holds

The document is small and closed: ten top-level fields, and nothing else is read.

• name — what the site is called.
• theme — typography, colour, radius, mode, and any scoped CSS override.
• pages — each with a route, a locale, and an ordered list of sections.
• collections — typed content rows, with their field definitions.
• forms — site-level form definitions, referenced by the form sections

that use them.

• header, footer, floats — the chrome around the pages.
• seo — the search settings.
• locales — the base language, and the languages it is translated into.

Every field a renderer touches is validated. Everything else is ignored, on purpose: the document is written by a language model, and the contract's job is to make a malformed document fail loudly at the boundary rather than render as a blank page.

The section vocabulary

A page is a list of sections, and the sections come from a registered set of twenty-four kinds: hero, features, richText, gallery, pricing, faq, contact, cta, stats, testimonials, team, collection, form, logos, timeline, video, banner, comparison, codeSnippet, splitFeature, menu, location, booking, marquee.

It is a closed set, and that is the point. A page is not a composition of arbitrary HTML — it is a list of known shapes, which is what lets a renderer be deterministic, and what lets a validator tell you that a section kind does not exist before the page is published rather than after.

Why a document and not generated code

text
                         one document
                      ┌──────────────┐
                      │   SiteSpec   │
                      └───────┬───────┘
                              │
            ┌─────────────────┼─────────────────┐
            │                 │                 │
       the builder        the studio       the renderer
        writes it          edits it         serves it

Because code has to be run, and running it means choosing a runtime, a framework, and a version of both — and then maintaining that choice forever. A document has to be read, and every reader can be swapped without the document changing.

That is the whole reason a studio edit and a chat regeneration can never disagree about what the site contains: they are not two descriptions of the site, they are two views of one document.

What it buys you

Three things follow from the shape:

1. Portability is a compile, not a rescue. The same document that renders

on our edge is open JSON, and its live content is readable over a public API without a key. Nothing is unlocked, because nothing was ever locked, and the portability guide is what replaces the button.

1. Diffable. A change to a site is a change to a document, so it reviews,

versions, and merges the way the rest of your code does.

1. Portable between renderers. The studio preview and the tenant worker are

two readers of one format, and a build you run yourself is a third — not three implementations that have to be kept in agreement.

How you get the document out

Three ways, and none of them costs anything:

• The studio's Code panel is a copyable JSON view of the document itself.
• The public API reads it: collections, their field definitions, and their

published rows, without a key and without a login. Drafts are not public, and never were.

• A build you made elsewhere is served from the same edge, so a static

bundle is a first-class citizen here rather than an afterthought.

The portability guide is the full procedure, and what happens to my website if I cancel is the same question from the other end.

The honest limit

A SiteSpec describes the site Zeso can render. It is not a general web platform: a section type that is not registered does not render, and a collection row whose field is not typed does not appear. The format is closed, which is what makes it deterministic — and a closed format is a boundary, not an infinite one.