{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.anguskit.com/schema/anguscopilot/1.0.0/common.json",
  "title": "AngusCopilot Common Types",
  "description": "AngusCopilot 1.0.0 规范族的公共类型定义。所有顶层 Schema 以及域片段通过 $ref 引用本文件复用类型。",

  "$defs": {

    "Identifier": {
      "title": "Identifier",
      "description": "符合 RFC1123 的小写标识符（与 K8s 资源名兼容）。",
      "type": "string",
      "minLength": 1,
      "maxLength": 253,
      "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$"
    },

    "SemVer": {
      "title": "Semantic Version",
      "description": "严格遵循 SemVer 2.0.0 的版本号。",
      "type": "string",
      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
    },

    "SemVerRange": {
      "title": "Semantic Version Range",
      "description": "SemVer 范围表达式（参考 npm semver 语法）。示例：'^1.0.0'、'>=1.0.0 <2.0.0'、'1.x'、'latest'。",
      "type": "string",
      "minLength": 1,
      "examples": [
        "^1.0.0",
        ">=1.0.0 <2.0.0",
        "1.x",
        "latest"
      ]
    },

    "SpecificationField": {
      "title": "Specification 根字段",
      "description": "格式：<规范族>/<语义化版本>。规范族区分资源种类，版本号遵循 SemVer。",
      "type": "string",
      "pattern": "^(anguscopilot|anguscopilot-procedure|anguscopilot-tool|anguscopilot-knowledge|anguscopilot-workflow)\\/(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-(?:alpha|beta|rc)(?:\\.(?:0|[1-9]\\d*))?)?$",
      "examples": [
        "anguscopilot/1.0.0",
        "anguscopilot-procedure/1.0.0",
        "anguscopilot-tool/1.0.0",
        "anguscopilot-knowledge/1.0.0-alpha"
      ]
    },

    "Duration": {
      "title": "ISO 8601 Duration 或快捷写法",
      "description": "支持 ISO 8601 持续时间（PT30S、PT5M、PT1H）或人类友好写法（30s、5m、1h、24h、7d）。",
      "type": "string",
      "pattern": "^(P(?:\\d+Y)?(?:\\d+M)?(?:\\d+D)?(?:T(?:\\d+H)?(?:\\d+M)?(?:\\d+(?:\\.\\d+)?S)?)?|\\d+(?:\\.\\d+)?(ms|s|m|h|d))$",
      "examples": [
        "PT30S",
        "30s",
        "5m",
        "1h",
        "24h",
        "7d"
      ]
    },

    "CapabilityRef": {
      "title": "Capability 引用",
      "description": "形如 'tool://<namespace>/<name>@<version-range>' 或 'procedure://<namespace>/<name>@<version-range>' 的统一资源标识符。",
      "type": "string",
      "pattern": "^(tool|procedure):\\/\\/[a-z0-9][-a-z0-9.]*\\/[a-z0-9][-a-z0-9_.]*@[^\\s]+$",
      "examples": [
        "tool://builtin/web-search@1.0.0",
        "tool://openapi/crm@^2.0.0",
        "tool://mcp/github@latest",
        "procedure://ticket/create@>=1.0.0 <2.0.0"
      ]
    },

    "SecretRef": {
      "title": "凭证引用",
      "description": "禁止 YAML 中明文密钥；必须以 'vault:'、'env:'、'session:'、'aws:'、'aliyun:' 等已知前缀的引用形式声明。",
      "type": "string",
      "pattern": "^(vault|env|session|aws|aliyun|gcp|azure|file):[A-Za-z0-9_./:-]+$",
      "examples": [
        "vault:credential/1001",
        "vault:credential/name/openai-api-key",
        "env:OPENAI_API_KEY",
        "session:authorization",
        "aws:secretsmanager:openai-api-key",
        "aliyun:kms:cs-openai-key"
      ]
    },

    "Labels": {
      "title": "Labels（用于分类筛选）",
      "description": "K-V 标签，键 / 值均为短字符串，参考 K8s Labels 约定。",
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "maxLength": 63,
        "pattern": "^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$"
      },
      "propertyNames": {
        "type": "string",
        "maxLength": 63,
        "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$"
      }
    },

    "Annotations": {
      "title": "Annotations（用于非结构化元信息）",
      "description": "K-V 注解，值可较长（如 changelog 文本）；不可用于框架内部行为决策。",
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "propertyNames": {
        "type": "string",
        "maxLength": 253
      }
    },

    "ExtensionMap": {
      "title": "Extension Map (x-*)",
      "description": "用户自定义扩展字段，必须以 'x-' 前缀开头。框架忽略未识别的 x-* 字段。",
      "type": "object",
      "additionalProperties": true,
      "propertyNames": {
        "pattern": "^x-[A-Za-z][A-Za-z0-9_-]*$"
      }
    },

    "JsonSchemaRef": {
      "title": "Embedded JSON Schema",
      "description": "嵌入式 JSON Schema 2020-12 子文档（用于 input/output 参数 Schema 定义）。",
      "type": "object",
      "$comment": "由代码层 SchemaValidator 进一步校验，YAML 阶段仅做结构性约束。",
      "additionalProperties": true
    }
  }
}