{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Schema Definition File",
  "description": "通用 schema 定义文件（.jsonc）的结构校验规则，适用于文档型/关系型数据库；配合任意支持 JSON Schema 的编辑器/工具使用（如 IntelliJ JSON Schema Mappings、VS Code 等）；语义规范见同 skill 的 references/CONSTRAINTS.md",
  "type": "object",
  "required": ["table_name", "description", "fields"],
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string",
      "description": "JSON Schema 引用，指向本目录的 schema.json（相对路径），供编辑器进行结构校验与补全"
    },
    "table_name": {
      "type": "string",
      "pattern": "^[a-zA-Z_][a-zA-Z0-9_.]*$",
      "description": "表/集合的完整名称（表名全称本身即为完整标识，不含 db/schema/命名空间语义）。名称可包含 `.`，但 `.` 是名称的一部分而非层级分隔符。生成原生或偏原生 SQL 时，必须用反引号包裹整个表名（如 `orders`、`my.orders`），避免 `.` 被解析为库/schema 限定符"
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "description": "表的中文用途描述"
    },
    "import": {
      "type": "array",
      "description": "从外部 yaml/jsonc 文件导入共享定义（enums、types、fields、indexes 等任意顶层节均可导入）",
      "items": { "$ref": "#/definitions/ImportDef" }
    },
    "fields": {
      "type": "array",
      "minItems": 1,
      "description": "字段定义列表",
      "items": { "$ref": "#/definitions/FieldDef" }
    },
    "enums": {
      "type": "array",
      "description": "本文件私有枚举定义",
      "items": { "$ref": "#/definitions/EnumDef" }
    },
    "types": {
      "description": "本文件私有结构体/嵌套类型定义（文档型DB映射为子文档，关系型DB映射为子表或JSON列）",
      "oneOf": [
        {
          "type": "array",
          "items": { "$ref": "#/definitions/TypeDef" }
        },
        {
          "type": "object",
          "additionalProperties": { "$ref": "#/definitions/TypeDefObject" }
        }
      ]
    },
    "indexes": { "$ref": "#/definitions/IndexConfig" }
  },
  "definitions": {
    "ImportDef": {
      "type": "object",
      "required": ["as", "path"],
      "additionalProperties": false,
      "description": "外部 yaml/jsonc 导入定义。被导入文件可含任意顶层节，通过 <alias>.<section>.<name> 引用",
      "properties": {
        "as": {
          "type": "string",
          "description": "命名空间别名，如 common、shared_types"
        },
        "path": {
          "type": "string",
          "pattern": "^\\.{1,2}/.*\\.(yaml|jsonc)$",
          "description": "相对路径，以 ./ 或 ../ 开头，以 .yaml 或 .jsonc 结尾"
        }
      }
    },
    "FieldDef": {
      "type": "object",
      "required": ["name", "type", "description", "required"],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
          "description": "字段名，数据库合法标识符"
        },
        "type": {
          "description": "数据类型。可为「标准类型字符串」或「按语言/数据库指定的类型映射对象」二选一",
          "oneOf": [
            {
              "type": "string",
              "description": "标准类型字符串。标量关键字可自动补全；参数化/复合/引用形式见各子模式",
              "anyOf": [
                {
                  "enum": ["int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64", "float32", "float64", "boolean", "datetime", "date", "time", "uuid", "json", "string", "char", "decimal", "decimal128"],
                  "description": "标量类型（裸形式，无参数）"
                },
                {
                  "pattern": "^(?:string|char)\\(\\d+\\)$",
                  "description": "带长度的字符串：string(n) / char(n)",
                  "examples": ["string(255)", "char(2)"]
                },
                {
                  "pattern": "^decimal(?:128)?\\(\\d+(?:,\\d+)?\\)$",
                  "description": "带精度的定点数：decimal(p,s) / decimal128(p,s)",
                  "examples": ["decimal(10,2)", "decimal128(34,4)"]
                },
                {
                  "pattern": "^array<[^<>]+>$",
                  "description": "数组：array<T>",
                  "examples": ["array<string>", "array<types.item>"]
                },
                {
                  "pattern": "^map<[^<>]+>$",
                  "description": "键值映射：map<K,V>",
                  "examples": ["map<string,json>"]
                },
                {
                  "pattern": "^(?:enums|types)\\.[a-zA-Z_]\\w*$",
                  "description": "引用本文件 enums/types",
                  "examples": ["enums.status", "types.item"]
                },
                {
                  "pattern": "^[a-zA-Z_]\\w*\\.(?:enums|types)\\.[a-zA-Z_]\\w*$",
                  "description": "引用导入文件：<alias>.enums|types.<name>",
                  "examples": ["common.enums.owner_type"]
                }
              ]
            },
            { "$ref": "#/definitions/TypeMapping" }
          ]
        },
        "description": {
          "type": "string",
          "minLength": 1,
          "description": "字段语义描述"
        },
        "required": {
          "type": "boolean",
          "description": "字段是否必填（本键必填）。true=必填且不允许 null；false=允许 null（可空）。强类型语言从本文档生成代码时，required=false 的字段必须选用支持 null/undefined 的类型（详见 references/CONSTRAINTS.md）"
        },
        "default": {
          "description": "创建时的默认值，支持特殊函数 now() 和 uuidV4()"
        },
        "readonly": {
          "type": "boolean",
          "description": "true 表示由服务端维护，客户端不可写入"
        }
      }
    },
    "TypeMapping": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": {
        "type": "string",
        "minLength": 1,
        "description": "该语言/数据库/驱动的具体类型名，如 Decimal128、primitive.Decimal128、numeric、org.bson.types.Decimal128"
      },
      "propertyNames": {
        "pattern": "^[a-zA-Z][a-zA-Z0-9_.+-]*$",
        "description": "编程语言或数据库标识，如 node/golang/python/java/rust/postgres/mysql/mongodb，支持自定义"
      },
      "description": "按语言/数据库分别指定的类型映射（非空对象）。key 为编程语言或数据库标识，value 为该语言原生类型或驱动类型（如 node 通过 mongoose 的 Decimal128、golang 通过 bson 的 primitive.Decimal128 支持 decimal128）。key 与 value 均支持自定义；建议 value 与 key 所属语言/数据库实际支持的基本类型或驱动类型相对应"
    },
    "EnumDef": {
      "type": "object",
      "required": ["enum_name", "type", "values"],
      "additionalProperties": false,
      "properties": {
        "enum_name": {
          "type": "string",
          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
          "description": "枚举标识名，数据库合法标识符"
        },
        "type": {
          "description": "枚举值的数据类型，用于类型推导与校验。可为「标准类型字符串」（int*/uint*/string）或「按语言/数据库指定的类型映射对象」二选一",
          "oneOf": [
            {
              "type": "string",
              "enum": ["int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64", "string"],
              "description": "int* 表示各枚举值为对应位宽整数，string 表示各枚举值为字符串"
            },
            { "$ref": "#/definitions/TypeMapping" }
          ]
        },
        "values": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/definitions/EnumValue" }
        }
      }
    },
    "EnumValue": {
      "type": "object",
      "required": ["value", "label"],
      "additionalProperties": false,
      "properties": {
        "value": {
          "oneOf": [
            { "type": "number" },
            { "type": "string" }
          ],
          "description": "存储值，由所属枚举的 type 字段决定：int*/uint*→整数，string→字符串"
        },
        "label": {
          "type": "string",
          "description": "英文短标签"
        },
        "description": {
          "type": "string",
          "description": "中文详细说明"
        }
      }
    },
    "TypeDef": {
      "type": "object",
      "required": ["type_name", "fields"],
      "additionalProperties": false,
      "properties": {
        "type_name": {
          "type": "string",
          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
          "description": "类型标识名，数据库合法标识符"
        },
        "description": {
          "type": "string",
          "description": "类型的中文描述"
        },
        "fields": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/definitions/FieldDef" }
        }
      }
    },
    "TypeDefObject": {
      "type": "object",
      "description": "对象格式类型定义（兼容旧格式）",
      "properties": {
        "description": { "type": "string" },
        "fields": {
          "type": "array",
          "items": { "$ref": "#/definitions/FieldDef" }
        }
      }
    },
    "IndexConfig": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "config": {
          "type": "array",
          "description": "显式声明的索引列表",
          "items": { "$ref": "#/definitions/IndexEntry" }
        }
      }
    },
    "IndexEntry": {
      "type": "object",
      "required": ["unique", "indexes"],
      "description": "单条索引定义。unique/indexes/partial 为通用字段；数据库专属选项（background/sparse/type/include 等）可自由附加",
      "additionalProperties": true,
      "properties": {
        "unique": {
          "type": "boolean",
          "description": "是否唯一索引"
        },
        "indexes": {
          "type": "array",
          "minItems": 1,
          "description": "索引字段列表，复合索引按优先级排列",
          "items": { "$ref": "#/definitions/IndexField" }
        },
        "partial": {
          "$ref": "#/definitions/PartialIndex"
        },
        "background": {
          "type": "boolean",
          "description": "（MongoDB 专属）后台构建索引，避免阻塞读写"
        },
        "sparse": {
          "type": "boolean",
          "description": "（MongoDB 专属简写）等价于 partial.condition: 'field IS NOT NULL'"
        }
      }
    },
    "PartialIndex": {
      "type": "object",
      "required": ["condition"],
      "additionalProperties": false,
      "description": "部分索引配置（跨数据库通用写法）。condition 使用 SQL 风格表达式，由实现层翻译为目标数据库语法",
      "properties": {
        "condition": {
          "type": "string",
          "minLength": 1,
          "description": "过滤条件表达式（SQL 风格）。示例：'deletedAt IS NULL'、'status = 1 AND deletedAt IS NULL'、'score > 0'。MongoDB→partialFilterExpression，PostgreSQL→WHERE 子句"
        }
      }
    },
    "IndexField": {
      "type": "object",
      "required": ["field", "direction"],
      "additionalProperties": false,
      "properties": {
        "field": {
          "type": "string",
          "description": "字段名或点分路径"
        },
        "direction": {
          "type": "integer",
          "enum": [1, -1],
          "description": "1=升序（ASC），-1=降序（DESC）"
        }
      }
    }
  }
}