GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: an opt-in `okf_profile` declaration (parallel to `okf_version`) — plus a spec clarification on root-index frontmatter keys

Open
#212 7 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.