.NET 9 中的 JsonSchemaExporter

.NET 9 中的 JsonSchemaExporter

Intro

.NET 9 Preview 6 中引入了一个 JsonSchemaExporter，我们可以借助它根据类型来生成 json schema，之前我们有写过一篇文章使用 JsonSchema 来验证 API 的 response 使用 JsonSchema 验证 API 的返回格式，有了这个 API 之后就可以更方便地生成 JsonSchema 了

Samples

首先我们准备一下类型用以测试：

public class Job
{
    public int Id { get; set; }
    public string Title { get; set; } = string.Empty;
    public string? Description { get; set; }
}

从 JsonSerializeOptions 获取类型的 json schema 结构

var type = typeof(Job);
var defaultSchemaNode = JsonSchemaExporter.GetJsonSchemaAsNode(
    JsonSerializerOptions.Default, type
    );
Console.WriteLine(JsonSerializer.Serialize(defaultSchemaNode, JsonSerializerOptions.Web));

我们可以使用 JsonSchemaExporter.GetJsonSchemaAsNode 来获取 jsonSchema，输出结果如下：

{"type":["object","null"],"properties":{"Id":{"type":"integer"},"Title":{"type":"string"},"Description":{"type":["string","null"]}}}

这个方法定义为扩展方法，我们也可以通过扩展方法的方式来使用，JsonSchema 导出之后是一个 JsonNode 对象，大小写命名规则等由 JsonSerializerOptions 来决定，所以需要一个 JsonSerializerOptions 参数，我们再来看下使用不同的 JsonSerializerOptions 的结果有何不同

var schemaNode = JsonSerializerOptions.Web.GetJsonSchemaAsNode(typeof(Job));
Console.WriteLine(JsonSerializer.Serialize(schemaNode, JsonSerializerOptions.Web));

和前面相比，这次我们使用了 JsonSerializerOptions.Web, 会使用 CamelCase 的命名规则， 输出结果如下：

{"type":["object","null"],"properties":{"id":{"type":["string","integer"],"pattern":"^-?(?:0|[1-9]\\d*)$"},"title":{"type":"string"},"description":{"type":["string","null"]}}}

可以看到此时，我们的属性名成变成了小写，另外由于 Web option 默认允许字符串转成数值，所以能看到我们的 id，允许的 type 除了 integer 之外还有 string，不过 string 也多了一个数字的正则表达式规则校验，这也说明了 JsonSerializerOptions 对 jsonSchema 的影响是比较大的。

如果我想要 title 必填的话要怎么做呢，可以把 Title 设置为 required, 添加一个 required 修饰符即可

public class Job
{
    public int Id { get; set; }
    public required string Title { get; set; }
    public string? Description { get; set; }
}

此时输出结果就变成了下面这样：

{"type":["object","null"],"properties":{"id":{"type":["string","integer"],"pattern":"^-?(?:0|[1-9]\\d*)$"},"title":{"type":"string"},"description":{"type":["string","null"]}},"required":["title"]}

可以看到在最后增加了一个 required 属性，里面有一个 title 表示 title 属性必填，没有的话 json schema 验证应该失败

除此之外，我们还可以在导出的时候做一些自定义的操作，示例如下：

var exporterOptions = new JsonSchemaExporterOptions
{
    TransformSchemaNode = (context, jsonNode) =>
    {
        var node = jsonNode.DeepClone();
        var idNames = new[] { "id", "Id" };

        if (node["properties"] is not JsonObject propertiesNode)
            return node;

        foreach (var idName in idNames)
        {
            if (propertiesNode[idName] is JsonObject)
            {
                var requiredNode = node["required"];
                if (requiredNode is JsonArray jsonArrayNode)
                {
                    var requiredProperties = JsonSerializer.Serialize(jsonArrayNode.Select(x => x.GetValue<string>()).Append(idName));
                    jsonArrayNode.ReplaceWith(JsonSerializer.Deserialize<JsonArray>(requiredProperties));
                }
                else
                {
                    node["required"] = JsonSerializer.Deserialize<JsonArray>($"""["{idName}"]""");
                }
            }

        }
        return node;
    }
};
var schemaNode3 = JsonSerializerOptions.Web.GetJsonSchemaAsNode(typeof(Job), exporterOptions);
Console.WriteLine(JsonSerializer.Serialize(schemaNode3, JsonSerializerOptions.Web));

这里我们在生成的 jsonSchema node 的基础之上，如果属性名称是 id 或者 Id 的话就将它添加到 required 中或者创建一个 required 并将 id 属性名添加进去，输出结果如下：

{"type":["object","null"],"properties":{"id":{"type":["string","integer"],"pattern":"^-?(?:0|[1-9]\\d*)$"},"title":{"type":"string"},"description":{"type":["string","null"]}},"required":["title","id"]}

这里可以看到针对前面的输出，required 里多个 id 属性

我们再来测试一下 Id 以及没有 required 属性的情况，我们将 required 修饰符给去掉，再加入 exporterOptions 和第一次的输出结果做个对比

var schemaNode4 = JsonSerializerOptions.Default.GetJsonSchemaAsNode(typeof(Job), exporterOptions);
Console.WriteLine(JsonSerializer.Serialize(schemaNode4, JsonSerializerOptions.Web));

此时输出结果如下：

{"type":["object","null"],"properties":{"Id":{"type":"integer"},"Title":{"type":"string"},"Description":{"type":["string","null"]}},"required":["Id"]}

可以看到输出结果里有了 required, 再来用 json schema 验证下看看

这个示例只是为了说明可以自定义，实际使用可以直接添加一个 required 修饰符即可

More

目前的 JsonSchema 支持还比较早期，对于复杂的需求可能还需要自己扩展，比如说设置 schema 需要类似前面示例一样自己扩展下，在 .NET 10 里应该还会继续优化和增强

References

• https://github.com/WeihanLi/SamplesInPractice/blob/main/net9sample/Net9Samples/JsonSample.cs

• https://github.com/dotnet/runtime/issues/102788

• https://github.com/dotnet/runtime/pull/103322

• https://github.com/dotnet/runtime/issues/105769

• https://www.jsonschemavalidator.net/