cap: Documentation
Browse Sign In

Capability Schema

Serialized JSON format for Cap definitions, arguments, outputs, and media specs

Top-Level Shape

Serialized capability objects use these fields:

{
  "urn": "cap:in=\"media:void\";op=extract;out=\"media:record\"",
  "title": "Extract Metadata",
  "command": "extract-metadata",
  "cap_description": "Extracts structured metadata from documents",
  "metadata": {"activity_timeout_secs": "300"},
  "media_specs": [ ... ],
  "args": [ ... ],
  "output": { ... },
  "metadata_json": { ... },
  "registered_by": "pdfcartridge"
}
Field Type Required Description
urn string yes Canonical Cap URN string
title string yes Human-readable name
command string yes CLI subcommand name (slug)
cap_description string no Description of what this cap does
metadata object no String-keyed metadata (e.g., activity_timeout_secs)
media_specs array no Inline media spec definitions (override registry)
args array yes Input argument definitions
output object no Output definition
metadata_json object no Arbitrary JSON metadata
registered_by string no Source identifier

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": "The input text to process",
  "default_value": "hello world",
  "metadata": { ... }
}
Field Type Required Description
media_urn string yes Media URN identifying this argument type
required bool yes Whether the argument must be provided
sources array yes How the argument can be provided (CLI mode)
arg_description string no Human-readable description
default_value any no Default value (as JSON)
metadata object no Arbitrary metadata

Argument Sources

Each source specifies one way to provide the argument in CLI mode:

Source Format Description
stdin {"stdin": "media:textable"} Primary input stream. The stdin media URN identifies the data type
position {"position": 0} Positional CLI argument (0-based index)
cli_flag {"cli_flag": "--model"} Named CLI flag

Source restrictions (enforced by validation rules):

  • Sources must not be empty (RULE2)
  • Multiple stdin sources must use identical media URN (RULE3)
  • No duplicate source type within one arg (RULE4)
  • One arg cannot have both position and cli_flag (RULE7)

Output

{
  "media_urn": "media:record;textable",
  "output_description": "JSON object with extracted metadata fields",
  "metadata": { ... }
}
Field Type Required Description
media_urn string yes Media URN for output type
output_description string yes Human-readable description
metadata object no Arbitrary metadata

Media Spec Definitions

Inline media_specs define custom media types local to this cap:

{
  "urn": "media:my-output;json",
  "media_type": "application/json",
  "title": "Custom Output Format",
  "profile_uri": "https://example.com/schema.json",
  "schema": { "type": "object", "properties": { ... } },
  "description": "...",
  "validation": { ... },
  "metadata": { ... },
  "extensions": [".json"]
}
Field Type Required Description
urn string yes Media URN for this spec
media_type string yes MIME type
title string yes Human-readable name
profile_uri string no JSON Schema URI
schema object no JSON Schema (Draft-07) for validation
description string no Description
validation object no Semantic validation rules
metadata object no Arbitrary metadata
extensions array no File extensions (e.g., [".json"])

Media Resolution

When resolving a media URN to its spec:

  1. Cap-local media_specs (highest priority)
  2. Registry cache (bundled standard specs)
  3. Registry lookup (remote fetch)
  4. Error if unresolved: UnresolvableMediaUrn

Inline specs override registry specs for the same URN. However, cross-validation rule XV5 prevents redefining built-in specs — InlineMediaSpecRedefinesRegistry is raised if a cap’s media_specs attempts to shadow a standard spec.

References