Skip to main content
Introducing packages.sweber.dev
Documentation menuFeed format

Feed format

The changelog.json schema.

changelog.json is plain JSON you can also write by hand or generate from a CMS.

{
  "version": 2,
  "title": "Acme changelog",
  "link": "https://acme.ch/changelog",
  "generatedAt": "2026-10-05T10:00:00.000Z",
  "releases": [
    {
      "id": "2.4.0",
      "version": "2.4.0",
      "date": "2026-10-02",
      "title": "Dark mode is here",
      "summary": "Switch it on under **Settings → Appearance**.",
      "importance": "major",
      "media": [{ "type": "image", "url": "/dark.png", "alt": "The dashboard in dark mode" }],
      "links": [{ "label": "Read the guide", "url": "https://acme.ch/docs/dark-mode" }],
      "translations": {
        "de": { "title": "Dunkelmodus ist da", "entries": { "ACME-12": "Dunkelmodus für das Dashboard" } }
      },
      "entries": [
        { "id": "ACME-12", "type": "feature", "text": "Dark mode for the dashboard", "target": "#theme-switch" },
        { "type": "fix", "text": "Rounding of Swiss francs", "scope": "billing", "link": "https://…", "audience": ["pro"] }
      ]
    }
  ]
}
FieldRequiredNotes
versionyes2. Files with 1 are accepted and converted
releasesyesNewest first
releases[].idyesStable key for the unread state, usually the version
releases[].entriesyesMay be empty when a title or summary is set
releases[].dateISO 8601 date or date-time
releases[].packagePackage name in monorepo feeds
entries[].typeyesfeature, improvement, fix, breaking, security, deprecated, removed or other
entries[].textyesOne line, inline Markdown
entries[].detailsMore paragraphs or a - list
entries[].scope, entries[].link
releases[].importancemajor or normal. The widget's highlight prefers major releases
releases[].media[{ type: "image" | "video", url, alt? }], shown above the entries
releases[].links[{ label, url }], shown under the entries
releases[].audience, entries[].audienceNames of the audiences that see it. Empty or missing: everyone
releases[].translations{ "<lang>": { title?, summary?, entries? } }, where entries maps an entry id to its translated text
entries[].idStable id of an entry (ticket key). Needed to translate it
entries[].targetCSS selector of the page element the entry is about, for the widget's hints

The widget validates the file with parseFeed and ignores unknown fields. URLs in link, media and links must be http(s), mailto or relative; others are dropped. For widgets still on 1.x, derivative build --feed-format 1 writes the old format (the first image becomes image; media, links, audiences and translations are left out).