Changelog-bestandsformaten: JSON, YAML of gewoon Markdown

De meeste teams beginnen een changelog als Markdown-bestand omdat het de weg van de minste weerstand is: leesbaar in een diff van een pull request, leesbaar op GitHub zonder iets te renderen, en vertrouwd voor iedereen die ooit een README heeft geschreven. Die keuze werkt prima totdat iets anders dan een mens het bestand moet lezen, een pagina, een widget, een e-mailsamenvatting, en dan houdt het formaat op gratis te zijn. Changelog-automatisering behandelt de structurele eis in het algemeen, een type, een datum, een body en een link; dit gaat over welk bestandsformaat die structuur echt levert en wat het kost om daar te komen bij elk.

Wat is er mis met een simpele Markdown-changelog?

Niets, totdat iets het terug moet parsen naar velden. Een kop, een datum en een lijst eronder is triviaal te lezen voor een mens en oprecht lastig betrouwbaar te parsen, omdat Markdown geen schema heeft: de datum kan in de kop staan, vetgedrukt op de eerste regel, of helemaal ontbreken bij een oud item, en elk van die varianten is geldige Markdown die een mens correct leest en een parser niet. Teams die een Markdown-changelog automatiseren, eindigen meestal met een op maat gemaakte regex-parser die breekt zodra de opmaak van een item ook maar licht afwijkt, wat vaak gebeurt, omdat niets consistentie afdwingt bij het schrijven.

Wat levert een gestructureerd formaat je eigenlijk op?

Een garantie dat elk item dezelfde vorm heeft, gecontroleerd wanneer het item wordt geschreven in plaats van geraden wanneer het wordt gelezen. Een JSON- of YAML-bestand met een gedefinieerd schema, type, datum, versie, doelgroep, body, link, faalt luidruchtig als een verplicht veld ontbreekt, net zoals een strikte API-respons zou doen; een Markdown-bestand rendert gewoon wat er staat, correct of niet. Dat verschil is onzichtbaar tot de dag dat een script de datum van elk item nodig heeft om een feed te sorteren, en de helft van de items heeft die op een andere plek staan.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

Betekent dat dat het mensleesbare bestand moet verdwijnen?

Nee, en proberen een YAML- of JSON-bestand tegelijk te laten dienen als wat een mens leest in een pull request is meestal een fout de andere kant op: een diff van geneste JSON reviewen is erger dan een zin proza reviewen, en een reviewer die een datastructuur mentaal moet parsen om een formuleringsfout te vangen, is een reviewer die uiteindelijk stopt met formuleringsfouten vangen. De twee formaten kunnen naast elkaar bestaan: gestructureerde data is de bron van waarheid die een automatiseringspipeline leest, en een gegenereerde Markdown- of HTML-weergave is wat een mens daadwerkelijk reviewt en leest, geproduceerd uit het gestructureerde bestand in plaats van er handmatig naast onderhouden.

Welk gestructureerd formaat is echt makkelijker handmatig te bewerken, JSON of YAML?

YAML, voor wie items met de hand schrijft in plaats van via een generator, omdat het het quoten en haakjes matchen wegneemt dat JSON vereist voor elke string en genest object. Het nadeel is dat de witruimtegevoeligheid van YAML op een manier stil faalt waarop de haakjesmismatches van JSON dat meestal niet doen: een JSON-parser wijst misvormde invoer regelrecht af, terwijl een YAML-parser een slecht ingesprongen bestand kan accepteren en het gewoon in de verkeerde structuur parst, wat een erger falen is omdat niets je vertelt dat het is gebeurd. Als items altijd alleen door een script worden geschreven, verdwijnt dit nadeel grotendeels en wordt het strengere parsen van JSON de veiligere standaardkeuze.

Heeft een changelogpagina zijn eigen gestructureerde formaat nodig, apart van het bestand dat het voedt?

Niet een apart formaat, hetzelfde anders gerenderd. Een changelogpagina behandelt hoe je de pagina zelf machineleesbaar maakt via een JSON-feed en schema.org-markup; die feed is gegenereerde output, geen tweede bron van waarheid die synchroon gehouden moet worden met het onderliggende bestand. Gestructureerde data op twee plekken handmatig onderhouden, een bronbestand en de feed van een pagina, is hoe de twee uit elkaar drijven, dus de bestandsformaatbeslissing die hier genomen wordt, zou het enige moeten zijn waaruit alles stroomafwaarts, pagina, widget, e-mail, gegenereerd wordt, nooit handmatig gekopieerd.

Is het migratiekosten waard om een bestaande Markdown-changelog om te zetten naar een gestructureerd formaat?

Meestal pas zodra automatisering het echte doel is, niet ervoor. Een eenpersoonsproject dat een Markdown-bestand publiceert in een GitHub-README heeft geen echte automatiseringsbehoefte, en het omzetten naar YAML koopt niets dan plichtplegingen. De conversie betaalt zichzelf terug op het moment dat meer dan één stroomafwaartse consument, een pagina, een samenvattingsmail, een publieke feed, dezelfde data moet lezen, omdat dat precies het punt is waarop de inconsistenties van een Markdown-parser zichtbaar verkeerde output beginnen te produceren in plaats van gewoon vervelend te zijn om te onderhouden.

FAQ

Kan een Markdown-changelog parseerbaar worden gemaakt zonder helemaal van formaat te wisselen? Gedeeltelijk, met frontmatter: een klein YAML-blok bovenaan elk item (datum, type, versie) naast een Markdown-body voor de proza. Dit levert de gestructureerde velden die een parser nodig heeft zonder het hele item in JSON of YAML te dwingen, en het is een redelijk middenweg voor een team dat nog niet klaar is voor een volledige migratie.

Maakt het bestandsformaat uit voor SEO of voor hoe een changelogpagina rankt? Niet direct. Zoekmachines lezen de gerenderde pagina, niet het bronbestand, dus het bestandsformaat is voor hen onzichtbaar; wat telt voor de pagina zelf is of hij op eigen kracht machineleesbaar is, wat een apart punt is van wat hem genereert.

Moet elk changelog-item door hetzelfde bestand lopen, of kunnen types over bestanden worden verdeeld? Eén bestand is simpeler tot het itemvolume het onhandig maakt om te diffen of te reviewen; opsplitsen per jaar of per categorie is een redelijke ontsnappingsklep zodra de diffs van één bestand te groot worden om zinnig te reviewen, maar het voegt een samenvoegstap toe voordat iets stroomafwaarts “alle items” als één lijst kan lezen.

Bestaat er een standaard changelog-bestandsformaat, zoals er een standaard is voor RSS? Niet een breed aangenomen. Keep a Changelog stelt een Markdown-conventie voor, en verschillende tools hebben hun eigen; een changeset is een Markdown-bestand met YAML-frontmatter dat het pakket en de bump noemt, precies het frontmatterpatroon dat hierboven is beschreven. Geen daarvan is een formaat dat andere tools out of the box lezen zoals RSS-lezers universeel RSS begrijpen.

De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.

Meer op changeloop: Changelog-tools vergeleken, Changelog-generator