GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Define a media type for OKF bundle artefacts (application/okf-bundle)
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Problem
OKF defines a bundle's *structure* but deliberately leaves *serving and discovery* out of scope. Discovery layers like the ARD AI Catalog let a publisher advertise a bundle by pointing an entry at the artefact — but a catalog entry is keyed by an **IANA media type**. There is no media type that identifies an artefact as an OKF bundle, so a consumer can *find* the artefact but cannot *recognise* it as OKF without sniffing the contents. Every publisher ends up inventing an interim type, and they won't agree.
## Proposal
Define (and eventually register) media types for an OKF bundle artefact:
- `application/okf-bundle` — an OKF bundle, packaging-agnostic.
- `application/okf-bundle+gzip` — a gzipped tar of the bundle tree.
- `application/okf-bundle+zip` — a zip of the bundle tree.
A consumer that recognises any of these knows the artefact is an OKF concept tree and can ingest it per the spec (`index.md` progressive disclosure, per-file `type` front matter, `log.md`, `references/`). The `+gzip`/`+zip` structured suffixes keep the compression explicit; fall back to `application/okf-bundle` when packaging is irrelevant.
## Worked example (real, resolvable)
We publish [The Website Specification](https://specification.website) as an OKF bundle generated from our content collection: 144 check concepts + a `references/` concept per cited standard, with `index.md`/`log.md`. It's served browsably and as a single tarball, and advertised through an ARD AI Catalog entry.
- Browsable tree: https://specification.website/okf/index.md
- Tarball: https://specification.website/okf.tar.gz
Today that entry uses the interim, unregistered constant `application/okf-bundle+gzip`, declared in one place and documented as interim so adopting a blessed type is a one-line change. Happy to be the reference adopter for whatever gets blessed.
Contributor guide
Research direction
Start by reviewing the proposed media types and the linked ARD AI Catalog and Website Specification examples. Locate where the interim application/okf-bundle+gzip constant is declared and documented, then determine the repository's process for defining or registering a blessed type. Done means the proposal has an agreed media-type definition and the reference adopter can replace its interim constant.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100