1  # Component Schema Definition v1.0.0
  2  # Defines the structure for all .component.cspec files
  3  # AI workers MUST validate components against this schema
  4  
  5  schema_version: 1.0.0
  6  created: 2026-01-07
  7  
  8  # === REQUIRED SECTIONS ===
  9  required:
 10    - metadata
 11    - dependencies
 12    - interface
 13    - spec
 14  
 15  # === METADATA SECTION ===
 16  metadata:
 17    id:
 18      type: string
 19      pattern: "^[A-Z]{1,2}[0-9]{2,3}$"  # T001, A001, AC01, etc.
 20      required: true
 21    name:
 22      type: string
 23      pattern: "^[a-z_]+$"
 24      required: true
 25    version:
 26      type: semver
 27      pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
 28      required: true
 29    domain:
 30      type: enum
 31      values: [tokens, alpha, delta, runtime, nodes, network, infra, acdc, security, future, frontend]
 32      required: true
 33    stability:
 34      type: enum
 35      values: [high_change, stable, future]
 36      required: true
 37    updated:
 38      type: date
 39      format: "YYYY-MM-DD"
 40      required: true
 41    cascade_priority:
 42      type: integer
 43      min: 0
 44      max: 100
 45      default: 50
 46      required: false
 47  
 48    # Role Expertise (for AI worker routing)
 49    roles:
 50      type: object
 51      required: false
 52      properties:
 53        primary:
 54          type: array
 55          items:
 56            type: enum
 57            values: [Dev, Ops, Arch, Security]
 58          description: "Roles that typically work on this component"
 59        review:
 60          type: array
 61          items:
 62            type: enum
 63            values: [Dev, Ops, Arch, Security]
 64          description: "Roles that must review changes to this component"
 65  
 66    expertise:
 67      type: object
 68      required: false
 69      properties:
 70        required:
 71          type: array
 72          items: string
 73          description: "Skills required to work on this component"
 74        helpful:
 75          type: array
 76          items: string
 77          description: "Skills that help but aren't required"
 78  
 79    context_tags:
 80      type: array
 81      items: string
 82      description: "Semantic tags for search and filtering"
 83      required: false
 84  
 85  # === DEPENDENCIES SECTION ===
 86  dependencies:
 87    upstream:
 88      type: array
 89      items:
 90        id:
 91          type: string
 92          required: true
 93        version:
 94          type: semver_constraint
 95          patterns:
 96            - "^>=?[0-9]+\\.[0-9]+\\.[0-9]+$"      # >=1.0.0, >1.0.0
 97            - "^\\^[0-9]+\\.[0-9]+\\.[0-9]+$"      # ^1.0.0 (compatible)
 98            - "^~[0-9]+\\.[0-9]+\\.[0-9]+$"        # ~1.0.0 (patch only)
 99            - "^[0-9]+\\.[0-9]+\\.[0-9]+$"         # 1.0.0 (exact)
100          required: true
101        interface:
102          type: array
103          items: string
104          required: true
105        relationship:
106          type: enum
107          values: [requires, uses, extends]
108          default: requires
109    downstream:
110      type: array
111      items:
112        id:
113          type: string
114          required: true
115        exposed_interface:
116          type: array
117          items: string
118          required: true
119  
120  # === INTERFACE SECTION ===
121  interface:
122    types_ref:
123      type: string
124      description: "Reference to shared types file"
125      default: "_registry/types.cspec"
126    types:
127      type: object
128      description: "Embedded type definitions (subset of types.cspec)"
129    functions:
130      type: object
131      items:
132        inputs:
133          type: array
134          description: "Function input parameters"
135        outputs:
136          type: array
137          description: "Function output values"
138        requires:
139          type: array
140          description: "Preconditions"
141        emits:
142          type: array
143          description: "Events emitted"
144    events:
145      type: array
146      items:
147        type: object
148        description: "Event name and payload fields"
149    constants:
150      type: object
151      description: "Named constant values"
152  
153  # === SPEC SECTION ===
154  spec:
155    type: object
156    description: "Specification content - structure varies by component"
157    required: true
158  
159  # === CHANGELOG SECTION ===
160  changelog:
161    type: array
162    required: true
163    items:
164      version:
165        type: semver
166        required: true
167      date:
168        type: date
169        required: true
170      type:
171        type: enum
172        values: [initial, major, minor, patch, cascade]
173        required: true
174      description:
175        type: string
176        required: true
177      breaking:
178        type: boolean
179        default: false
180      cascade_from:
181        type: string
182        description: "Source component ID if this was a cascade update"