# JSON Schema (draft 2020-12, written in YAML) for a single workspace convention.
# Every file at @conventions/programming_<scope>/<name>.yaml validates against this.
# Agents reference a convention as  convention:<name>  or  convention:<name>(<args>).
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "conventions/convention.yaml.schema"
title: Convention
description: One workspace convention — metadata + rules, optionally defining a project manifest file and/or accepting parameters.
type: object
additionalProperties: false
required: [apiVersion, name, title, scope, status, summary]
properties:
  apiVersion:
    type: string
    const: "conventions/v1"
    description: Schema-contract version for the convention DOCUMENT itself. Bumped only on breaking schema changes; consumers branch on it. (The JSON Schema draft is separate — see $schema.)
  version:
    type: string
    pattern: "^\\d+\\.\\d+\\.\\d+$"
    description: SemVer of THIS convention's CONTENT (its rules/manifest). Bump on changes so projects can pin/migrate, e.g. "requires convention:infra_manifest >= 1.2.0".
  updated:
    type: string
    format: date
    description: ISO date (YYYY-MM-DD) this convention was last changed.
  name:
    type: string
    pattern: "^[a-z0-9][a-z0-9_]*$"
    description: snake_case id; MUST match the filename (without .yaml).
  title:
    type: string
  scope:
    type: string
    enum: [general, ts, swift, py, rust, gd]
    description: Matches the programming_<scope>/ directory the file lives in.
  status:
    type: string
    enum: [draft, active, deprecated]
  summary:
    type: string
    description: One line; shown when an agent lists available conventions.
  params:
    type: array
    description: Named arguments the convention accepts, e.g. recursive_code_workspace(root).
    items:
      type: object
      additionalProperties: false
      required: [name]
      properties:
        name: { type: string }
        description: { type: string }
        default: {}
  appliesTo:
    type: array
    description: Globs or project kinds this convention governs.
    items: { type: string }
  supersedes:
    type: array
    items: { type: string }
  rules:
    type: array
    items:
      type: object
      additionalProperties: false
      required: [id, level, text]
      properties:
        id: { type: string }
        level: { type: string, enum: [must, should, may] }
        text: { type: string }
        rationale: { type: string }
  # When set, the convention defines a manifest file every conforming project must
  # provide (e.g. .infra.yaml), with a nested JSON Schema for that file's contents.
  providesFile:
    type: object
    additionalProperties: false
    required: [path, schema]
    properties:
      path:
        type: string
        description: Repo-relative path each conforming project must contain (e.g. ".infra.yaml").
      schema:
        type: object
        description: JSON Schema (draft 2020-12) the manifest file validates against.