Modul 2 – OKF-specen i detalj

Tillbaka till kursens startsida. Föregående modul: Modul 1 – Varför OKF?.

Denna modul går igenom strukturen i okf/SPEC.md paragraf för paragraf.

En Knowledge Bundle är en självständig, hierarkisk samling av kunskapsdokument – enheten som distribueras. Varje koncept (Concept) är en enskild markdown-fil i bundlen. Filens sökväg, utan ändelsen .md, blir dess koncept-ID. Till exempel ger tables/customers.md koncept-ID tables/customers.

Två filnamn är reserverade:

• index.md – möjliggör stegvis navigering (progressive disclosure)

för agenter som utforskar hierarkin.

• log.md – kronologisk historik över ändringar i katalogen.

sales/
├── index.md
├── datasets/
│   ├── index.md
│   └── orders_db.md
├── tables/
│   ├── index.md
│   ├── orders.md
│   └── customers.md
└── metrics/
    ├── index.md
    └── weekly_active_users.md

Varje koncept-fil inleds med ett frontmatter-block: YAML-metadata avgränsad av — överst i filen, följt av body – all text efter frontmatter.

Det enda obligatoriska fältet är type. Rekommenderade fält är title, description, resource, tags och timestamp.

---
type: metric
title: Konverteringsgrad
description: Andel besök som resulterar i en genomförd beställning.
resource: bigquery://analytics.metrics.conversion_rate
tags: [ecommerce, kpi]
timestamp: 2026-06-01
---

## Konverteringsgrad

Beräknas som antal beställningar dividerat med antal unika besök,
per kalenderdygn.

OKF är medvetet minimalt opinionerat: specen bestämmer bara interoperabilitetsytan (frontmatter + reserverade filer), inte innehållsmodellen. Vilka type-värden som finns, vilka ytterligare fält som används och hur body:n struktureras bestäms av producenten.

Koncept länkas till varandra med vanliga markdown-länkar, vilket gör katalogen till en graf av relationer – rikare än den implicita förälder/barn-hierarkin som filsystemet ger.

Konformansregler att känna till:

• Frontmatter måste vara parsebar YAML.
• Fältet type får inte vara tomt i något koncept.
• index.md och log.md följer sina respektive reserverade roller

och får inte användas för annat syfte.

• Konsumtionsmodellen är permissiv – bundles med saknade index.md

ska ändå fungera, eftersom bundles växer och refaktoreras över tid.

Specen är versionerad som <major>.<minor>. En mindre versionsökning introducerar bakåtkompatibla tillägg, till exempel nya valfria fält eller nya konventionella sektionsrubriker.

Nästa steg: gå vidare till Modul 3 – Designa din bundle.