A single source of truth for site structure

StructureSpec is an open standard for defining a site's structure as machine-readable JSON. The sitemap, page archetypes, navigation, and routing — all in one canonical file, composable from BlockSpec primitives and themed by BrandSpec tokens.

A StructureSpec file is a single .json document describing one site's structure. It references BlockSpec items by slug and is themed at render time by a BrandSpec.

1. Define the sitemap

   Map out the site as a tree of pages. Each node has a slug, title, and an archetype reference — pointing at the archetype that describes its block sequence. Children nest recursively.

2. Define the archetypes

   An archetype is a reusable sequence of BlockSpec items. A "Marketing landing" archetype might list hero → feature-grid → testimonial → cta; a "Narrative page" archetype might list page-header → rich-text → image-gallery → cta. Archetypes are referenced by slug from the sitemap.

3. Compose navigation and routing

   Primary, secondary, and footer navigation reference sitemap nodes by slug. Routing rules define URL patterns and any redirects. Both stay in sync with the sitemap because both reference the same slug graph.

4. Generate the site

   A consumer reads the StructureSpec and produces pages, navigation, and routes. Each page is rendered by walking its archetype's block sequence, pulling each BlockSpec for its contract, and applying BrandSpec tokens at render time.

A StructureSpec document is a JSON object with a root structure key and six top-level sections. Sitemap and archetypes are the minimum viable spec; the rest are recommended for complete site definition.

Sitemap node fields

Archetype block reference fields

Each item in an archetype's blocks array references a BlockSpec by slug, optionally constraining which variant, surface, or layout to use in this position.

A condensed StructureSpec for a small marketing site with a homepage, an about page, a services landing with two child pages, and a contact page. All fields shown are part of the v0.1.0 schema.

{
  "_export": {
    "siteName":            "Example Site",
    "structureSpecVersion": "0.1.0",
    "exportedAt":          "2026-05-02T10:00:00.000Z"
  },

  "structure": {

    /* ── Identity ────────────────────────────── */
    "identity": {
      "name":        "Example Site",
      "slug":        "example-site",
      "description": "Marketing site for a purpose-led services brand.",
      "version":     "1.0.0"
    },

    /* ── Sitemap ─────────────────────────────── */
    "sitemap": [
      {
        "slug":      "home",
        "title":     "Home",
        "archetype": "marketing-landing",
        "status":    "live"
      },
      {
        "slug":      "about",
        "title":     "About",
        "archetype": "narrative-page",
        "status":    "live"
      },
      {
        "slug":      "services",
        "title":     "Services",
        "archetype": "category-landing",
        "status":    "live",
        "children": [
          {
            "slug":      "strategy",
            "title":     "Strategy",
            "archetype": "service-detail",
            "status":    "live"
          },
          {
            "slug":      "design",
            "title":     "Design",
            "archetype": "service-detail",
            "status":    "live"
          }
        ]
      },
      {
        "slug":      "contact",
        "title":     "Contact",
        "archetype": "contact-page",
        "status":    "live"
      }
    ],

    /* ── Archetypes ──────────────────────────── */
    "archetypes": [
      {
        "slug":        "marketing-landing",
        "name":        "Marketing landing",
        "description": "Homepage and top-of-funnel pages.",
        "blocks": [
          { "block": "hero",          "variant": "split",        "required": true  },
          { "block": "feature-grid",  "variant": "three-column" },
          { "block": "testimonial" },
          { "block": "cta",           "variant": "centered",     "surface": "accent" }
        ]
      },
      {
        "slug":        "narrative-page",
        "name":        "Narrative page",
        "description": "Long-form pages — about, manifesto, story.",
        "blocks": [
          { "block": "page-header", "required": true },
          { "block": "rich-text",   "required": true },
          { "block": "image-gallery" },
          { "block": "cta",         "variant": "inline" }
        ]
      },
      {
        "slug":        "category-landing",
        "name":        "Category landing",
        "description": "Parent page introducing a group of child pages.",
        "blocks": [
          { "block": "page-header", "required": true  },
          { "block": "child-grid",  "required": true  },
          { "block": "cta" }
        ]
      }
    ],

    /* ── Navigation ──────────────────────────── */
    "navigation": {
      "primary": [
        { "slug": "about" },
        { "slug": "services", "includeChildren": true },
        { "slug": "contact" }
      ],
      "footer": [
        { "slug": "about" },
        { "slug": "services" },
        { "slug": "contact" }
      ]
    },

    /* ── Routing ─────────────────────────────── */
    "routing": {
      "trailingSlash": false,
      "redirects": [
        { "from": "/old-services", "to": "/services", "status": 301 }
      ]
    },

    /* ── Metadata ────────────────────────────── */
    "metadata": {
      "name":        "Example Site",
      "version":     "1.0.0",
      "lastUpdated": "2026-05-02T00:00:00.000Z"
    }

  },

  "$schema":  "https://structurespec.org/schema/v0.1/structurespec.json",
  "version":  "0.1.0"
}

StructureSpec is designed to be consumed by any tool that needs a structured site definition — page generators, CMS scaffolders, navigation builders, sitemap.xml exporters. Below are reference patterns for the most common outputs.

Generate pages from archetypes

Walk the sitemap, look up each node's archetype, and render the block sequence in order. Each block reference resolves to a BlockSpec for the contract.

// Render every page in the sitemap
const spec = await fetch('/structurespec.json').then(r => r.json());
const archetypes = new Map(
  spec.structure.archetypes.map(a => [a.slug, a]).filter(Boolean)
);

function renderNode(node) {
  const archetype = archetypes.get(node.archetype);
  const blocks    = archetype.blocks.map(renderBlock);
  return { slug: node.slug, title: node.title, blocks };
}

const pages = walkSitemap(spec.structure.sitemap, renderNode);

Generate navigation from sitemap slugs

Navigation references nodes by slug, so the navigation stays in sync with the sitemap automatically. No drift, no orphan menu items.

// Build the primary navigation tree
function findNode(tree, slug) {
  for (const node of tree) {
    if (node.slug === slug) return node;
    if (node.children) {
      const hit = findNode(node.children, slug);
      if (hit) return hit;
    }
  }
}

const primaryNav = spec.structure.navigation.primary.map(item => {
  const node = findNode(spec.structure.sitemap, item.slug);
  return {
    label:    node.title,
    href:     `/${node.slug}`,
    children: item.includeChildren ? node.children : []
  };
});

Export to sitemap.xml

The sitemap tree maps directly to the sitemaps.org XML format, with status filtering to exclude drafts and archived pages.

// Generate sitemap.xml from StructureSpec
function flattenSitemap(tree, base = '') {
  return tree.flatMap(node => [
    { url: `${base}/${node.slug}`, status: node.status },
    ...(node.children ?? []).flatMap(c =>
      flattenSitemap([c], `${base}/${node.slug}`))
  ]);
}

const urls = flattenSitemap(spec.structure.sitemap)
  .filter(u => u.status === 'live');

StructureSpec is designed to be standards-aware. It builds on, references, and is interoperable with several established frameworks. It is not a replacement for any of them — it is a structured layer that makes them composable in a single, machine-readable file.