GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Proposal: an opt-in `okf_profile` declaration (parallel to `okf_version`) — plus a spec clarification on root-index frontmatter keys
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
§9's conformance surface is deliberately minimal: parseable frontmatter, non-empty `type`, reserved-file structure. Everything else about authoring quality is left to producers — so every serious producer builds a private validation layer. This tracker is itself the evidence: #196 (`okft`) is an independently built community linter, and we built our own before finding it.
Proposal: give that layer a *name* the format understands — an optional, domain-scoped profile declaration — and clarify one spec seam it depends on.
## The proposal (opt-in, advisory, no consumer change)
A bundle MAY declare, in root-index frontmatter beside `okf_version`:
```yaml
okf_version: 0.1
okf_profile: civic-v1
```
A profile is a producer-published document that pins, for one domain: a `type` vocabulary, any required-beyond-`type` fields, and lint rules. Consumers that don't know the profile ignore the key — exactly the `okf_version` mechanism §11 already established. Nothing becomes rejectable; profile checks are authoring-time warnings, never consumer-side errors. This is deliberately NOT a central or mandatory type registry (an explicit spec Non-goal) — profiles are domain-scoped, opt-in, and live with their producers.
Why it's worth a spec-level convention rather than staying private: interop between the authoring tools this ecosystem is already growing. A linter like #196's `okft` could read a declared profile and apply the domain's rules instead of only generic hygiene checks; two producers in the same domain could share one profile instead of two private validators.
## The spec clarification this depends on
We hit a genuine ambiguity implementing this: **may a producer key appear in root-index frontmatter at all?** §4.1's extension-key permission governs *concept documents*; §6 says index files contain no frontmatter; §11 carves an exception for `okf_version` in the root index — and is silent on additional keys. `okf_profile` (or any bundle-level producer key) has no clearly legal home. A one-line clarification in §6 or §11 — "the root index MAY carry additional producer keys beside `okf_version`" (or "MUST NOT," and bundle-level metadata belongs somewhere else) — would settle it either way.
## Evidence
We publish an OKF v0.1 bundle of local-government public records for a large county in the US Northeast (~230 concepts), authored under a `civic-v1` profile: a pinned civic `type` vocabulary, per-type required fields, a typed-relation vocabulary (see comment on #148), and a linter that warns on broken links, missing `resource`/`description`, orphan concepts, and index-vs-atom drift. The profile mechanism is what lets us keep the bundle strictly v0.1-conformant while enforcing domain rules — a compatible superset, not a fork. Our validator predates #196's `okft` and overlaps it heavily, which is the reinvention problem in miniature.
Happy to contribute the validator as a reference implementation, or draft the profile-mechanism text, if maintainers are interested.
Contributor guide
Research direction
Start by reading the conformance rules in §4.1, §6, and §11, then compare the existing `okf_version` handling with the profile proposal. Review #196 and the related typed-relation discussion in #148 for compatibility context. Done means maintainers resolve the root-index-key ambiguity and, if accepted, define the opt-in profile convention in the specification.
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
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100