AKN Diff Examples: The Paella Valenciana Lifecycle

This walkthrough uses a fictional legislative process — the regulation of the Paella Valenciana recipe — to demonstrate every feature of AKN Diff. The story follows a traditional recipe through a bill, five amendments, and a final enacted version.

All example files are in research/2026-02-01/akndiff-poc/receta-paella/.

The cast

Stage 1: The original act

File: 01-act-original.xml — A standard AKN <act> with no AKN Diff extensions.

The recipe has 11 articles across 4 titles, with strict rules: bomba rice only, no seafood, real saffron only, wood fire only.

<akomaNtoso xmlns="http://docs.oasis-open.org/legaldocml/ns/akn/3.0">
  <act name="receta-paella-valenciana">
    <!-- Standard AKN: meta + preface + body -->
    <!-- No akndiff namespace needed yet -->
  </act>
</akomaNtoso>

Key articles that will be contested:

Stage 2: The bill — "Democratizing" the recipe

File: 02-bill.xml — An AKN <bill> with an AKN Diff changeSet.

The Diputada Madrileña proposes 5 changes to make the recipe more accessible. The bill is voted on and approved 5-3 (the entire Valencian delegation votes against).

The changeSet

<akndiff:changeSet
  base="/poc/receta/paella-valenciana/esp@2023-03-18"
  result="/poc/receta/paella-valenciana/esp@2024-05-10">

This tells us: applying these changes to the 2023-03-18 original produces a new version dated 2024-05-10.

The changes

The vote

<akndiff:vote date="2024-05-10" result="approved"
            source="/poc/debate/pae-2024-01-pleno">
  <akndiff:for>   <!-- 5 votes --> </akndiff:for>
  <akndiff:against> <!-- 3 votes (Valencian delegation) --> </akndiff:against>
  <akndiff:abstain/>
</akndiff:vote>

Stage 3: Amendment 1 — "The chorizo amendment"

File: 03-amendment-1.xml — REJECTED unanimously (0-8).

The Dip. Turismo proposes adding chorizo for international markets. Even the bill's own author votes against. This is the first unanimous vote in the commission's history.

Key pattern: rejected amendment

<akndiff:changeSet
  base="/poc/receta/paella-valenciana/esp@2024-05-10"
  result="/poc/receta/paella-valenciana/esp@2024-05-10">

Note: base and result are identical. The amendment proposed changes but they were not applied.

<akndiff:vote date="2024-06-01" result="rejected" ...>
  <akndiff:for/>  <!-- empty: zero votes in favor -->
  <akndiff:against>
    <!-- all 8 members, including the proposer himself -->
  </akndiff:against>
</akndiff:vote>

The articleChange still records what was proposed (insert art_5ter for chorizo), preserving the full legislative record.

Stage 4: Amendment 2 — "The Valencian shield"

File: 04-amendment-2.xml — APPROVED 6-2.

The Valencian delegation fights back. They accept gas as a heat source but demand reverting two changes from the bill:

• art_1: Back to mandatory bomba rice (reverting the bill's change)
• art_7: Back to mandatory real saffron (reverting the bill's change)

Key pattern: reverting previous changes

The <old> text matches the bill's <new> text, and the <new> text matches the original act:

<akndiff:articleChange article="art_1" type="substitute">
  <akndiff:old>Se utilizarán 400 gramos de arroz bomba o, alternativamente,
  arroz redondo de grano medio. Se recomienda preferentemente el arroz
  bomba cuando esté disponible.</akndiff:old>
  <akndiff:new>Se utilizarán 400 gramos de arroz bomba de denominación de
  origen Valencia. Queda prohibido el uso de cualquier otra variedad
  de arroz.</akndiff:new>
</akndiff:articleChange>

The base→result chain advances:

<akndiff:changeSet
  base="/poc/receta/paella-valenciana/esp@2024-05-10"
  result="/poc/receta/paella-valenciana/esp@2024-06-15">

Stage 5: Amendment 3 — "The onion amendment"

File: 05-amendment-3.xml — WITHDRAWN before the vote.

The Dip. Andaluza proposes allowing onion in the sofrito. Social media backlash and a letter from 200 Valencian chefs force her to withdraw.

Key pattern: withdrawn amendment

<akndiff:changeSet
  base="/poc/receta/paella-valenciana/esp@2024-06-15"
  result="/poc/receta/paella-valenciana/esp@2024-06-15">

Again base == result (no new version produced). But the vote record is different from a rejection:

<akndiff:vote date="2024-06-20" result="withdrawn" ...>
  <akndiff:for/>
  <akndiff:against/>
  <akndiff:abstain/>
</akndiff:vote>

All voter containers are empty — the vote never took place.

Stage 6: Amendment 4 — "The seafood compromise"

File: 06-amendment-4.xml — APPROVED 7-1.

The Dip. Catalán proposes a compromise: instead of allowing seafood in paella, create a separate "arroz de marisco" (seafood rice) category with its own rules.

Changes:

• art_5: Restores the seafood prohibition but references art_5bis
• art_5bis: Replaces "paella mixta" with a proper "arroz de marisco" definition

<akndiff:changeSet
  base="/poc/receta/paella-valenciana/esp@2024-06-15"
  result="/poc/receta/paella-valenciana/esp@2024-07-01">

Stage 7: Amendment 5 — "The socarrat express"

File: 07-amendment-5.xml — REJECTED 2-6.

The Dip. Consumo proposes making socarrat optional and replacing newspaper with a kitchen towel. The commission rejects it decisively.

<akndiff:changeSet
  base="/poc/receta/paella-valenciana/esp@2024-07-01"
  result="/poc/receta/paella-valenciana/esp@2024-07-01">

<akndiff:vote date="2024-07-10" result="rejected" ...>
  <akndiff:for>   <!-- 2 votes --> </akndiff:for>
  <akndiff:against> <!-- 6 votes --> </akndiff:against>
</akndiff:vote>

Stage 8: The final act

File: 08-act-final.xml — Standard AKN <act>, the enacted result.

The final act reflects only the approved amendments (bill + amendments 2 and 4). It has no AKN Diff extensions itself — it's the resulting document.

Net changes from original to final

The version chain

esp@2023-03-18  ──bill──→  esp@2024-05-10  ──amd2──→  esp@2024-06-15  ──amd4──→  esp@2024-07-01
                                 │                          │                          │
                           amd1 (rejected)            amd3 (withdrawn)           amd5 (rejected)
                           base==result               base==result               base==result

The lifecycle element in the final act records all events:

<lifecycle source="#congreso">
  <eventRef eId="e1" date="2023-03-18" type="generation" source="#autor"/>
  <eventRef eId="e2" date="2024-05-10" type="amendment" source="/poc/bill/pae-2024-01"/>
  <eventRef eId="e3" date="2024-06-01" type="amendment" source="/poc/amendment/pae-2024-01-ind1"/>
  <eventRef eId="e4" date="2024-06-15" type="amendment" source="/poc/amendment/pae-2024-01-ind2"/>
  <eventRef eId="e5" date="2024-06-20" type="amendment" source="/poc/amendment/pae-2024-01-ind3"/>
  <eventRef eId="e6" date="2024-07-01" type="amendment" source="/poc/amendment/pae-2024-01-ind4"/>
  <eventRef eId="e7" date="2024-07-10" type="amendment" source="/poc/amendment/pae-2024-01-ind5"/>
  <eventRef eId="e8" date="2024-09-01" type="generation" source="#congreso"/>
</lifecycle>

Summary of AKN Diff patterns demonstrated

Previous: The vote element