Proposal: bundle authoring metadata for OKF

[filipdanisko]

I couldn’t find specific guidance for how OKF specification proposals should be submitted, so I’m starting this as a GitHub Discussion because it seems like the most appropriate place for early design feedback. If there is a preferred process, template, or location for OKF spec proposals that I missed, please point me there and I’ll move or reshape this accordingly. Thank you.

I’d like to propose a small optional metadata layer for OKF bundles that helps tools and agents understand how a bundle should be discovered, presented, and loaded.

This is related to #96 Metadata orientation hints, but focused specifically on bundle authoring: metadata declared by the bundle itself, so consumers can process the bundle without requiring separate external configuration.

Problem

An OKF bundle can be valid and portable, but a generic consumer still has to infer several things:

• What should this bundle be called?
• What is the bundle useful for?
• Which document should be loaded by default?
• When should a consumer suggest or load this bundle?

For human readers, prose documentation may be enough. For tools, it would be useful to have a small, predictable, machine-readable authoring convention.

Proposal

Allow OKF bundles to optionally declare bundle-level metadata in the root index.md frontmatter.

Example:

---
okf_version: "0.1"
okf_bundle_name: accessibility
okf_bundle_title: Accessibility Base
okf_bundle_purpose: Accessibility guidance for UI, HTML, ARIA, keyboard navigation
okf_bundle_tags:
  - accessibility
  - ui
  - review
okf_bundle_entry_default: "index.md"
okf_bundle_entry_<entry_name>: "<file>.md"
---

The metadata would be optional. A bundle with only okf_version: "0.1" would remain valid and consumable.

Entrypoints

The bundle-level metadata can define named entrypoints, for example:

okf_bundle_entry_default: "index.md"
okf_bundle_entry_aria: "aria/index.md"
okf_bundle_entry_review: "accessibility_review.md"

If okf_bundle_entry_default is missing, consumers should fall back to index.md at the bundle root.

Entry-specific usage hints

For entry-specific hints, there is already a related proposal: [#96 Metadata orientation hints](#96).

This proposal focuses on bundle-level metadata in the root index.md. Together, bundle-level entrypoint metadata and document-level orientation hints would let consumers first discover the right bundle and entrypoint, then use document-level metadata to understand when and how that specific entrypoint should be loaded.

Why bundle-authored metadata?

Consumers may use this metadata for:

• bundle discovery
• catalog display
• agent/tool routing
• task-based suggestions
• selecting the right entrypoint
• lightweight discovery without reading the whole bundle
• UI presentation in catalogs or tools

Consumers that do not understand these fields should ignore them.

Consumers should not reject a bundle just because the metadata is missing or partially understood.

Relationship to OKF v0.1

This proposal is not meant to make OKF heavier or stricter. All metadata described here is optional.

Closing thoughts

This proposal is meant to open the discussion. If the idea resonates, I’d be happy to help specify it further to the level needed for a concrete spec contribution.