cap: Documentation
Browse Sign In

Capability Schema

Current serialized format used by Cap

Top-Level Shape

Serialized capability objects use these fields:

{
  "urn": "cap:...",
  "title": "...",
  "command": "...",
  "cap_description": "...",          // optional
  "metadata": {"k": "v"},          // optional
  "media_specs": [ ... ],             // optional
  "args": [ ... ],                    // optional
  "output": { ... },                  // optional
  "metadata_json": { ... },           // optional
  "registered_by": { ... }            // optional
}

Legacy arguments.required/optional and argument name/type/media structures are not the current format.

Args and Sources

args entries are keyed by media_urn identity, not by argument name:

{
  "media_urn": "media:textable",
  "required": true,
  "sources": [
    {"stdin": "media:textable"},
    {"position": 0},
    {"cli_flag": "--input"}
  ],
  "arg_description": "...",          // optional
  "default_value": "...",            // optional
  "metadata": { ... }                 // optional
}

Output

{
  "media_urn": "media:record;textable",
  "output_description": "...",
  "metadata": { ... }                 // optional
}

Media Resolution

  1. Cap-local media_specs
  2. Registry cache / registry lookup
  3. Error if unresolved

Unresolved media URNs fail hard with UnresolvableMediaUrn.

References