CAPNS Documentation

What CAPNS Is

CAPNS (Capability Namespace System) gives computational operations structured names. A PDF text extractor, a language translator, an image classifier — each gets a URN that describes what it does. Programs can then discover available capabilities and match requests to implementations without knowing anything about each other in advance.

A capability URN looks like this:

cap:in="media:pdf;bytes";op=extract;out="media:text;utf8"

This names a capability that takes PDF bytes as input, performs extraction, and produces UTF-8 text as output. The URN is self-describing: you can read it and know what the capability does.

The Three Parts

CAPNS has three parts. Each solves a different problem.

URN Syntax

The naming format. A capability URN starts with cap: and contains semicolon-separated key-value tags. Tags describe what the capability operates on, what operation it performs, and what it produces. The syntax defines how tags are written, how values are quoted, how URNs are normalized to canonical form, and what special values like * and ! mean.

Matching Algorithm

The rules for deciding whether a capability can handle a request. Matching is directional: pattern.accepts(instance) checks whether an instance satisfies all constraints in a pattern. Each tag is evaluated independently using a truth table. Direction specifiers (in and out) use semantic subtype matching rather than exact string comparison.

Specificity

When multiple capabilities match a request, specificity determines which one wins. Each tag gets a score based on how constrained it is: exact values score highest, wildcards score lower, unconstrained tags score zero. The capability with the highest total score is the best match.

Beyond Naming

Capability Definitions

A JSON format for describing what a capability does in detail: its arguments, their types, its output format. Definitions make capabilities self-documenting and let tools generate UIs or validate inputs automatically.

Libraries

Implementations in Rust, Go, JavaScript, and Objective-C/Swift. All produce identical results for parsing, matching, and specificity. The Rust implementation is the reference.

API Reference

The registry provides a REST API for looking up capabilities by URN, listing all registered capabilities, and finding matches for a request.