Add or correct a product

Adding a product

1. 1. Check the producer exists. Look for content/brands/<brand>.json. If it is missing, add it first — ownership and headquarters live on the brand, not the product.
2. 2. Create the product file. content/products/<slug>.json, where the filename matches the slug inside. The $schema line gives you completion and inline errors in any modern editor.
3. 3. Cite everything you can. Open the producer's site, find the page that states the fact, quote the sentence, and record the date. If you cannot find it, leave the claim unverified rather than guessing — an honest gap is worth more than a confident invention.
4. 4. Run the checks. npm run validate tells you what is broken and what is merely missing. Errors block the merge; warnings are the to-do list.
5. 5. Open a pull request. CI runs the same validation, so review is about judgement, not typos.

A minimal record

Everything below except the identity fields is optional. A record with two well-sourced claims is more useful than one with twenty guesses.

{
  "$schema": "../../schemas/product.schema.json",
  "slug": "example-widget",
  "name": "Example Widget",
  "tagline": "A widget assembled in Portugal from European steel",
  "summary": "Two to five sentences of plain prose. Say what it is and what is notable about where it comes from. No adjectives you cannot source.",
  "type": "physical",
  "brand": "example-co",
  "categories": ["tools-machinery"],
  "url": "https://example-co.eu/widget",
  "alternativeTo": [{ "name": "Acme Widget", "company": "Acme", "country": "US" }],
  "origin": {
    "manufacturedIn": {
      "value": ["PT"],
      "status": "verified",
      "evidence": [{
        "url": "https://example-co.eu/about/production",
        "publisher": "producer",
        "quote": "Every widget is assembled at our plant in Braga.",
        "retrievedAt": "2026-07-28"
      }]
    },
    "materials": { "value": "mostly-eu" }
  },
  "quality": {
    "warrantyYears": {
      "value": 5,
      "status": "verified",
      "evidence": [{
        "url": "https://example-co.eu/warranty",
        "publisher": "producer",
        "quote": "All widgets carry a five-year warranty.",
        "retrievedAt": "2026-07-28"
      }]
    }
  },
  "createdAt": "2026-07-28",
  "updatedAt": "2026-07-28"
}

Rules that will trip you up

• Producer evidence must be on the producer's domain. Marking a magazine article as producer is a build failure, not a warning.
• A claim marked verified must carry at least one source — and a claim marked unverified must carry none. The two states are not interchangeable.
• Sources must be https and dated. Future dates are rejected.
• Slugs are permanent. They are URLs. Add rather than rename.

Corrections

If a record is wrong, edit the file and say why in the pull request. If a company was acquired or a factory moved, update the claim and its evidence date — do not just change the value, because the date is what makes the change auditable. If two sources disagree, set the claim to disputed and explain the conflict in the note; it will score zero and display the disagreement.