OKF and ARD: Complementary by Accident  🔗 **Source:** [OKF and ARD: Complementary by Accident](https://joost.blog/okf-ard/) > [!note]+ Document Notes > --- > tags: [agentic-web, open-source-governance, web-standards, interoperability, early-adoption, knowledge-packaging] > author: Joost de Valk > source: joost.blog > reference: https://joost.blog/okf-ard/ > date created: 2026-06-20 12:00 > --- > # 🏷️ Title: OKF and ARD: complementary by accident > ## 🧭 Table of Contents > - [📝 Summary](#-summary) > - [📖 Main Content](#-main-content) > - [🗒️ Notes](#️-notes) > - [📚 References](#-references) > - [🗣️ Paraphrase](#️-paraphrase) > - [📰 Newsletter](#-newsletter) > - [✅ Action Items](#-action-items) > - [🧪 Hypotheses](#-hypotheses) > - [📊 Methodology](#-methodology) > - [❓ Questions](#-questions) > - [🔮 Future Research](#-future-research) > - [💡 Implications](#-implications) > - [🧠 Learning Styles Assessment](#-learning-styles-assessment) > - [📊 Accessibility Assessment](#-accessibility-assessment) > - [🌍 DEIB Assessment](#-deib-assessment) > - [✅ Logical Validity](#-logical-validity) > - [🛡️ DARVO Analysis](#-darvo-analysis) > - [🎯 Conclusion](#-conclusion) > ### 🔗 References > - [specification.website](https://specification.website) — Joost's platform-agnostic site spec, source of the derived OKF bundle > - [OKF spec page on specification.website](https://specification.website) (rated optional) > - [ARD spec page on specification.website](https://specification.website) (rated optional) > - Google Cloud — Open Knowledge Format (OKF) origin > - Google developer blog — Agentic Resource Discovery (ARD) announcement > - Linux Foundation — ARD base spec (Agent-Card/ai-catalog) > - [joost.blog agent-ready plumbing](https://joost.blog) — runs ARD with a `did:web:joost.blog` identity > ## 📝 Summary > - **What happened.** Two new "agentic web" standards landed within a week of each other this month, both with Google's involvement: Open Knowledge Format (OKF), from Google Cloud, packages a knowledge base as typed Markdown concept files; Agentic Resource Discovery (ARD), announced on Google's developer blog atop a Linux Foundation base spec, is the discovery layer published at `/.well-known/ai-catalog.json`. Joost de Valk (Yoast founder) adopted both on specification.website and found they compose almost perfectly without referencing each other. > - **Why it matters.** This is a working field report on how a still-forming standards layer actually gets composed, debugged, and improved by an early adopter — including filing the gaps back upstream. It models "ecosystem citizen" behavior for emerging agentic-web governance. > - **Key stakeholders.** Google Cloud and Google's developer relations (the two spec authors), the Linux Foundation (base-spec steward), standards-body maintainers who must reconcile the field-name conflict, publishers adopting these specs, and AI agents that consume catalogs and bundles. > - **Risks and tradeoffs.** The two specs disagree on a media-type field name (`mediaType` vs `type`); there is no registered media type for an OKF bundle, forcing an invented interim constant (`application/okf-bundle+gzip`); both specs are v0.9 drafts that can still move; Joost rates both "optional," not "recommended." > - **Bottom line.** Don't wait for the dust to settle on a forming standards layer. Compose what exists, ship it publicly, and file what's missing upstream — that is what early adoption actually means. > ## 📖 Main Content > - **The two specs and what each does.** Open Knowledge Format (OKF), out of Google Cloud, packages a knowledge base: a tree of typed Markdown concept files with light front matter. It is deliberately narrow — serving the bundle and helping anyone find it are explicit non-goals, so a conformant OKF bundle sitting on a server is by design undiscoverable. Agentic Resource Discovery (ARD), announced on Google's developer blog and built on a Linux Foundation base spec, is the discovery layer OKF omits: you publish a catalog at `/.well-known/ai-catalog.json` listing what your domain offers, and an entry can point directly at an OKF bundle. > - **Why they compose.** On their own each is partial — OKF packages a knowledge base it leaves undiscoverable; ARD is a discovery layer that only pays off when there's something worth pointing at. Composed, the catalog sends an agent straight to the bundle. That complementarity is why Joost shipped both rather than picking one. > - **Everything derived, nothing hand-written.** specification.website is generated from one content collection: HTML pages, per-page Markdown mirror, llms.txt, and the data the MCP server reads are all derived from the same source. The OKF bundle is one more output of that pipeline, not a second copy to keep in sync. It comes to 604 Markdown files: 144 check concepts (paths mirror canonical URLs), 445 reference concepts (one per distinct cited source), plus OKF's index files; a `/okf.tar.gz` offers the whole thing in one fetch. The ARD catalog lists four pre-existing entries: the MCP server, the A2A agent, the Agent Skill, and the new bundle. > - **The standard that disagrees with itself.** The AI Catalog format is pinned in two places — a base spec (`Agent-Card/ai-catalog`) and the ARD layer (`ards-project/ard-spec`) built on it — and they use different names for the media-type field: the base uses `mediaType`, ARD uses `type`. ARD also added a `representativeQueries` array. Joost's pragmatic fix: carry both field names with the same value in every entry. Because both specs require consumers to ignore unrecognised keys, the dual-field entry validates under either reading. > - **The gap nobody registered.** There is no registered media type for an OKF bundle, so Joost invented `application/okf-bundle+gzip`, shipped as a single documented constant marked interim. Without a blessed type, a consumer can't recognise a bundle as OKF without opening it, and every publisher would invent a different string that never converges. So he filed the fix in both places — an issue on OKF to define and register the type, and one on ARD to recognise it (also flagging the `type` vs `mediaType` split) — offering the live bundle as a reference adopter. > - **Optional, on purpose.** specification.website grades every feature required / recommended / optional / avoid. Both ARD and OKF pages are rated optional, not recommended, because they are v0.9 drafts that can still move; the site's rule is to adopt early but rate honestly. joost.blog also runs ARD atop its agent-ready plumbing with a `did:web:joost.blog` identity tied to a Bluesky account. > - **Contested / uncertain.** Whether the two specs converge, which field name becomes canonical, and whether a registered OKF media type lands are all open. "Both have Google's fingerprints on them" is an attribution claim, not formal sole authorship — the base spec is a Linux Foundation artifact. > ### 🗒️ Notes > - Two agentic-web standards landed within a week; neither references the other; one (the AI Catalog format) doesn't even agree with itself on a field name. > - OKF = Open Knowledge Format, from Google Cloud — packages a knowledge base as typed Markdown concept files with front matter. Deliberately narrow: serving and discovery are explicit non-goals. > - A conformant OKF bundle on a server is, by design, undiscoverable — that's the gap ARD fills. > - ARD = Agentic Resource Discovery, from Google's developer blog, built on a Linux Foundation base spec. Catalog lives at `/.well-known/ai-catalog.json`; an entry can point straight at an OKF bundle. > - The two specs "fit exactly" by accident, not coordination — the headline thesis. > - Derivation pipeline: one content collection → HTML, Markdown mirror, llms.txt, MCP data, AND the OKF bundle. The bundle is "one more output," not a synced copy. > - Bundle size: 604 Markdown files = 144 check concepts (paths mirror canonical URLs) + 445 reference concepts (one per cited source) + OKF index files. Plus `/okf.tar.gz`. > - ARD catalog lists four already-existing entries: MCP server, A2A agent, Agent Skill, new bundle. > - Field-name conflict: base spec `Agent-Card/ai-catalog` uses `mediaType`; ARD layer `ards-project/ard-spec` uses `type`. ARD adds `representativeQueries` (sample prompts). > - Fix: dual-field entries carry both `type` and `mediaType` with identical value; valid under either reading because both specs mandate ignoring unrecognise Two new standards for the agentic web landed within a week of each other this month. Both have Google’s fingerprints on them. Neither references the other, and one does not even agree with itself about what to call a field. I adopted both on [specification.website](https://specification.website) this week, bracing for the usual overlap. There is none. They are two separate ideas that happen to connect almost perfectly. #### Two ideas that connect [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog) (OKF), out of Google Cloud, is a way to package a knowledge base: a tree of typed Markdown concept files with a little front matter. It is deliberately narrow. Serving the bundle and helping anyone find it are explicit non-goals. A conformant OKF bundle sitting on a server is, by design, undiscoverable. [Agentic Resource Discovery](https://agenticresourcediscovery.org/) (ARD), announced on Google’s developer blog and built on a Linux Foundation base spec, is the discovery layer OKF leaves out. You publish a catalog at `/.well-known/ai-catalog.json` listing what your domain offers, and an entry can point straight at an OKF bundle. On their own, each is partial: OKF packages a knowledge base it deliberately leaves undiscoverable, and ARD is a discovery layer that only pays off when there is something worth pointing at. Composed, they fit exactly, with the catalog sending an agent straight to the bundle. That is why I shipped both instead of picking one. #### Everything derived, nothing hand-written specification.website, the [platform-agnostic spec I shipped last month](https://joost.blog/fixing-the-plumbing/), is already generated from one content collection. The HTML pages, the per-page Markdown mirror, llms.txt, the data the MCP server reads: all derived from the same source. The OKF bundle is one more output of that pipeline, not a second copy to keep in sync. It comes to 604 Markdown files: 144 check concepts whose paths mirror their canonical URLs, 445 reference concepts (one per distinct cited source), and the index files OKF wants in between. There is also a [`/okf.tar.gz`](https://specification.website/okf.tar.gz) for anyone who wants the whole thing in one fetch. The ARD catalog now lists four entries, all of which already existed: the MCP server, the A2A agent, the Agent Skill, and the new bundle. #### The standard that disagrees with itself The AI Catalog format is pinned down in two places, a base spec and the ARD layer built on it, and the two use different names for an entry’s media-type field: | Spec | Media-type field | | --- | --- | | AI Catalog base ([`Agent-Card/ai-catalog`](https://github.com/Agent-Card/ai-catalog)) | `mediaType` | | ARD layer ([`ards-project/ard-spec`](https://github.com/ards-project/ard-spec)) | `type` | The ARD layer also added a `representativeQueries` array of sample prompts. My first catalog used `mediaType` and was correct against the base spec; a registry validating against ARD would want `type`. The pragmatic fix is to do both. Every entry now carries both field names with the same value: ``` { "type": "application/okf-bundle+gzip", "mediaType": "application/okf-bundle+gzip", "url": "https://specification.website/okf.tar.gz" } ``` Both specs require consumers to ignore keys they do not recognise, so the dual-field entry validates under either reading. Early adoption sometimes means carrying two spellings of the same field until the base spec and the layer built on it line up. #### The gap nobody registered The OKF bundle entry exposes a real hole. There is no registered media type for an OKF bundle, so I had to invent one: `application/okf-bundle+gzip`, shipped as a single documented constant marked interim. A catalog can list the bundle, but without a blessed type a consumer cannot recognise it as OKF without opening it. Every publisher will invent a different string, and they will never converge. So I did the ecosystem-citizen thing and filed the fix in both places, offering the live bundle as a reference adopter: [one issue on OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/issues/111) to define and register the type, and [one on ARD](https://github.com/ards-project/ard-spec/issues/27) to recognise it, which also flagged the `type` versus `mediaType` split. Being an early adopter is not only implementing the draft. It is finding the gap the draft left and pushing it back upstream. #### Optional, on purpose [specification.website](https://specification.website) is my platform-agnostic spec of what a good website ships, and it grades every feature it documents as required, recommended, optional, or avoid. Both new spec pages, [ARD](https://specification.website/spec/agent-readiness/agentic-resource-discovery/) and [OKF](https://specification.website/spec/agent-readiness/okf-bundle/), are rated optional, not recommended. They are v0.9 drafts that can still move, and the site’s rule is to adopt early but rate honestly. This blog runs ARD too, on top of [the rest of its agent-ready plumbing](https://joost.blog/agent-ready/), with a `did:web:joost.blog` identity tied to [my Bluesky account](https://bsky.app/profile/joost.blog), but that is a story for another day. Two overlapping, half-coordinated standards in a single week is not a scandal. It is the normal texture of a layer that is still forming. The useful response is not to wait for the dust to settle. It is to compose what is already there, ship it where people can see it, and file what is missing., OKF and ARD: Complementary by Accident, joost.blog, 01kvkr1yg8af1yqp04rxdrd89j.