Versions and groups

Flat specs cover one current API surface. Real products often need more: released versions readers can switch between, or several related groups under one roof. A reference uses exactly one of the three shapes.

Versions

{
  "product": "payments",
  "label": "Payments API",
  "versions": [
    {
      "id": "v71",
      "label": "v71 (latest)",
      "default": true,
      "specs": [{ "spec": "payments-v71.json", "useFirstTagOnly": true }]
    },
    {
      "id": "v70",
      "label": "v70",
      "specs": ["https://specs.example.com/payments-v70.json"]
    }
  ]
}

Behavior worth knowing:

• The default version owns the bare URL (/payments/api-reference); other versions nest under their id (/payments/api-reference/v70). Mark at most one default: true — otherwise the first entry wins.
• Dropdown order is config order; label defaults to the id.
• Old versions announce themselves — readers on a non-default version see a notice with a one-click path to the latest.
• Canonical SEO is automatic: only default-version pages enter the sitemap, so old versions never compete with current docs in search.
• A version can merge multiple specs, and each spec entry takes all the usual per-spec options.

Groups

Groups present several sub-references with a switcher — right for products that are a family of surfaces rather than a line of versions:

{
  "product": "terminals",
  "label": "Terminals API",
  "groupDisplay": "dropdown",
  "groups": [
    { "id": "terminal-api", "label": "Terminal API", "category": "Devices",
      "specs": [{ "spec": "terminals.json", "useFirstTagOnly": true }] },
    { "id": "management", "label": "Management", "category": "Devices",
      "specs": ["management.json"] },
    { "id": "integration", "label": "Integration guides", "specs": [] }
  ]
}

• Each group mounts at /{product}/{section}/{id}/....
• groupDisplay chooses the presentation: "dropdown" (default) shows one group at a time behind a switcher — with options organized under each group's category heading — while "list" stacks all groups as sidebar sections at once. Dropdown suits many/large groups; list suits a few small ones.
• "specs": [] is a legitimate group — an MDX-only group whose pages come entirely from your content folder (content/docs/terminals/api-reference/integration/...). Use it for integration guides that belong inside the reference.
• The same spec file may appear in multiple groups and renders consistently in each.

Choosing between them

Ask what the switcher means to your reader. If the options are points in time — v70 was current, v71 is — use versions and get the outdated notice and canonical-URL handling for free. If the options are different things that coexist — devices, regions, audiences — use groups. If you need both dimensions, split by product: products are the outermost switcher.