07 - Exemples de fichiers
Exemples de fichiers OKF : modèles concrets pour écrire vos premiers concepts
Cette page sert de boîte à modèles. L'objectif n'est pas de figer une taxonomie universelle, mais de montrer comment écrire des concept files OKF propres, typés, lisibles et directement adaptables à votre contexte.
Pourquoi partir d'exemples ?
OKF est volontairement minimal: un fichier Markdown UTF-8, un frontmatter YAML, un champ `type`, puis un body structuré. Cette simplicité est puissante, mais elle peut laisser une question très pratique: qu'est-ce que j'écris concrètement dans mon premier fichier ?
Les exemples réduisent cette ambiguïté. Ils donnent une forme de départ pour documenter une table, une métrique, un playbook, un endpoint API, une décision, un persona ou une source. Ensuite, chaque entreprise adapte les champs, les sections et les liens à son domaine.
Le bon réflexe n'est pas de tout copier mécaniquement. Le bon réflexe est de garder la logique: un type clair, une description utile, des liens vers les concepts voisins, des citations pour les affirmations importantes et un body Markdown qu'un humain peut relire.
La structure commune à tous les fichiers OKF
Tous les exemples ci-dessous suivent la même mécanique. Le frontmatter YAML donne les métadonnées exploitables par un agent: `type`, `title`, `description`, `resource`, `tags`, `timestamp`, parfois `owner` ou `status`.
Le body Markdown porte l'explication: définition, schéma, étapes, limites, exemples, liens et citations. C'est la partie qui évite qu'un concept soit seulement une fiche technique froide. Elle donne le contexte nécessaire pour agir correctement.
Les liens internes transforment les fichiers isolés en graphe de connaissance. Les citations transforment une affirmation en connaissance vérifiable. C'est cette combinaison qui rend un concept utile à la fois pour un humain, un agent, un moteur de recherche interne ou un visualizer.
Exemple 1 : BigQuery Table
Utilisez ce type quand vous voulez documenter une table, un dataset ou un actif data tangible. Le fichier doit aider un agent à comprendre le grain, les colonnes importantes, les jointures possibles et les pièges d'usage.
Même si l'exemple mentionne BigQuery, le pattern fonctionne aussi pour Snowflake, PostgreSQL, Databricks, Airtable ou n'importe quelle source tabulaire. OKF ne remplace pas le schéma technique: il ajoute le contexte métier autour du schéma.
---
type: BigQuery Table
title: Orders
description: One row per completed customer order across all sales channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, revenue, orders]
timestamp: 2026-07-08T09:00:00Z
owner: data-platform
---
# Schema
| Column | Type | Description |
| --- | --- | --- |
| order_id | STRING | Unique order identifier. |
| customer_id | STRING | Foreign key to [Customers](/tables/customers.md). |
| total_amount | NUMERIC | Order amount before refunds. |
| placed_at | TIMESTAMP | Time when the order was confirmed. |
# Joins
Join with [Customers](/tables/customers.md) on customer_id.
Use [Monthly Recurring Revenue](/metrics/mrr.md) for revenue reporting rules.
# Usage notes
Do not use cancelled orders for revenue dashboards. Use the status field
and the refund policy in [Refund Playbook](/playbooks/refund-request.md).
# Citations
[1] [BigQuery table schema](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)Exemple 2 : Metric
Une métrique est souvent l'un des meilleurs premiers concepts à créer, parce qu'elle concentre beaucoup d'ambiguïtés: formule, grain, exclusions, source de vérité, owner et usage attendu.
Documenter une métrique en OKF permet de réduire les écarts entre les équipes data, finance, sales et produit. Un agent peut aussi s'appuyer sur ce fichier pour expliquer un chiffre au lieu d'improviser une définition.
---
type: Metric
title: Monthly Recurring Revenue
description: Recurring revenue recognized for active subscriptions during a calendar month.
resource: https://bi.example.com/dashboards/revenue
tags: [finance, revenue, subscription]
timestamp: 2026-07-08T09:00:00Z
owner: revenue-ops
---
# Definition
Monthly Recurring Revenue measures the normalized recurring revenue attached
to active subscriptions for a given month.
# Formula
MRR = sum(active_subscription_monthly_amount)
# Grain
One row per account per calendar month.
# Exclusions
- Setup fees.
- Usage-based overage.
- One-time services.
- Cancelled subscriptions after the cancellation effective date.
# Depends on
- [Orders](/tables/orders.md)
- [Customers](/tables/customers.md)
- [Pricing v2 decision](/decisions/pricing-v2.md)
# Citations
[1] [Revenue dashboard](https://bi.example.com/dashboards/revenue)Exemple 3 : Playbook
Un playbook décrit une procédure actionnable: support, sales, ops, onboarding, incident, relance, qualification, validation humaine. C'est un type très utile pour les agents, car il transforme une règle orale en séquence contrôlable.
Le fichier doit indiquer le déclencheur, les étapes, les limites de décision et les escalades. C'est souvent ici qu'on évite les réponses plausibles mais risquées: l'agent sait quand agir, quand s'arrêter et quand demander une validation humaine.
---
type: Playbook
title: Support refund request
description: Steps for support agents handling a customer refund request.
tags: [support, refund, customer-success]
timestamp: 2026-07-08T09:00:00Z
owner: support
---
# Trigger
A customer asks for a refund by email, chat or ticket.
# Steps
1. Check the customer's latest order in [Orders](/tables/orders.md).
2. Verify whether the request is eligible under the refund policy.
3. If eligible, create a refund ticket with [Create Ticket API](/apis/create-ticket.md).
4. If uncertain, escalate to the customer success owner.
# Limits
The agent must not promise a refund before eligibility has been checked.
# Template
Use [Refund response template](/templates/refund-response.md) for the first reply.
# Citations
[1] [Refund policy](https://help.example.com/refund-policy)Exemple 4 : API Endpoint
Un concept `API Endpoint` ne remplace pas OpenAPI. Il doit pointer vers le contrat technique et expliquer le rôle de l'endpoint dans les workflows réels: quand l'appeler, avec quelles limites, et depuis quels playbooks.
C'est particulièrement utile quand des agents commencent à exécuter des actions. Le fichier OKF apporte la couche de contexte et de gouvernance que le contrat API seul ne porte pas toujours.
---
type: API Endpoint
title: Create support ticket
description: Endpoint used to create a support ticket from an agent workflow.
resource: https://api.example.com/openapi.yaml#/paths/~1tickets/post
tags: [api, support, ticketing]
timestamp: 2026-07-08T09:00:00Z
owner: platform
---
# Purpose
Create a support ticket when an agent needs human validation or operational follow-up.
# Request
POST /tickets
Required fields:
- customer_id
- subject
- priority
- summary
# Response
Returns ticket_id, status and created_at.
# Usage constraints
Use only after checking the relevant playbook. For refund requests,
see [Support refund request](/playbooks/support-refund-request.md).
# Citations
[1] [OpenAPI specification](https://api.example.com/openapi.yaml)Exemple 5 : Decision
Un concept `Decision` permet de garder la mémoire des choix importants: pricing, architecture, stratégie produit, politique support, règles de qualification, segmentation ou positionnement.
Pour un agent, ce type de fichier évite de raisonner comme si toutes les options étaient encore ouvertes. Il comprend ce qui a été décidé, pourquoi, à quelle date et avec quelles conséquences.
---
type: Decision
title: Pricing v2 launch
description: Decision record explaining why the pricing model changed in Q3.
tags: [pricing, product, revenue]
timestamp: 2026-07-08T09:00:00Z
owner: product
status: accepted
---
# Context
The previous pricing model made expansion revenue hard to explain and created
too many custom exceptions for the sales team.
# Decision
Move to three public plans with a usage-based add-on for advanced automation.
# Tradeoffs
- Simpler sales narrative.
- Less custom negotiation.
- Higher need for clear onboarding and pricing documentation.
# Related concepts
- [Monthly Recurring Revenue](/metrics/mrr.md)
- [Enterprise buyer persona](/personas/enterprise-buyer.md)
# Citations
[1] [Pricing research synthesis](https://docs.example.com/pricing-v2-research)Exemple 6 : Persona
Un persona OKF n'est pas une fiche marketing décorative. C'est une représentation opérationnelle d'un segment, d'un acheteur, d'un utilisateur ou d'un interlocuteur métier que les agents doivent comprendre.
Il peut alimenter des workflows de qualification, de support, de rédaction commerciale, de priorisation produit ou de génération de briefs. Le plus important est de relier le persona à des preuves et à des concepts voisins.
---
type: Persona
title: Enterprise buyer
description: Decision maker evaluating whether agent-ready context is worth prioritizing.
tags: [marketing, sales, enterprise]
timestamp: 2026-07-08T09:00:00Z
owner: go-to-market
---
# Situation
The enterprise buyer already has AI initiatives in motion, but agents remain
blocked by fragmented knowledge, unclear ownership and risk review.
# Jobs to be done
- Reduce failed agent pilots.
- Make internal knowledge easier to verify.
- Move from demos to production workflows.
# Objections
| Objection | Useful response |
| --- | --- |
| We already have Notion | OKF does not replace Notion; it creates a portable context layer. |
| The spec is young | The work of structuring context is valuable even if the format evolves. |
# Related concepts
- [Context fragmentation problem](/problems/context-fragmentation.md)
- [First bundle method](/methods/first-bundle.md)Exemple 7 : Reference ou source
Un concept `Reference` représente une source importante: annonce officielle, documentation, étude, politique interne, compte rendu, transcript, décision juridique ou page produit.
C'est utile quand plusieurs concepts citent la même source. Au lieu de répéter le contexte partout, vous créez une source de référence dans le bundle, puis vous la reliez aux concepts qui s'appuient dessus.
---
type: Reference
title: Google Cloud OKF announcement
description: Official article introducing the Open Knowledge Format.
resource: https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
tags: [okf, official, google-cloud]
timestamp: 2026-07-08T09:00:00Z
owner: knowledge
---
# Summary
Google Cloud presents OKF as an open format for representing the context,
metadata and curated knowledge that surrounds data and systems.
# Why this source matters
This is a primary source for explaining why OKF exists and how Google frames
the need for portable, human-readable and agent-readable knowledge.
# Used by
- [OKF definition](/concepts/okf-definition.md)
- [OKF principles](/concepts/okf-principles.md)Exemple 8 : Template réutilisable
Un template aide les équipes à produire des concepts cohérents sans repartir de zéro. C'est particulièrement utile quand vous commencez à créer plusieurs métriques, playbooks, décisions ou fiches API.
Le template ne doit pas devenir une contrainte bureaucratique. Il sert à rappeler les sections utiles et à rendre la contribution plus simple pour les humains comme pour les agents qui génèrent ou enrichissent les fichiers.
---
type: Template
title: Metric concept template
description: Reusable structure for documenting a business metric in OKF.
tags: [template, metric, governance]
timestamp: 2026-07-08T09:00:00Z
owner: data-governance
---
# Definition
Explain the metric in one or two sentences.
# Formula
Write the calculation in plain language or SQL.
# Grain
Define the unit of analysis: account, user, event, month, ticket, order.
# Exclusions
List what must not be counted.
# Sources
Link to tables, dashboards, APIs or reference documents.
# Citations
[1] [Source of truth](https://example.com/source-of-truth)Comment choisir le bon type de concept ?
Le `type` doit être descriptif, pas parfait. La spec OKF ne force pas une taxonomie centrale: elle demande seulement un champ `type` non vide et recommande des valeurs auto-explicatives que les consommateurs peuvent tolérer même s'ils ne les connaissent pas.
Pour choisir, partez de la question que le fichier doit aider à résoudre. Si le fichier explique une donnée, choisissez `BigQuery Table`, `Dataset` ou un type équivalent. S'il explique un calcul, choisissez `Metric`. S'il guide une action, choisissez `Playbook`. S'il justifie un choix passé, choisissez `Decision`.
BigQuery Table, Dataset, Source
Le grain, les champs et les jointures sont clairs.
Metric
La formule, les exclusions et la source de vérité sont explicites.
Playbook
Le déclencheur, les étapes et les limites sont écrits.
API Endpoint
Le contrat est relié et les contraintes d'usage sont visibles.
Decision
Le contexte, les tradeoffs et la date sont documentés.
Persona
Les jobs, objections et preuves sont reliés au reste du bundle.
Erreurs fréquentes à éviter
La première erreur est d'écrire des exemples trop génériques. Un fichier OKF doit être assez précis pour guider une action réelle. `metrics/revenue.md` est moins utile que `metrics/monthly_recurring_revenue.md` avec formule, grain et exclusions.
La deuxième erreur est de confondre OKF avec une base de données. Ne dupliquez pas toute la source technique dans le body. Référencez la source de vérité avec `resource`, puis ajoutez le contexte que les outils techniques ne portent pas bien.
La troisième erreur est d'oublier les liens. Un concept isolé est une note. Un concept relié devient une pièce d'un graphe. C'est ce maillage qui permet aux agents de naviguer sans tout charger d'un coup.
Lire ensuite
Une fois les modèles compris, la suite logique est de travailler les liens, la conformité et le workflow de création. C'est là que les exemples deviennent un système maintenable plutôt qu'une collection de fichiers copiés.
Revenir aux règles de base d'un concept file OKF.
Anatomie d'un bundleComprendre où ranger ces fichiers dans une unité de distribution.
Liens et grapheApprendre à relier les exemples entre eux.
ConformitéVérifier les règles minimales de conformité OKF v0.1.
WorkflowPasser des modèles à une production régulière de contexte.
Premier bundleChoisir un périmètre réduit pour démarrer sans cartographier toute l'entreprise.
Sources officielles et lectures utiles
Source primaire: exemples officiels de concepts, frontmatter, body, liens et citations.
OKF README.mdPrésentation officielle du format et des bundles d'exemple produits par le reference agent.
Google Cloud - Introducing OKFAnnonce officielle pour comprendre le cadrage et les cas d'usage du format.
Knowledge Catalog repoRepo officiel avec reference agent, visualizer, samples et bundles.
Sample bundle GA4Exemple officiel de bundle autour d'un dataset e-commerce GA4.
Sample bundle Stack OverflowExemple officiel de bundle autour du dataset public Stack Overflow.
Les points à retenir
Les exemples OKF ne sont pas une taxonomie fermée. Ce sont des points de départ pour écrire des concepts utiles: un type clair, un frontmatter exploitable, un body Markdown structuré, des liens internes et des citations. Commencez par les fichiers qui réduisent le plus d'ambiguïté dans vos workflows: métriques critiques, playbooks récurrents, décisions importantes et sources de vérité.
