reuse-surface/schemas/capability.schema.yaml

$schema: https://json-schema.org/draft/2020-12/schema
$id: https://reuse-surface.local/schemas/capability.schema.yaml
title: Capability Registry Entry
description: >
  JSON Schema for YAML front matter in Markdown capability entries under
  registry/capabilities/. Aligns with specs/CapabilityMaturityStandard.md.
type: object
additionalProperties: false
required:
  - id
  - name
  - summary
  - owner
  - status
  - maturity
  - external_evidence
properties:
  id:
    type: string
    pattern: '^capability(\.[a-z][a-z0-9-]*)+$'
    description: Stable reverse-domain capability identifier.
  name:
    type: string
    minLength: 1
  summary:
    type: string
    minLength: 1
  owner:
    type: string
    minLength: 1
  status:
    type: string
    enum: [draft, reviewed, approved, deprecated]
  domain:
    type: string
    description: Optional domain or product scope for filtering.
  tags:
    type: array
    items:
      type: string
  maturity:
    type: object
    additionalProperties: false
    required: [discovery, availability]
    properties:
      discovery:
        $ref: '#/$defs/internalMaturityDimension'
      availability:
        $ref: '#/$defs/internalMaturityDimension'
  external_evidence:
    type: object
    additionalProperties: false
    required: [completeness, reliability]
    properties:
      completeness:
        $ref: '#/$defs/completenessEvidence'
      reliability:
        $ref: '#/$defs/reliabilityEvidence'
  discovery:
    type: object
    additionalProperties: false
    properties:
      intent:
        type: string
      includes:
        type: array
        items:
          type: string
      excludes:
        type: array
        items:
          type: string
      assumptions:
        type: array
        items:
          type: string
      use_cases:
        type: array
        items:
          type: string
      research_memos:
        type: array
        items:
          type: string
  availability:
    type: object
    additionalProperties: false
    properties:
      current_level:
        $ref: '#/$defs/availabilityLevel'
      target_level:
        $ref: '#/$defs/availabilityLevel'
      current_artifacts:
        type: array
        items:
          type: string
      target_artifacts:
        type: array
        items:
          type: string
      consumption_modes:
        type: array
        items:
          type: string
  relations:
    type: object
    additionalProperties: false
    properties:
      depends_on:
        $ref: '#/$defs/capabilityIdList'
      supports:
        $ref: '#/$defs/capabilityIdList'
      used_by:
        $ref: '#/$defs/capabilityIdList'
      related_to:
        $ref: '#/$defs/capabilityIdList'
      specializes:
        $ref: '#/$defs/capabilityIdList'
      generalizes:
        $ref: '#/$defs/capabilityIdList'
      replaces:
        $ref: '#/$defs/capabilityIdList'
      wraps:
        $ref: '#/$defs/capabilityIdList'
      reused_by:
        description: >
          Consumer repo slugs with observed reuse-event evidence
          (REUSE-WP-0019-T05), not capability ids. Evidence-gated: only
          `reuse-surface maintain` proposes/applies these, never silent.
        $ref: '#/$defs/repoSlugList'
  evidence:
    type: object
    additionalProperties: false
    properties:
      documentation:
        type: array
        items:
          type: string
      tests:
        type: array
        items:
          type: string
      consumer_feedback:
        type: array
        items:
          type: string
      bug_reports:
        type: array
        items:
          type: string
      incidents:
        type: array
        items:
          type: string
  consumer_guidance:
    type: object
    additionalProperties: false
    properties:
      recommended_for:
        type: array
        items:
          type: string
      not_recommended_for:
        type: array
        items:
          type: string
      known_limitations:
        type: array
        items:
          type: string
  promotion_history:
    type: array
    items:
      $ref: '#/$defs/promotionRecord'
$defs:
  confidence:
    type: string
    enum: [low, medium, high]
  discoveryLevel:
    type: string
    enum: [D0, D1, D2, D3, D4, D5, D6, D7]
  availabilityLevel:
    type: string
    enum: [A0, A1, A2, A3, A4, A5, A6, A7]
  completenessLevel:
    type: string
    enum: [C0, C1, C2, C3, C4, C5, C6]
  reliabilityLevel:
    type: string
    enum: [R0, R1, R2, R3, R4, R5, R6]
  capabilityIdList:
    type: array
    items:
      type: string
      pattern: '^capability(\.[a-z][a-z0-9-]*)+$'
  repoSlugList:
    type: array
    items:
      type: string
      minLength: 1
  internalMaturityDimension:
    type: object
    additionalProperties: false
    required: [current, target]
    properties:
      current:
        oneOf:
          - $ref: '#/$defs/discoveryLevel'
          - $ref: '#/$defs/availabilityLevel'
      target:
        oneOf:
          - $ref: '#/$defs/discoveryLevel'
          - $ref: '#/$defs/availabilityLevel'
      confidence:
        $ref: '#/$defs/confidence'
      rationale:
        type: string
  completenessEvidence:
    type: object
    additionalProperties: false
    required: [level]
    properties:
      level:
        $ref: '#/$defs/completenessLevel'
      name:
        type: string
      confidence:
        $ref: '#/$defs/confidence'
      basis:
        type: string
      satisfied_expectations:
        type: array
        items:
          type: string
      broken_expectations:
        type: array
        items:
          type: string
      out_of_scope_expectations:
        type: array
        items:
          type: string
  reliabilityEvidence:
    type: object
    additionalProperties: false
    required: [level]
    properties:
      level:
        $ref: '#/$defs/reliabilityLevel'
      name:
        type: string
      confidence:
        $ref: '#/$defs/confidence'
      basis:
        type: string
      evidence:
        type: object
        additionalProperties: true
      known_reliability_risks:
        type: array
        items:
          type: string
  promotionDimension:
    type: string
    enum: [discovery, availability, completeness, reliability]
  promotionRecord:
    type: object
    additionalProperties: false
    required: [date, dimension, from, to, rationale]
    properties:
      date:
        type: string
        pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}$'
      dimension:
        $ref: '#/$defs/promotionDimension'
      from:
        type: string
      to:
        type: string
      rationale:
        type: string
      author:
        type: string