Merge pull request #7 from NickSale/BooleanSchemaCombinations

Added support for boolean combination keywords

Author: matthijscox

Project.toml

@@ -1,7 +1,7 @@
 name = "JSONSchemaGenerator"
 uuid = "b10a6b5e-eaef-4b72-b159-8e5005e98e8e"
 authors = ["matthijscox <matthijs.cox@gmail.com> and contributors"]
-version = "0.2.0"
+version = "0.3.0"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
@@ -22,4 +22,4 @@ JSONSchema = "7d188eb4-7ad8-530c-ae41-71a32a6d4692"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test", "JSON", "JSON3", "JSONSchema"]
+test = ["Test", "JSON", "JSON3", "JSONSchema"]

README.md

@@ -150,4 +150,111 @@ obj = NestedFieldSchema(
 json_dict = JSON3.write(obj) |> JSON.parse
 
 JSONSchema.validate(JSONSchema.Schema(schema_dict), json_dict) === nothing
-```
+```
+
+## Boolean Combination Keywords
+
+JSONSchemaGenerator.jl provides a function `combinationkeywords(::Type)` which can be used to associate a struct with an array of special types `AllOf{T,S}`, `AnyOf{T,S}`, `OneOf{T,S}` and `Not{T}` that allow the corresponding JSON keyword to be generated in a schema (see [Boolean JSON Schema combination](https://json-schema.org/understanding-json-schema/reference/combining)). Note that more than two schemas can be combined by chaining: e.g. `AllOf{A, AllOf{B, C}}`.
+
+In the following example we combine some schemas that check if fields are equal to specific values (using `Val` and `Tuple` types, noting that these do not serialize well and should only be used for validation purposes like this):
+```julia
+import JSONSchemaGenerator as JSG
+using JSONSchema, JSON3
+
+struct ConstantInt1Schema
+    int::Val{1}
+end
+
+struct EnumInt2Or3Schema
+    int::Tuple{2,3}
+end
+
+struct ConstantBoolTrueSchema
+    bool::Val{true}
+end
+
+struct BooleanCombinationSchema
+    int::Int
+    bool::Bool
+end
+StructTypes.StructType(::Type{BooleanCombinationSchema}) = StructTypes.Struct()
+JSG.combinationkeywords(::Type{BooleanCombinationSchema}) = [
+    JSG.AllOf{
+        JSG.AnyOf{ConstantInt1Schema, EnumInt2Or3Schema},
+        JSG.Not{ConstantBoolTrueSchema}
+    }
+]
+
+schema_dict = JSG.schema(BooleanCombinationSchema)
+
+good_json = JSON3.write(BooleanCombinationSchema(2, false))
+bad_json = JSON3.write(BooleanCombinationSchema(5, true))
+
+JSONSchema.validate(JSONSchema.Schema(schema_dict), good_json) === nothing
+JSONSchema.validate(JSONSchema.Schema(schema_dict), bad_json) !== nothing
+```
+
+The printed schema looks as follows:
+```julia
+julia> JSON.print(schema_dict, 2)
+JSON.print(schema_dict, 2)
+{
+  "type": "object",
+  "properties": {
+    "int": {
+      "type": "integer"
+    },
+    "bool": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "int",
+    "bool"
+  ],
+  "allOf": [
+    {
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "int": {
+              "const": 1
+            }
+          },
+          "required": [
+            "int"
+          ]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "int": {
+              "enum": [
+                2,
+                3
+              ]
+            }
+          },
+          "required": [
+            "int"
+          ]
+        }
+      ]
+    },
+    {
+      "not": {
+        "type": "object",
+        "properties": {
+          "bool": {
+            "const": true
+          }
+        },
+        "required": [
+          "bool"
+        ]
+      }
+    }
+  ]
+}
+```

src/CombinationKeywordTypes.jl

@@ -0,0 +1,75 @@
+"""
+    AllOf{T}
+
+Type introduced for generating the JSON schema `allOf` keyword.
+
+Can be added to `combinationkeywords` for some Struct to add the keyword to the generated schema of that struct,
+    or chained with other keywords.
+
+# Example
+```julia
+combinationkeywords(MyStructType) = (AllOf{StructTypeA, StructTypeB}, Not{AllOf{StructTypeC, StructTypeD}})
+```
+"""
+struct AllOf{T,S} end
+
+"""
+    AnyOf{T}
+
+Type introduced for generating the JSON schema `anyOf` keyword.
+
+Can be added to `combinationkeywords` for some Struct to add the keyword to the generated schema of that struct,
+    or chained with other keywords.
+
+# Example
+```julia
+combinationkeywords(MyStructType) = (AnyOf{StructTypeA, StructTypeB}, Not{AnyOf{StructTypeC, StructTypeD}})
+```
+"""
+struct AnyOf{T,S} end
+
+"""
+    OneOf{T}
+
+Type introduced for generating the JSON schema `oneOf` keyword.
+
+Can be added to `combinationkeywords` for some Struct to add the keyword to the generated schema of that struct,
+    or chained with other keywords.
+
+# Example
+```julia
+combinationkeywords(MyStructType) = (OneOf{StructTypeA, StructTypeB}, Not{OneOf{StructTypeC, StructTypeD}})
+```
+"""
+struct OneOf{T,S} end
+
+"""
+    Not{T}
+
+Type introduced for generating the JSON schema `not` keyword.
+
+Can be added to `combinationkeywords` for some Struct to add the keyword to the generated schema of that struct,
+    or chained with other keywords.
+
+# Example
+```julia
+combinationkeywords(MyStructType) = (Not{StructA}, AnyOf{Not{StructB}, StructC})
+```
+"""
+struct Not{T} end
+
+"""
+    combinationkeywords(T::Type)::Tuple
+
+Specifies which JSON boolean combination keywords will be included in the generated schema for a type.
+
+Elements should be one of the following types: `AllOf{T,S}`, `AnyOf{T,S}`, `OneOf{T,S}`, `Not{T}`.
+
+# Example
+```julia
+combinationkeywords(MyStructType) = (AllOf{SchemaA, SchemaB}, Not{SchemaC})
+```
+"""
+function combinationkeywords end
+
+combinationkeywords(::Type) = ()

src/JSONSchemaGenerator.jl

@@ -8,6 +8,8 @@ if !isdefined(Base, :fieldtypes) && VERSION < v"1.1"
     fieldtypes(T::Type) = (Any[fieldtype(T, i) for i in 1:fieldcount(T)]...,)
 end
 
+include("CombinationKeywordTypes.jl")
+
 # by default we assume the type is a custom type, which should be a JSON object
 _json_type(::Type{<:Any}) = :object
 #_json_type(::Type{<:AbstractDict}) = :object
@@ -26,6 +28,12 @@ _json_type(::Type{Base.UUID}) = :string
 _json_type(::Type{T}) where {T <: Dates.TimeType} = :string
 _json_type(::Type{VersionNumber}) = :string
 _json_type(::Type{Base.Regex}) = :string
+_json_type(::Type{<:Val}) = :const
+_json_type(::Type{<:Tuple}) = :enum
+_json_type(::Type{<:AllOf}) = :keyword
+_json_type(::Type{<:AnyOf}) = :keyword
+_json_type(::Type{<:OneOf}) = :keyword
+_json_type(::Type{<:Not}) = :keyword
 
 _is_nothing_union(::Type) = false
 _is_nothing_union(::Type{Nothing}) = false
@@ -130,6 +138,12 @@ function _generate_json_object(julia_type::Type, settings::SchemaSettings)
     if is_top_level && settings.use_references
         d["\$defs"] = _generate_json_reference_types(settings)
     end
+    for combination_type in combinationkeywords(julia_type)
+        _json_type(combination_type) == :keyword ? nothing : error("combinationkeywords($julia_type) should only contain valid keywords")
+        keyword_dict = _generate_json_type_def(combination_type, settings)
+        issubset(keys(keyword_dict), keys(d)) ? error("each keyword should only appear at most once in combinationkeywords($julia_type)") : nothing
+        merge!(d, keyword_dict)
+    end
     return d
 end
 
@@ -154,12 +168,48 @@ function _generate_json_type_def(::Val{:array}, julia_type::Type{<:AbstractArray
     )
 end
 
+function _generate_json_type_def(::Val{:const}, julia_type::Type{<:Val}, settings::SchemaSettings)
+    return settings.dict_type{String, Any}(
+        "const" => julia_type.parameters[1]
+    )
+end
+
+function _generate_json_type_def(::Val{:enum}, julia_type::Type{<:Tuple}, settings::SchemaSettings)
+    return settings.dict_type{String, Any}(
+        "enum" => [p isa Symbol ? String(p) : p for p in julia_type.parameters]
+    )
+end
+
 function _generate_json_type_def(::Val{:enum}, julia_type::Type, settings::SchemaSettings)
     return settings.dict_type{String, Any}(
         "enum" => string.(instances(julia_type))
     )
 end
 
+function _generate_json_type_def(::Val{:keyword}, julia_type::Type{AllOf{T,S}}, settings::SchemaSettings) where {T,S}
+    return settings.dict_type{String, Any}(
+        "allOf" => [_generate_json_type_def(T, settings), _generate_json_type_def(S, settings)]
+    )
+end
+
+function _generate_json_type_def(::Val{:keyword}, julia_type::Type{AnyOf{T,S}}, settings::SchemaSettings) where {T,S}
+    return settings.dict_type{String, Any}(
+        "anyOf" => [_generate_json_type_def(T, settings), _generate_json_type_def(S, settings)]
+    )
+end
+
+function _generate_json_type_def(::Val{:keyword}, julia_type::Type{OneOf{T,S}}, settings::SchemaSettings) where {T,S}
+    return settings.dict_type{String, Any}(
+        "oneOf" => [_generate_json_type_def(T, settings), _generate_json_type_def(S, settings)]
+    )
+end
+
+function _generate_json_type_def(::Val{:keyword}, julia_type::Type{Not{T}}, settings::SchemaSettings) where {T}
+    return settings.dict_type{String, Any}(
+        "not" => _generate_json_type_def(T, settings)
+    )
+end
+
 function _generate_json_type_def(::Val, julia_type::Type, settings::SchemaSettings)
     return settings.dict_type{String, Any}(
         "type" => string(_json_type(julia_type))

test/runtests.jl

@@ -9,6 +9,8 @@ using StructTypes
 module TestTypes
     using Dates
     using StructTypes
+    import JSONSchemaGenerator
+    const JSG = JSONSchemaGenerator
 
     struct BasicSchema
         int::Int64
@@ -84,6 +86,42 @@ module TestTypes
             NestedSchema(),
         )
     end
+
+    struct ConstantInt1Schema
+        int::Val{1}
+    end
+    struct EnumInt2Or3Schema
+        int::Tuple{2,3}
+    end
+    struct ConstantBoolTrueSchema
+        bool::Val{true}
+    end
+    struct BooleanCombinationSchema
+        int::Int
+        bool::Bool
+    end
+    JSG.combinationkeywords(::Type{BooleanCombinationSchema}) = [
+        JSG.AllOf{
+            JSG.AnyOf{ConstantInt1Schema, EnumInt2Or3Schema},
+            JSG.Not{ConstantBoolTrueSchema}
+        }
+    ]
+    StructTypes.StructType(::Type{BooleanCombinationSchema}) = StructTypes.Struct()
+
+    struct BadBooleanCombinationSchema
+        int::Int
+    end
+    StructTypes.StructType(::Type{BadBooleanCombinationSchema}) = StructTypes.Struct()
+    JSG.combinationkeywords(::Type{BadBooleanCombinationSchema}) = [
+        JSG.AllOf{ConstantInt1Schema, ConstantInt1Schema},
+        JSG.AllOf{EnumInt2Or3Schema, EnumInt2Or3Schema}
+    ]
+
+    struct BadBooleanCombinationSchema2
+        int::Int
+    end
+    StructTypes.StructType(::Type{BadBooleanCombinationSchema2}) = StructTypes.Struct()
+    JSG.combinationkeywords(::Type{BadBooleanCombinationSchema2}) = [Int32]
 end
 
 function test_json_schema_validation(obj::T) where T
@@ -269,3 +307,28 @@ end
     json_schema = JSONSchemaGenerator.schema(TestTypes.NestedSchema, use_references=true, dict_type=Dict)
     test_json_schema_validation(json_schema, TestTypes.NestedSchema())
 end
+
+@testset "Boolean Combination of Schemas" begin
+    @testset "Good weather" begin
+        combo_schema = JSONSchemaGenerator.schema(TestTypes.BooleanCombinationSchema)
+        constantint1_schema = JSONSchemaGenerator.schema(TestTypes.ConstantInt1Schema)
+        enumint2or3_schema = JSONSchemaGenerator.schema(TestTypes.EnumInt2Or3Schema)
+        constantbooltrue_schema = JSONSchemaGenerator.schema(TestTypes.ConstantBoolTrueSchema)
+
+        @test combo_schema["allOf"][1]["anyOf"][1] == constantint1_schema
+        @test combo_schema["allOf"][1]["anyOf"][2] == enumint2or3_schema
+        @test combo_schema["allOf"][2]["not"] == constantbooltrue_schema
+
+        test_json_schema_validation(TestTypes.BooleanCombinationSchema(1, false))
+        test_json_schema_validation(TestTypes.BooleanCombinationSchema(2, false))
+        test_json_schema_validation(TestTypes.BooleanCombinationSchema(3, false))
+    end
+
+    @testset "Multiple uses of same keyword in one object" begin
+        @test_throws Exception bad_combo_schema = JSONSchemaGenerator.schema(TestTypes.BadBooleanCombinationSchema)
+    end
+
+    @testset "Use of incorrect type in combinationkeywords" begin
+        @test_throws Exception bad_combo_schema2 = JSONSchemaGenerator.schema(TestTypes.BadBooleanCombinationSchema2)
+    end
+end