cap: Documentation
Browse Sign In

Validation Rules

CU1-CU2, RULE1-RULE12, MS1-MS3, XV1-XV5: structural validation constraints

Overview

All implementations MUST enforce these rules identically. Validation order:

  1. Structural validation (JSON Schema)
  2. Cap URN validation (CU1-CU2)
  3. Cap definition rules (RULE1-RULE12)
  4. Media spec rules (MS1-MS3)
  5. Cross-validation (XV1-XV5)
Category Rules Scope
Cap URN Rules CU1-CU2 URN structure
Cap Definition Rules RULE1-RULE12 Capability arguments
Media Spec Rules MS1-MS3 Media specifications
Cross-Validation Rules XV1-XV5 Reference integrity

Cap URN Rules

CU1: Required Direction Specifiers — Cap URNs in canonical form MUST include in and out tags. Surface syntax may omit them (they default to media:).

CU2: Valid Media URN References — Direction values must be valid Media URNs (starting with media:) or * (which normalizes to media:).

Cap Definition Rules (RULE1-RULE12)

  1. RULE1: No duplicate media_urns across arguments.
  2. RULE2: sources must not be empty.
  3. RULE3: Multiple stdin sources must use identical stdin media URN.
  4. RULE4: No duplicate source type inside one arg.
  5. RULE5: No duplicate positional index across args.
  6. RULE6: Positions must be 0-based sequential with no gaps.
  7. RULE7: One arg cannot have both position and cli_flag.
  8. RULE8: Unknown source keys rejected by serde deny_unknown_fields.
  9. RULE9: No duplicate cli_flag across args.
  10. RULE10: Reserved CLI flags forbidden: manifest, --help, --version, -v, -h.
  11. RULE11: cli_flag is used verbatim (no auto-prefixing with --).
  12. RULE12: Argument identity is media_urn; no separate name key.

Media Spec Rules (MS1-MS3)

MS1: Every media spec MUST have a title field.

MS2: Media URNs MUST start with media: prefix.

MS3: Every media spec MUST have a media_type field (MIME type).

Cross-Validation Rules (XV1-XV5)

XV1: No duplicate cap URNs in the same registry.

XV2: No duplicate media URNs in standalone definitions.

XV3: All media URNs referenced in capabilities MUST resolve. Resolution order: cap-local media_specs → registry cache → registry lookup. No fallbacks — unresolved URNs fail hard with UnresolvableMediaUrn.

XV4: Inline media specs MUST have a title field.

XV5: Inline media specs MUST NOT redefine specs that exist in the global registry. Raises InlineMediaSpecRedefinesRegistry.

Schema Validation Flow

When validating argument or output values against their media spec schemas:

  1. Resolve media URN via cap-local specs, then registry.
  2. If resolved spec has no JSON schema, skip schema check.
  3. Compile Draft-07 schema (cached by schema JSON via SchemaValidator).
  4. Validate argument/output JSON value against compiled schema.
  5. Return detailed validation errors on failure.

The SchemaValidator compiles each unique JSON Schema once and caches it for subsequent validations.

Implementation Requirements

  • Fail hard: All errors cause immediate failure with clear messages. No fallbacks, no silent recovery, no default values for required fields.
  • Consistent behavior: All implementations (Rust, Go, Python, JavaScript, Swift) enforce identical rules.
  • Error codes: CU1-CU2 (URN), RULE1-RULE12 (args), MS1-MS3 (media), XV1-XV5 (cross-validation).

Summary Table

Rule Description Scope
CU1 Required in/out tags URN
CU2 Valid media URN values URN
RULE1 No duplicate media_urns Args
RULE2 Non-empty sources Args
RULE3 Identical stdin media_urns Args
RULE4 No duplicate source types Args
RULE5 No duplicate positions Args
RULE6 Sequential positions Args
RULE7 No position + cli_flag combo Args
RULE8 No unknown source keys Args
RULE9 No duplicate cli_flags Args
RULE10 Reserved cli_flags forbidden Args
RULE11 CLI flags verbatim Args
RULE12 media_urn as identifier Args
MS1 Title required Media
MS2 media: prefix required Media
MS3 media_type required Media
XV1 No duplicate cap URNs Cross
XV2 No duplicate media URNs Cross
XV3 All media URNs resolve Cross
XV4 Inline specs need title Cross
XV5 No registry redefinition Cross

References