09 - Conformité
Conformité OKF : les règles minimales pour qu'un bundle reste lisible et portable
La conformité OKF v0.1 ne cherche pas à tout contrôler. Elle définit un minimum interopérable: assez strict pour que les outils sachent quoi lire, assez souple pour que les équipes puissent adapter le format à leur domaine.
Pourquoi OKF parle de conformité minimale ?
OKF est jeune et volontairement léger. Son objectif n'est pas d'imposer un modèle documentaire complet à toutes les entreprises, mais de garantir qu'un bundle puisse être lu par différents consommateurs: humains, agents, scripts, visualizers ou outils de recherche.
Une conformité trop stricte rendrait le format difficile à adopter. Une conformité trop floue rendrait l'interopérabilité impossible. OKF choisit donc une voie pragmatique: quelques règles obligatoires, beaucoup de champs recommandés, et une forte tolérance côté consommateur.
Pour une entreprise, c'est une bonne nouvelle. Vous pouvez commencer avec des fichiers simples, puis améliorer progressivement la qualité: titres, descriptions, sources, citations, index, historique et conventions métiers.
Les trois règles obligatoires d'OKF v0.1
Un concept conforme à OKF v0.1 doit respecter trois règles minimales. Premièrement, il doit être représenté par un fichier Markdown. Deuxièmement, son frontmatter YAML doit être parseable. Troisièmement, il doit contenir un champ `type` présent et non vide.
Ces règles ne disent pas qu'un concept est complet, fiable ou bien écrit. Elles disent seulement qu'il possède la structure minimale pour être reconnu comme concept OKF par un consommateur.
C'est une distinction importante: la conformité est le plancher technique. La qualité documentaire, elle, dépend des bonnes pratiques: description claire, sources, citations, liens, owner, timestamp et relecture humaine.
Règle 1 : chaque concept est un fichier Markdown
Dans OKF, une unité de connaissance est un fichier `.md`. Ce choix rend le contenu lisible sans outil propriétaire, versionnable dans Git, facile à relire et exploitable par de nombreux parseurs existants.
Le Markdown ne signifie pas que tout doit être prose libre. Un bon concept peut contenir des titres, listes, tableaux, blocs de code, liens et citations. La structure du body aide autant les humains que les agents.
`index.md` et `log.md` ont un rôle réservé quand ils existent. Les autres fichiers Markdown du bundle sont traités comme des concept files.
Règle 2 : le frontmatter YAML doit être parseable
Le frontmatter YAML est le bloc placé au début du fichier entre deux lignes `---`. Pour être conforme, ce bloc doit être syntaxiquement parseable. Un outil doit pouvoir le lire sans erreur YAML.
Cette règle est simple, mais elle évite beaucoup de problèmes: indentation cassée, listes mal formées, guillemets non fermés, ou champs impossibles à interpréter.
Le frontmatter sert de couche structurée. Le body Markdown peut rester humain et narratif, mais le frontmatter donne aux agents les métadonnées minimales pour filtrer, router, indexer ou afficher un concept.
Règle 3 : le champ type doit être présent et non vide
`type` est le seul champ requis dans un concept file OKF v0.1. Il indique la nature du concept: `Metric`, `Playbook`, `BigQuery Table`, `API Endpoint`, `Decision`, `Persona`, `Reference`, ou un type métier propre à l'entreprise.
Le type n'a pas besoin d'appartenir à une liste officielle. Un consommateur doit accepter un type inconnu et traiter le fichier comme un concept générique plutôt que rejeter tout le bundle.
En revanche, un champ `type` vide ne suffit pas. Le consommateur peut afficher le fichier comme Markdown brut, mais il ne devrait pas le considérer comme un concept OKF conforme.
Cas particulier : index.md et log.md
`index.md` sert de carte d'entrée. Il peut aider un agent ou un humain à découvrir ce qui existe dans un dossier sans ouvrir tous les fichiers. Il est utile, mais son absence ne doit pas bloquer la lecture d'un bundle.
`log.md` sert d'historique. Il peut documenter les changements importants: création, mise à jour, dépréciation, clarification ou déplacement de concepts. Là encore, il améliore la maintenabilité sans devenir obligatoire dans tous les cas.
La bonne posture est progressive: démarrez avec des concept files conformes, puis ajoutez `index.md` et `log.md` dès que le bundle devient assez riche pour nécessiter une navigation et un historique.
Ce qu'un consommateur OKF doit tolérer
La conformité OKF concerne aussi le comportement des consommateurs. Un outil qui lit un bundle ne doit pas casser brutalement dès qu'il rencontre un champ inconnu, un type inconnu, un champ recommandé absent ou un lien cassé.
Cette tolérance est essentielle pour un format ouvert. Les équipes vont ajouter leurs propres champs métiers, leurs propres types et leurs propres conventions. Un consommateur OKF doit préserver ce qu'il ne comprend pas et faire une lecture best effort.
Cela ne veut pas dire que tout est acceptable. Les outils peuvent signaler des warnings, proposer des corrections, lister les liens cassés ou indiquer les champs manquants. Mais ils doivent aider à améliorer le bundle, pas empêcher sa lecture.
Ce qui reste une bonne pratique sans être obligatoire
`title`, `description`, `resource`, `tags` et `timestamp` sont recommandés parce qu'ils rendent un concept beaucoup plus utile. Mais leur absence ne rend pas automatiquement le concept non conforme.
Les citations, les liens internes, les owners, les conventions de nommage et les templates augmentent fortement la qualité opérationnelle. Ils aident les humains à relire, les agents à naviguer, et les équipes à maintenir le contexte dans le temps.
La conformité répond à la question: est-ce lisible par un consommateur OKF ? La bonne pratique répond à une autre question: est-ce fiable, utile et maintenable pour une entreprise ?
Exemple concret : conforme, incomplet, invalide
Les trois exemples suivants montrent la différence entre conformité minimale, qualité incomplète et invalidité. C'est le point clé à retenir: un fichier peut être conforme sans être excellent, et un fichier peut être lisible en Markdown sans être un concept OKF valide.
---
type: Metric
---
# Monthly Recurring Revenue
This concept is minimally compliant with OKF v0.1 because it is a Markdown
file with parseable YAML frontmatter and a non-empty type field.---
type: Playbook
title: Refund request
---
# Refund request
This concept is usable but incomplete. It has the required type field,
but it is missing recommended metadata such as description, tags,
timestamp, resource and citations.---
type:
title: Broken concept
---
# Broken concept
This concept is not compliant because the required type field is empty.
A consumer may still display the Markdown as a raw document, but it should
not treat it as a valid OKF concept file.Oui
Un concept document OKF est représenté par un fichier Markdown.
Oui
Le frontmatter doit pouvoir être lu sans erreur de syntaxe.
Oui
Le consommateur peut identifier la nature minimale du concept.
Non
Champs recommandés: signaler leur absence, mais ne pas rejeter le concept.
Non bloquant
Le traiter comme concept générique et préserver la valeur originale.
Non bloquant
Le conserver, l'ignorer si nécessaire, mais ne pas casser la lecture.
Non bloquant
Afficher un warning ou une dette de maintenance.
Non
Le bundle reste lisible, mais la navigation progressive est moins bonne.
Erreurs fréquentes à éviter
La première erreur est de confondre conformité et qualité. Un concept peut être techniquement conforme avec seulement `type`, mais rester trop pauvre pour guider un agent en production.
La deuxième erreur est de créer un validateur trop strict. Si un outil rejette un bundle parce qu'un champ recommandé manque ou qu'un type métier est inconnu, il trahit l'esprit extensible d'OKF.
La troisième erreur est d'utiliser la tolérance comme excuse pour ne jamais nettoyer. Les liens cassés, champs absents et sources manquantes doivent être visibles dans la maintenance, même s'ils ne bloquent pas la lecture.
Lire ensuite
Une fois les règles minimales comprises, la suite naturelle est de comparer OKF au RAG: la conformité garantit que la matière première est lisible, tandis que le retrieval décide comment retrouver les bons passages au bon moment.
Revoir les champs requis et recommandés d'un concept file.
Liens et grapheComprendre pourquoi les liens cassés sont tolérés mais doivent être maintenus.
Exemples de fichiersVoir des exemples conformes et adaptables à plusieurs cas métiers.
OKF vs RAGComprendre pourquoi la conformité structure la matière première du retrieval.
WorkflowMettre en place une relecture et une maintenance régulière du bundle.
Premier bundleDémarrer avec un périmètre réduit et des règles simples.
Sources officielles et lectures utiles
Source primaire: règles de conformité, champs requis, champs recommandés et tolérance des consommateurs.
OKF README.mdPrésentation officielle du format, des outils et des exemples de bundles.
Knowledge Catalog repoRepo officiel avec spec, samples, reference agent et visualizer.
Google Cloud - Introducing OKFAnnonce officielle pour comprendre le contexte de création d'OKF.
YAML SpecificationRéférence du format YAML, utile pour comprendre la notion de frontmatter parseable.
Les points à retenir
La conformité OKF v0.1 est un minimum interopérable, pas une garantie de qualité. Un concept conforme est un fichier Markdown avec frontmatter YAML parseable et champ `type` non vide. Les consommateurs doivent tolérer champs inconnus, types inconnus, liens cassés et champs optionnels absents, tout en aidant les équipes à améliorer progressivement le bundle.
