在dotnet/extensions项目中为JSON Schema生成添加DataAnnotations支持

在当今的微服务架构和API开发中，JSON Schema作为数据验证和文档化的标准工具变得越来越重要。特别是在AI和机器学习领域，JSON Schema能够帮助语言模型更好地理解数据结构约束，从而生成更准确的请求参数。本文将深入探讨如何在dotnet/extensions项目中为JSON Schema生成添加对System.ComponentModel.DataAnnotations的支持。

背景与现状

目前，dotnet/extensions项目中的AIFunction基础设施在生成JSON Schema时，无法识别.NET中常用的验证特性（如Range、Required、StringLength等）。这意味着开发者无法直接在工具参数上使用这些标准验证特性来表达约束条件，而必须手动实现运行时验证。

举例来说，当开发者定义如下记录类型时：

public record SimulationSettings(
    [Range(-1, 10, ErrorMessage = "必须在-1到10之间")]
    decimal MarketROR
);

当前系统生成的JSON Schema仅包含基本类型信息：

{
  "marketROR": {
    "type": "number"
  }
}

技术实现方案

为了实现更完善的Schema生成，我们需要扩展AIJsonUtilities的功能，使其能够识别并转换常见的DataAnnotations特性为对应的JSON Schema验证约束。

需要支持的验证特性

1. RangeAttribute：转换为"minimum"和"maximum"属性
2. RequiredAttribute：确保参数出现在"required"数组中
3. StringLengthAttribute：转换为"maxLength"属性
4. RegularExpressionAttribute：转换为"pattern"属性
5. EmailAddressAttribute：转换为"format": "email"

预期输出示例

改进后，上述示例应该生成包含验证约束的完整Schema：

{
  "marketROR": {
    "type": "number",
    "minimum": -1,
    "maximum": 10
  }
}

技术优势与价值

1. 标准化支持：与.NET生态系统的验证模式保持一致
2. 开发体验提升：开发者可以使用熟悉的验证特性
3. 客户端验证：MCP客户端可以在调用工具前验证输入
4. 自文档化：Schema本身可以作为API契约的一部分
5. 一致性：与ASP.NET Core、Minimal APIs等框架保持相同的行为

实现建议

在技术实现上，建议在AIJsonUtilities层添加对DataAnnotations的支持。这种设计有以下优势：

1. 模块化：保持功能的独立性和可维护性
2. 可扩展性：未来如果STJ（System.Text.Json）底层支持这些特性，可以轻松迁移
3. 灵活性：可以根据项目需求定制特定的转换规则

总结

为JSON Schema生成添加DataAnnotations支持是一个能够显著提升开发体验和系统健壮性的改进。它不仅使验证逻辑更加声明式和集中化，还能帮助AI系统更好地理解数据约束，减少无效请求和错误处理的开销。对于使用dotnet/extensions项目的开发者来说，这将是一个值得期待的功能增强。

在未来的发展中，这种验证特性的支持还可以进一步扩展到更多场景，如OpenAPI规范生成、客户端代码生成等，为.NET生态系统的开发者提供更完整的开发体验。