The new dictionary for AI and Agentic Workflows — OKF in LookML
In mid-June 2026, Google announced a new open framework that hones in on utilising AI’s best kept secret — optimised markdown files. In this article, I’ll explain how I’ve used Open Knowledge Format in Looker Studio to produce documentation that both humans and computers can read.
What is Open Knowledge Format?
Essentially, it is a format and document structure of markdown files for both humans and AI to read and gather context on the project without reading line by line code in each file. I think of it as a dictionary of the entire project.
The power of this format comes from its flexibility in content combined with a rigorous structure. For example, the YAML front matter can contain structured and unstructured data but the format is always the same. Furthermore, there is no vendor lock-in and it’s portable meaning you do not need to stick with a particular documenting software like Notion or Obsidian as they are all markdown files.
How do you set the Open Knowledge Format?
There are three components to making the document structure OKF like:
1. Project Structure
docs/
├── index.md <-- Required OKF entry point
├── log.md <-- Required OKF change log
├── explores/
│ ├── index.md
│ └── orders.md <-- Individual concept file
└── metrics/
├── index.md
└── revenue.md <-- Individual concept fileThe document folder structure must contain the index.md and the log.md . Each folder should also contain its own index.md . This file contains the overview of what’s inside the project, very similar to having __init__.py files to let Python know to read the folder. The log.md file contains the version history, so what was changed, by who and when. This information helps you keep track of the team changes and what they did.
2. YAML Front Matter
---
type: LookML Metric
title: Avg Order Value
description: Average revenue per unique order (AOV). Defined on the fact_orders hub view.
resource: views/core/fact_orders.view.lkml
tags: [aov, revenue, metric, calculated]
timestamp: 2026-06-19T00:00:00Z
---Within the all files except log.md, the start of the markdown file should include this section called the YAML Front Matter. This helps categorise the file with the most relevant information so that the agent/RAG system can find the file first before reading the content in it to give a context-driven answer.
3. Cross linking
This part is the trickiest. Just like Obsidian, you can create a knowledge graph to see how each file connects to each other interactively. Google does ship a visualiser that helps to put the dots on paper in a html view.
See the [customers table](/tables/customers.md) for the join key.
# Taken from the documentation of Google SPEC.mdMore importantly, to create those links, the files contain cross-links that connecting concepts to each other. For more information, you can find the section in the spec.md file here. Just like Confluence, you can link the two documentations if they sit in a hierarchy like tables with primary and foreign keys.
How I set up Looker Studio’s semantic layer with this format?
Within my repository, I’ve created the overall semantic layer structure that’s required for Looker to create the data logic to provide analysts with explore, dashboards and conversations.
analytics-looker-models/
│
├── docs/ ← WORDS folder. explain stuff to human.
│ ├── README.md
│ └── architecture.md
│
├── core_library/ ← HUB. share view.
│ ├── manifest.lkml
│ └── views/
│ └── orders.view.lkml
│
└── region_us/
├── manifest.lkml
├── region_us.model.lkml
└── views/
└── orders.view.lkml ← +view. add region stuff.The layout above is an example of this setup. It follows the Hub and Spoke method where the Hub controls the definitions that can be inherited to the Spokes so that you do the heavy effort once, it gets reused through each spoke.
Get Sajid Ahmed’s stories in your inbox
Join Medium for free to get updates from this writer.
The documentation sits in the root folder as well as the sub-folders. The docs can explain everything regarding the core, regional and main repository.
Within the agent file (CLAUDE.md)
To make this setup fully autonomous and CI/CD like, the CLAUDE.md file manages the continuous updates you make to the project. Any changes, additions or restructuring automatically gets updated in the logs and documentation files so you work on the actual content and Claude works to write it up. Here is part of my Claude file:
# Looker Development Rules
Whenever you create, modify, or delete a LookML view, explore, or metric:
1. You must immediately update or create the corresponding OKF markdown file in the `docs/` folder.
2. Ensure the YAML frontmatter includes the correct `type`, `title`, and `resource` path.
3. Keep the business logic explanations in plain, accurate English.
The Directory Structure (The OKF "Bundle")
Tell Claude exactly where files go. OKF groups files by concept type in a single directory:
```Plaintext
docs/
├── index.md <-- Required OKF entry point
├── log.md <-- Required OKF change log
├── views/
│ ├── index.md
│ └── users.md <-- Individual concept file
├── explores/
│ ├── index.md
│ └── orders.md <-- Individual concept file
└── metrics/
├── index.md
└── revenue.md <-- Individual concept file
```
---
The Strict OKF Frontmatter Schema
OKF v0.1 only forces one mandatory field (type), but relies heavily on 5 other reserved fields. Instruct Claude to strictly use this exact YAML block:
```yaml
---
type: [LookML View | LookML Explore | LookML Metric] # Mandatory
title: String
description: String
resource: String (The path to the LookML file, e.g., views/users.view.lkml)
tags: [array, of, tags]
timestamp: ISO8601 String (e.g., 2026-06-18T14:00:00Z)
author: String (GitHub username of who last changed this concept, e.g., @octocat)
---
```Why does this all matter?
I’ve explained the generic setup and the way I’ve applied it to Looker. But the reason for this all comes down to human laziness. We’ve had those moments where we come back to a Confluence page we made 3 years ago and find all the relevant information and links are broken and out-of-date. With AI, we can now have an agent set up to do the (let’s be honest) boring part of the fancy work — documentation.
By setting up a strict agent file, your agent can keep a CI/CD flow of the work you do, log changes for visibility for your team and help you find the relevant information quickly. In my eyes, you kill two birds with one stone: quickly onboard new analysts with all the information they may need, and give AI the relevant business knowledge it needs to reference.
