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:
-
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.
-
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.
-
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:
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.
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.
Proposal
Rename the one required field from
typetokind. Optionally lettypehold a media type. No fields added or removed.Why: in many formats
typealready 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:
Many comparable formats reserve
typefor the media type. AsciiDoc usesdoctypefor the document kind; thetext/markdownmedia-type spec (RFC 7763) uses avariantparameter for the flavor, keepingtype/subtypefor the media type; and RFC 7764 names the "kind of document" fieldcategory(kramdown-rfc), nottype. A dedicated word for "what kind of thing" is the common pattern.The overload can cause real collisions. OKF is designed for cross-tool exchange (§1). There are already file-based knowledge tools whose
typefield is the MIME type - so importing a concept would puttype: Flowchart about xyzinto a slot that expectsimage/svg+xml. Usingkindavoids that clash entirely.Freeing
typeis a net gain. Concepts often point at a real asset viaresource(§4.1), and those assets have genuine media types OKF currently has nowhere to put:This also lets agents triage and index on frontmatter alone - no fetching or expensive vision-model passes per asset.
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 notCost: 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 keeptypeoptional and authoritative when present.