AKN4OLF - the Open Laws Foundation profile of Akoma Ntoso

This repository defines AKN4OLF: a profile of Akoma Ntoso (OASIS LegalDocML) plus the conformance suite that every Open Laws Foundation adapter must pass.

It is the entry point to the project. Read this before the other repos.

---

The core principle

We normalize metadata, not content.

Legal content is not normalizable across jurisdictions, and trying to do it is how this kind of project dies. An Italian comma, a U.S. section, and a French article are not three names for the same object: they differ in granularity, hierarchy, and citation rules. Force them into one schema and you either lose everything that makes each jurisdiction useful (lowest common denominator) or build an unmaintainable monster with a field for every national exception (highest common multiple).

Akoma Ntoso already solved this the right way: a shared vocabulary (act, body, article, ref, lifecycle, …) that each jurisdiction instantiates on its own terms. That is exactly what AKN4EU, AKN4UN, and AKN4Africa are profiles, not translations. AKN4OLF is one more profile in that family.

So:

• Content → stays in native Akoma Ntoso, in the jurisdiction's own profile. We never flatten it into a neutral schema.
• Metadata and relationships → normalized by AKN4OLF, because every legal system has a "when", a "what is named what", and a "who cites whom".

The rule, on your monitor: if two lawyers from two countries would argue about how to model it, it's content leave it native. If they agree it exists in both systems, it's metadata normalize it.

Entry into force? Exists everywhere → normalize. comma vs section structure? They'd argue → native.

---

What AKN4OLF normalizes

Exactly three things. Nothing about the substantive text.

1. Identity

A uniform way to name and address an act across jurisdictions, layered over Akoma Ntoso's native FRBR/URI identifiers. The OLF identifier is a stable, resolvable key:

olf:<jurisdiction>/<type>/<year>/<number>[/<eId>]
olf:it/legge/2019/123
olf:it/legge/2019/123/art_3        # an element inside the act
olf:fr/loi/2016/1321

The OLF id maps onto the native URN/ELI; it does not replace it. Both travel together in the document metadata.

2. Lifecycle events

Typed temporal events, so the differ and any consumer can reason about time identically across countries:

• in_force_from / in_force_to (validity interval)
• enacted, published, commenced, amended, repealed
• deferred / conditional commencement is represented explicitly, not inferred from a publication date

These map to Akoma Ntoso <lifecycle> / <temporalGroup>; AKN4OLF fixes the required event vocabulary and which ones are mandatory.

3. References

A common way to express that one act cites / amends / repeals another, so the citation graph crosses borders:

• every reference carries a resolvable target OLF id (or unresolved with the raw text preserved)
• the relation is typed (cites, amends, repeals, implements, …)

We normalize the relationship, not the text of either act.

---

What AKN4OLF leaves native

Everything else. Document hierarchy, article/section/comma structure, headings, the substantive text, footnotes, annexes. These follow the jurisdiction's native Akoma Ntoso profile, untouched.

---

Provenance (non-negotiable)

Every document in the archive is generated, never hand-edited, and must carry, in its metadata:

• the source identifier and hash of the official material it was built from
• the adapter name and version that produced it
• the timestamp of generation

This is what lets anyone re-run the pipeline and obtain the same Akoma Ntoso from the same source. The archive is a reproducible cache; the truth is the adapters + this spec.

---

Conformance suite

The heart of the project. The suite (in conformance/) defines what it means for an adapter's output to be correct, independent of who wrote the adapter:

• output is schema-valid Akoma Ntoso in a recognized profile
• every required AKN4OLF lifecycle event is present and well-formed
• every <ref> either resolves to an OLF id or is explicitly unresolved
• temporal validity is monotonic (no overlapping/contradictory in-force intervals)
• the original (as-enacted) text is reconstructible from the multi-version document
• OLF identifiers are stable across regenerations (same source ⇒ same ids)

An adapter is "OLF-conformant" iff it passes the suite. That is the only gate. The suite, not the corpus, not any single adapter, is the artifact other projects can adopt even without using our archive.

---

How a jurisdiction joins

1. Write an adapter in pipeline that ingests the official source and emits native Akoma Ntoso + the AKN4OLF metadata layer.
2. Pass the conformance suite.
3. On merge, the pipeline regenerates that jurisdiction and publishes signed artifacts to the archive.

You do not need to model 190 legal systems. For each jurisdiction you only need to answer three questions: when does it come into force, what is it called, what does it cite.

---

Relationship to existing work

AKN4OLF is deliberately not novel as a format it is Akoma Ntoso. The new part is the interoperability + verifiable-provenance layer over already-published sources, and the conformance suite that holds independent contributors together. Prior and adjacent art we build with, not against: Akoma Ntoso / OASIS LegalDocML, Laws.Africa / Indigo, AKN4EU / LEOS, AKN4UN, and national systems such as Normattiva (IT) and Légifrance (FR).