Comparison pages

A Comparisons space is the page every product site writes — "Us vs Them", "The best X alternatives", "The best tools for Y" — built so that a fact is written once. The products, the criteria and the value of each product on each criterion live in one catalog; a comparison is a page that picks from it. Correct "Coda has SSO" in the catalog and every page that shows the cell is corrected, the freshness list knows when each fact was last checked, and the structured data a search engine reads is built from the same numbers the table shows.

Create one like any space:

POST /orgs/{orgId}/spaces
{ "name": "Comparisons", "slug": "compare", "type": "COMPARE", "visibility": "PUBLIC", "preset": "product" }

The type's name is COMPARE. GET /space-types/COMPARE publishes everything the type declares — its presets, the written sections, the settings it reads and its reader prefix. On your own domain it answers at its slug (acme.com/compare); on our address its prefix is /vs/.

The shape of it

A comparison is an ordinary page: revisions, drafts, scheduling, translations, SEO fields and the sitemap come with it.

Set it up in the studio

The first section of a new Comparisons space is Set up your comparisons. Four answers:

1. The kind of site — product site (head-to-heads lead), directory (search and a product grid first) or review publication (roundups lead).

2. Your product — paste its website and the name, logo, tagline and description are read from the site's own metadata (nothing is invented; what was found is listed). Tick "I have no product of my own" for a roundup site.

3. Your rivals — add each by its website.

4. What buyers weigh — name the category and start from a set of criteria (business software, project management, developer tools, e-commerce, marketing) or from nothing. Running it again adds only what is missing.

It can also draft a versus page for each rival. Everything it writes is ordinary catalog data, so nothing here is a mode you are stuck in.

The catalog

GET|PATCH /orgs/{orgId}/spaces/{spaceId}/compare/catalog reads and writes it. PATCH merges per top-level key (a key sent as null is removed) and answers 422 naming the product or criterion that does not resolve; ?dryRun=true shows the diff without writing. The answer carries catalog (this space's own), effective (what readers see, after catalogFrom) and source.

Products — products[] (up to 200)

A price period is month, year, once, seat-month, seat-year, usage or custom. A plan with amount: null is "no public price" — never read as free. Prices are made comparable (a monthly equivalent per seat) but are never converted between currencies.

Criteria — criteria.groups[]

A group is {id, label, description, labels, criteria[]} (up to 50 groups and 500 criteria). A criterion is:

Values — values.<product>.<criterion>

A cell is {level, value, note, plan, source {label, url}, verifiedAt, labels}. level is yes, partial, no, addon, planned or unknown; value is typed by the criterion's kind (a boolean, a number, an option id, words or a list); plan is the cheapest plan that has it ("from Pro"). An empty cell is "unknown", and says so. A fact with no source and no date is an opinion, so the studio asks for both beside the value.

The catalog's rules

Default naming: {self} vs {rival} ({year}) at {self}-vs-{rival}, and The {n} best {rival} alternatives in {year} at {rival}-alternatives. The slug carries no year on purpose: the title says 2026, the address stays the one every backlink already points at when the year turns.

The matrix as a spreadsheet

Competitor research starts in a spreadsheet, so the matrix round-trips through one. GET …/compare/catalog.csv exports it and PUT …/compare/catalog.csv ({ "csv": "…" }) imports it; ?dryRun=true answers how many cells it would write or clear, which rows it cannot read, and the diff. The studio previews every import before it applies it.

One row per criterion, in catalog order:

group,group_label,criterion,label,kind,unit,better,weight,key,tasklane,tasklane.note,boardwise
planning,Planning,gantt,Gantt and timeline,level,,,,true,partial,Paid add-on,no
pricing,Pricing,starting-price,Starting price,price,/seat/mo,lower,,true,10,,6

• <product> holds the cell: a level word, true/false, a number, an option id (or its label), words, or a list joined with |. A cell with both a level and a value puts the value there and the level in <product>.level.

• .level, .note, .plan, .source, .source_label and .verified columns are written only when some cell of that product uses them, and read when present.

• An absent column keeps what is stored; an empty field in a present column clears it. A product with no column, or a criterion with no row, is untouched, so a sheet of ticks never erases the notes.

• A new row adds a criterion to the group it names. A select cannot be added this way (its options need declaring), and an existing criterion's kind is never changed by a sheet.

• A leading apostrophe means "literally this text". The export writes one before words that would read as a level, a boolean, a number or a formula (=, +, -, @), so a competitor's name scraped from a web page cannot run in anybody's spreadsheet.

Comparison pages

metadata.comparison on a page of the space (write it with PATCH …/pages/{id}/metadata or comparison: in front matter):

Every product, group and criterion a page names must exist in the catalog; the write is refused with 422 naming the one that does not.

Patch, never copy. patch is laid over the catalog when the page is read and never written into it. "On this page call it Coda 2.0 and show SSO as an add-on" cannot quietly rename the product on every other page, and when the catalog changes the page follows.

Front matter

---
title: Acme vs Tasklane
comparison:
  kind: versus
  products: [acme, tasklane]
  subject: tasklane
  featured: acme
---
Tasklane and Acme both plan team work, but they trade off differently…

## Our verdict
…

The written parts

The page's prose is its sections: intro (required; it is also the page's description), verdict, why-switch, migration (steps), faq (each ### question and the words under it become FAQPage markup) and methodology. Everything structured — the matrix, prices, pros and cons, ranking — is generated from the catalog and never written as prose, so nothing is stated twice.

Bands

A page is a column of bands. Each draws only when it has something to say (a page with one product has no matrix; a catalog with no prices has no pricing band). The order and what is hidden are metadata.comparison.bands, and each kind starts in the order its readers expect:

A versus page leads with the verdict, an alternatives page and a roundup with the ranked list, and a matrix page with the table.

The look — theme.compare

Every band has its own keys; none depends on another. The families:

The design keys

Every key below is independent and works under every look; the "clean" column is what the default look sets (the plain paper look sets none of them). Layering is theme default → theme.compare → a band's own key (<band>.card beats cards key by key) → a page's customization.theme.compare.

The level glyphs are a check (yes), a half-hatched ring (partial), a price tag (add-on), a clock (planned) and a cross (no); each carries its word for screen readers, and matrix.legend prints the words under the table.

Five looks — clean (the default), paper (the plain reader), bold, editorial, dense — are only patches of those keys, laid under yours and never stored, so everything a look does is available to the others and every key stays independently set. A layout preset (product, directory, editorial) patches the same keys and the hub's band order. A single comparison can carry customization.theme.compare of its own. Click an element in the studio preview and the panel opens on the key that draws it. The outlets compare-hub-above, compare-hub-below, compare-before-matrix, compare-after-matrix and compare-page-end take your own HTML (theme components).

Generate pages

POST …/compare/generate with { "kinds": ["versus", "alternatives"], "rivals": ["tasklane"], "dryRun": true } plans the pages the catalog implies and, without dryRun, creates them as drafts from the naming patterns:

• versus — {self} against each rival (none on a roundup site: there is no "us");

• alternatives — one per rival, about it, with {self} first and then the rival's category peers;

• roundup and matrix — one per category with at least two products, with your own product leading its category's roundup.

Pages that already exist are listed as such and left alone, so running it again after adding a rival creates only the new pages. Nothing is published: a generated page still wants a verdict a person wrote. With autoPages set to draft, "generate" with no kinds makes those kinds.

Freshness

Every cell carries verifiedAt. GET …/compare/stale lists the cells past freshness.verifyEveryDays, never-checked first and then the most overdue. POST …/compare/verify with { "cells": [{ "product": "tasklane", "criterion": "sso" }] } (or "all") stamps them verified now — only a person who has re-read the source should press it. A daily sweep emits the compare.stale webhook, and a catalog write emits compare.catalog.updated (webhooks). The studio's Freshness section is the same list with a "Verified" button on each row, and the bulk "mark selected verified today" in the matrix grid stamps a block.

Readers see the date as a date, a relative date or not at all (freshness.showVerified), and a stale cell wears a badge unless freshness.staleBadge is off.

Editing the matrix

The matrix grid in the studio behaves like a spreadsheet: arrows move, Shift+arrows select a block, Y P N A L U set Yes / Partial / No / Add-on / Planned / Unknown on the whole selection, Backspace clears it, and Enter opens the cell's form (value, note, plan, source, verified date). Groups and criteria reorder by dragging or with Alt+Up / Alt+Down on the row's handle.

SEO notes

• Titles and descriptions come from the naming pattern (with {year}) and the introduction; canonical, Open Graph and Twitter tags are generated, and a page can be marked noindex. A comparison with fewer than two products can be kept out of the index (seo.noindexThin).

• Structured data: WebPage or Article, an ItemList of SoftwareApplication (or Product) entries with offers built from the pricing, FAQPage from the questions, and BreadcrumbList. Disable any of them in theme.compare.seo, or replace the lot with the page's own customization.jsonLd.

• No self-serving ratings. AggregateRating is built only from a product's third-party ratings (G2, Capterra, an app store), only when theme.compare.seo.ratingsInSchema is switched on, and never from a score this site awards. Search engines treat a rating a business gives its own product as self-serving and penalise it, so there is no key that publishes one. Scores are computed but not shown until scoring.show is on, for the same reason: a number you award your own product reads as a sales claim, and the least surprising page is the one that only states facts.

• Affiliate links are drawn rel="sponsored nofollow" and disclosed on the page; they are marked in the studio on each product and on the page's CTA.

• Dates: dateModified is the latest verified date on the page, so a re-checked fact is a visible freshness signal.

• A product with at least one published comparison has its own hub at /vs/{org}/{space}/product/{id} and is listed in the sitemap; a product with none is not.

• Every page has a Markdown twin (.md: the matrix as a table, the sources as footnotes), is listed in llms.txt, carries hreflang twins for each translated language, and has a generated social card showing the logos and names (social cards). Languages are in the path (/vs/…/es/acme-vs-tasklane), never a query (translations).

• ?embed=1 returns the bare matrix for an <iframe>; an oEmbed card is advertised on every comparison. rss.xml and feed.json list new and re-verified comparisons.

• CTA clicks send a first-party compare_cta event (product and page), consent-gated like the rest (measurement).

From forumulate.yaml

spaces:
  - path: compare
    space: compare
    create: { type: COMPARE, name: Comparisons }
    compare:
      catalog: compare.yaml     # the catalog's keys, in a file beside the manifest
      matrix: matrix.csv        # the matrix as a spreadsheet
      scoring: { show: false }  # any catalog key inline wins over the file

compare.yaml holds the catalog (self, products, criteria, values, scoring, freshness, naming, disclaimer, …). Only the top-level keys that differ from what the space stores are sent, so a run that changes nothing writes nothing; null clears a key. The matrix file is read by the same importer as the CSV door after the catalog, previewed first, and a row it cannot read stops the run naming the row. The comparison pages are the folder's Markdown, with comparison: in their front matter. In a version 2 file (forumulate plan / apply) the same block sits on the space and matrix is sent as the CSV text (plan and apply).

Templates

Four kits start a space with a sample catalog of fictional products, pages drawn from it and a Your Brand placeholder:

Every sample product carries a brand color, so its monogram tile shows an identity until you upload its logo. Every sample fact carries a sample verified date. Re-check each against its real source and re-date it (the Freshness section lists them) before you publish.

In the API

Every operation below is also reachable from the other surfaces without a dedicated command. forumulate api <Operation> calls it from the CLI, the JavaScript SDK has a typed method for each one (the last column names it; the Python and Go SDKs are generated from the same spec), and an agent reaches the organization-scoped ones through the MCP agent server — its api_* family tools, or call_api. Where a CLI command or a hand-made MCP tool exists too, the last column names it. Operation names link to the API reference.

Compare