GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Proposal: Rename required field `type` -> `kind`; reserve `type` for media type
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Proposal
Rename the one required field from `type` to `kind`. Optionally let `type` hold a media type. No fields added or removed.
**Why:** in many formats `type` already means "media/content type" (`text/plain`, `image/svg+xml`). OKF uses it for a semantic category (`BigQuery Table`). That overload can break portability and sits a little awkwardly with the standard governing OKF's own files.
**Three reasons:**
1. **Many comparable formats reserve `type` for the media type.** AsciiDoc uses `doctype` for the document kind; the `text/markdown` media-type spec (RFC 7763) uses a `variant` parameter for the flavor, keeping `type`/`subtype` for the media type; and RFC 7764 names the "kind of document" field `category` (kramdown-rfc), not `type`. A dedicated word for "what kind of thing" is the common pattern.
2. **The overload can cause real collisions.** OKF is designed for cross-tool exchange (§1). There are already file-based knowledge tools whose `type` field *is* the MIME type - so importing a concept would put `type: Flowchart about xyz` into a slot that expects `image/svg+xml`. Using `kind` avoids that clash entirely.
3. **Freeing `type` is a net gain.** Concepts often point at a real asset via `resource` (§4.1), and those assets have genuine media types OKF currently has nowhere to put:
```yaml
kind: Flowchart
resource: https://example.com/architecture
type: image/svg+xml
```
This also lets agents triage and index on frontmatter alone - no fetching or expensive vision-model passes per asset.
```yaml
kind: Flowchart
resource: https://example.com/architecture
type: application/vnd.mermaid
```
That's basically the same **kind** but a completely different skill set needed to be used to handle the resource.
**As a user** I would like to be able to ask.
Q: What kind of info is that? A: ToDo
Q: What type? A: text/markdown; variant=GFM ... because GFM allows to use `- [x] tasks`. Other variants do not
**Cost:** very low right now (v0.1 Draft; §11 already anticipates renaming required fields at a major bump), versus a breaking change later.
**Ask:** rename `type` -> `kind`, and keep `type` optional and authoritative when present.
---------
- IMO this will immediately solve the problem rased by @jdevalk
- see: #111
- IMO related: #93 posted by @magnus919
Contributor guide
Research direction
Start with the OKF specification sections referenced in the proposal, especially §1, §4.1, and §11, then review related issues #111 and #93 for existing constraints. Done means the required field is consistently specified as kind, type is optional and authoritative for media types, and no fields are added or removed.
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
- 45/100