Json Schema簡介和Json Schema的.net實現庫 LateApexEarlySpeed.Json.Schema

dotnet程式故障診斷發表於2023-12-26
JSON

什麼是Json Schema ？

Json schema是一種宣告式語言，它可以用來標識Json的結構，資料型別和資料的具體限制，它提供了描述期望Json結構的標準化方法。
利用Json Schema, 你可以定義Json結構的各種規則，以便確定Json資料在各個子系統中互動傳輸時保持相容和一致的格式。

一般來說，系統可以自己實現邏輯來判斷當前json是否滿足介面要求，比如是否某個欄位存在，是否屬性值是有效的。但當驗證需求變得複雜後，比如有大量巢狀json結構，屬性之間的複雜關聯限制等等，則容易編寫出考慮不全的驗證程式碼。另外，當系統需要動態的json資料要求，比如先由使用者自己決定他需要的json結構，然後系統根據使用者表達的定製化json結構需求，幫助使用者驗證後續的json資料。這種系統程式碼編譯時無法確定的json結構，就需要另一種解決方案。

Json Schema就是針對這種問題的比較自然的解決方案。它可以讓你或你的使用者描述希望的json結構和值的內容限制，有效屬性，是否是required, 還有有效值的定義，等等。。利用Json Schema, 人們可以更好的理解Json結構，而且程式也可以根據你的Json Schema驗證Json資料。
Json Schema語法的學習見官方介紹。

比如下面的一個簡單例子，用.net下的Json Schema實現庫library LateApexEarlySpeed.Json.Schema進行Json資料的驗證：

Json Schema （檔案：schema.json）：

{
  "type": "object",
  "properties": {
    "propBoolean": {
      "type": "boolean"
    },
    "propArray": {
      "type": "array",
      "uniqueItems": true
    }
  }
}

Json 資料 （檔案：instance.json）：

{
  "propBoolean": true,
  "propArray": [ 1, 2, 3, 4, 4 ]
}

C# 程式碼：

            string jsonSchema = File.ReadAllText("schema.json");
            string instance = File.ReadAllText("instance.json");

            var jsonValidator = new JsonValidator(jsonSchema);
            ValidationResult validationResult = jsonValidator.Validate(instance);

            if (validationResult.IsValid)
            {
                Console.WriteLine("good");
            }
            else
            {
                Console.WriteLine($"Failed keyword: {validationResult.Keyword}");
                Console.WriteLine($"ResultCode: {validationResult.ResultCode}");
                Console.WriteLine($"Error message: {validationResult.ErrorMessage}");
                Console.WriteLine($"Failed instance location: {validationResult.InstanceLocation}");
                Console.WriteLine($"Failed relative keyword location: {validationResult.RelativeKeywordLocation}");
            }

輸出：

Failed keyword: uniqueItems
ResultCode: DuplicatedArrayItems
Error message: There are duplicated array items
Failed instance location: /propArray
Failed relative keyword location: /properties/propArray/uniqueItems

LateApexEarlySpeed.Json.Schema中文介紹

專案原始文件：https://github.com/lateapexearlyspeed/Lateapexearlyspeed.JsonSchema.Doc

中文文件：
LateApexEarlySpeed.Json.Schema是2023年12月釋出的一個新的.net下的Json Schema實現庫library，基於截止到2023年12月為止最新版的Json schema - draft 2020.12。
Json Schema驗證功能經過了official json schema test-suite for draft 2020.12的測試。（部分排除的用例見下面的已知限制章節）
LateApexEarlySpeed.Json.Schema的主要特點是：

  • 基於微軟.net下預設的System.Text.Json而非經典的Newtonsoft.Json
  • 使用簡單
  • 和已有的知名且傑出的.net下的一些JsonSchema library相比，具有很好的效能 (在common case下，利用BenchmarkDotnet進行的效能測試)。使用者請根據自己的使用場景進行效能驗證

該實現庫(implementation library)之後可能會transfer成開源專案。

基礎用法

安裝Nuget package

Install-Package LateApexEarlySpeed.Json.Schema

string jsonSchema = File.ReadAllText("schema.json");
string instance = File.ReadAllText("instance.json");

var jsonValidator = new JsonValidator(jsonSchema);
ValidationResult validationResult = jsonValidator.Validate(instance);

if (validationResult.IsValid)
{
    Console.WriteLine("good");
}
else
{
    Console.WriteLine($"Failed keyword: {validationResult.Keyword}");
    Console.WriteLine($"ResultCode: {validationResult.ResultCode}");
    Console.WriteLine($"Error message: {validationResult.ErrorMessage}");
    Console.WriteLine($"Failed instance location: {validationResult.InstanceLocation}");
    Console.WriteLine($"Failed relative keyword location: {validationResult.RelativeKeywordLocation}");
    Console.WriteLine($"Failed schema resource base uri: {validationResult.SchemaResourceBaseUri}");
}

輸出資訊

當json資料驗證失敗後，可以檢視錯誤資料的具體資訊:

  • IsValid: As summary indicator for passed validation or failed validation.

  • ResultCode: The specific error type when validation failed.

  • ErrorMessage: the specific wording for human readable message

  • Keyword: current keyword when validation failed

  • InstanceLocation: The location of the JSON value within the instance being validated. The value is a JSON Pointer.

  • RelativeKeywordLocation: The relative location of the validating keyword that follows the validation path. The value is a JSON Pointer, and it includes any by-reference applicators such as "$ref" or "$dynamicRef". Eg:

    /properties/width/$ref/minimum

  • SubSchemaRefFullUri: The absolute, dereferenced location of the validating keyword when validation failed. The value is a full URI using the canonical URI of the relevant schema resource with a JSON Pointer fragment, and it doesn't include by-reference applicators such as "$ref" or "$dynamicRef" as non-terminal path components. Eg:

    https://example.com/schemas/common#/$defs/count/minimum

  • SchemaResourceBaseUri: The absolute base URI of referenced json schema resource when validation failed. Eg:

    https://example.com/schemas/common

效能建議

儘可能的重用已例項化的JsonValidator例項（JsonValidator可以簡單理解為代表一個json schema驗證文件）來驗證json資料，以便獲得更高效能

外部json schema依賴的支援

除了自動支援當前schema文件內的引用關係，還支援外部json schema依賴：

  • 本地schema依賴文字
var jsonValidator = new JsonValidator(jsonSchema);
string externalJsonSchema = File.ReadAllText("schema2.json");
jsonValidator.AddExternalDocument(externalJsonSchema);
ValidationResult validationResult = jsonValidator.Validate(instance);
  • 遠端schema url (實現庫將訪問網路來獲得遠端的schema)
var jsonValidator = new JsonValidator(jsonSchema);
await jsonValidator.AddHttpDocumentAsync(new Uri("http://this-is-json-schema-document"));
ValidationResult validationResult = jsonValidator.Validate(instance);

自定義keyword的支援

除了json schema specification中的標準keywords之外，還支援使用者建立自定義keyword來實現額外的驗證需求：

{
  "type": "object",
  "properties": {
    "prop1": {
      "customKeyword": "Expected value"
    }
  }
}

ValidationKeywordRegistry.AddKeyword<CustomKeyword>();

[Keyword("customKeyword")] // It is your custom keyword name
[JsonConverter(typeof(CustomKeywordJsonConverter))] // Use 'CustomKeywordJsonConverter' to deserialize to 'CustomKeyword' instance out from json schema text
internal class CustomKeyword : KeywordBase
{
    private readonly string _customValue; // Simple example value

    public CustomKeyword(string customValue)
    {
        _customValue = customValue;
    }

    // Do your custom validation work here
    protected override ValidationResult ValidateCore(JsonInstanceElement instance, JsonSchemaOptions options)
    {
        if (instance.ValueKind != JsonValueKind.String)
        {
            return ValidationResult.ValidResult;
        }

        return instance.GetString() == _customValue
            ? ValidationResult.ValidResult
            : ValidationResult.CreateFailedResult(ResultCode.UnexpectedValue, "It is not my expected value.", options.ValidationPathStack, Name, instance.Location);
    }
}

internal class CustomKeywordJsonConverter : JsonConverter<CustomKeyword>
{
    // Library will input json value of your custom keyword: "customKeyword" to this method.
    public override CustomKeyword? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        // Briefly: 
        return new CustomKeyword(reader.GetString()!);
    }

    public override void Write(Utf8JsonWriter writer, CustomKeyword value, JsonSerializerOptions options)
    {
        throw new NotImplementedException();
    }
}

Format支援

目前library支援如下format:

  • uri
  • uri-reference
  • date
  • time
  • date-time
  • email
  • uuid
  • hostname
  • ipv4
  • ipv6
  • json-pointer
  • regex

Format 驗證需要顯式enable, 當驗證資料時，請傳入配置好的 JsonSchemaOptions:

jsonValidator.Validate(instance, new JsonSchemaOptions{ValidateFormat = true});

如果需要自定義format驗證，可以實現一個FormatValidator子類並註冊：

[Format("custom_format")] // this is your custom format name in json schema
public class TestCustomFormatValidator : FormatValidator
{
    public override bool Validate(string content)
    {
        // custom format validation logic here...
    }
}

// register it globally
FormatRegistry.AddFormatType<TestCustomFormatValidator>();

Other extension usage doc is to be continued .

限制

  • 目前library關注於驗證，暫不支援annotation
  • 因為暫不支援annotation, 所以不支援如下keywords: unevaluatedProperties, unevaluatedItems
  • 目前不支援 content-encoded string

問題報告

歡迎把使用過程中遇到的問題和希望增加的功能發到github repo issue中

More doc is to be written

相關文章