如何拆分大型JSON Schema文件并在Newtonsoft JSON.Net本地复用

文件结构说明 #

先明确你的项目Schema文件结构：

主文件夹/
├── CustomerListResponse.json  # 响应结构Schema
├── Schema-Request1.json
├── Schema-Response1.json
└── def/
    ├── Customer.json          # 公共客户对象Schema
    └── Object2.json

1. 公共Schema的$id配置 #

在def/Customer.json中，将$id设置为相对于主文件夹的路径，既不需要依赖外部域名，也能保证引用的唯一性：

{
  "$id": "def/Customer.json",
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["id", "name"]
}

2. 主Schema的$ref引用 #

在主文件夹的CustomerListResponse.json中，直接通过相对路径引用公共Schema：

{
  "$id": "CustomerListResponse.json",
  "type": "object",
  "properties": {
    "totalCount": { "type": "integer" },
    "customers": {
      "type": "array",
      "items": { "$ref": "def/Customer.json" }
    }
  },
  "required": ["totalCount", "customers"]
}

3. C#验证代码的本地加载配置 #

在你的C#验证逻辑中，必须设置JsonSchemaLoader的BaseUri为主文件夹的绝对路径，这样Loader才能正确解析相对路径的Schema引用，避免尝试下载外部资源：

using Newtonsoft.Json.Schema;
using Newtonsoft.Json.Linq;
using System.IO;
using System.Linq;

public bool ValidateCustomerListResponse(string jsonContent)
{
    // 替换为你的主文件夹绝对路径
    string schemaRootPath = @"C:\YourProject\APISchemas\";
    var baseUri = new Uri(Path.GetFullPath(schemaRootPath) + Path.DirectorySeparatorChar);

    var loader = new JsonSchemaLoader();
    loader.BaseUri = baseUri;

    // 加载主响应Schema
    using var schemaStream = new StreamReader(Path.Combine(schemaRootPath, "CustomerListResponse.json"));
    var responseSchema = loader.Load(schemaStream);

    // 解析待验证的JSON
    var jsonObject = JObject.Parse(jsonContent);

    // 执行验证并返回结果
    var validationErrors = responseSchema.Validate(jsonObject);
    return !validationErrors.Any();
}

关键注意事项 #

• 避免使用域名格式的$id（如https://yourdomain.com/def/Customer.json），这会触发Json.NET Schema的远程下载逻辑
• 相对路径的$id和$ref必须基于BaseUri设置的根路径，否则Loader无法定位文件
• 如果需要跨项目复用，也可以使用file://协议的绝对URI作为$id（如"$id": "file:///C:/YourProject/APISchemas/def/Customer.json"），但相对路径的移植性更好

内容的提问来源于stack exchange，提问作者Michael Hartmann