Anyone can propose a new capability or media definition for the CapDAG registry. The registry is community-curated, and a definition that is well-formed, fills a real gap, and is documented clearly enough for others to use is a candidate for inclusion. Submissions happen through the GitHub issue tracker on the capfab repository. The published fabric registry is the canonical reference for definitions that are live.
How submissions work
There is no automated merge. Every proposal is read by a maintainer; we work with the submitter on any rough edges; and once the shape is right, the new definition appears in the versioned registry and on capdag.com.
You submit JSON. Browse capdag.com for live examples of accepted definitions. The proposal schemas live at cap.schema.json and media.schema.json.
What to submit
Open an issue on capfab using one of the templates below.
| To do this | Template |
|---|---|
| Add a capability or media definition | Add definition |
| Report a problem, ask a question, or propose a change | Definition feedback |
The full template picker is at github.com/machinefabric/capfab/issues/new/choose.
What makes a good capability submission
- A real, distinct operation. Do not re-skin an existing capability with cosmetic tags. Input, output, operation tags, and effect all participate in the CapDAG contract; see Predicates and Cap URN structure.
- Documentation that says when to use it and when not to. End users discover capabilities by reading the
documentationfield on capdag.com. A bare line like “convert X to Y” doesn’t give them enough to decide. Tell them what upstream produces this kind of thing, what downstream consumes the output, and what neighbouring capabilities they might be confusing it with. - Argument shape that follows established patterns. Inspect neighboring live definitions on capdag.com before writing yours.
- A URN that survives review. URNs are tagged URNs; once published, the URN is the permanent key. Picking the right tags up front matters.
What makes a good media def submission
- A type with a clear shape and a clear role. Specs that overlap heavily with an existing one will be sent back to merge. If you think you need a new spec, explain in the rationale why an existing spec doesn’t fit: what flow gets blocked, which existing type is too general or too specific.
- A
media_type, atitle, and adocumentationblock. Thedocumentationshould explain when to use this type vs. neighbouring types, not just describe what it represents in isolation. - Stable extensions if relevant. For media types tied to file formats, list the canonical file extensions in
extensionsso file-based ingestion can map by extension.
Removals and edits
Removals are weighed against impact. Definitions in the registry are referenced by deployed cartridges, by published capdag.com pages, and by users’ saved machine notations. We will work with you on a deprecation path before removing anything that is in active use.
Edits change a definition’s metadata (title, docs, content type, extensions) but never change its URN. The URN is the permanent key; renaming a URN is not an edit, it is a removal plus a fresh add.
What’s out of scope
- Implementations of capabilities. The capfab registry is a directory of capability and media definitions, not a place to publish cartridges or implementations. Cartridges are distributed separately. A capability can exist in the registry before any implementation exists.
Conduct
Be kind. If a maintainer asks you to revise a submission, it is because we want to merge it.