This project provides some basic tools for performing JSON Schema validation with Circe.
The current version of the library is a wrapper for the Everit JSON Schema Validator, although it does
not expose any org.everit
or org.json
types in its public API. Future releases will drop the Everit dependency,
although we don't currently have an exact timeline for when this will happen.
The library only supports Draft 7 of the JSON Schema specification.
We are currently testing against the non-ref
cases provided in the JSON Schema Test Suite.
Note that this library currently depends on the most recent version of the Everit validator, which is not published to Maven Central. You'll need to add the Jitpack resolver to your build:
resolvers += "jitpack".at("https://jitpack.io")
See the Everit documentation for the equivalent Maven configuration.
Once you've configured the resolver, you can add this project to your dependencies:
libraryDependencies += "io.circe" %% "circe-json-schema" % "0.1.0"
And the appropriate Everit version will be pulled in transitively.
The io.circe.schema
package contains just two types (Schema
and ValidationError
), each of which
has just a few methods. You can load a schema from either a Json
value or a string.
import io.circe.literal._
import io.circe.schema.Schema
val polygonSchema: Schema = Schema.load(
json"""
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "Polygon"
},
"coordinates": {
"type": "array",
"items": {
"type": "array",
"minItems": 2,
"maxItems": 3
}
}
}
}
"""
)
The validate
method on Schema
instances returns either nothing (as Valid(())
) or a non-empty
list of validation errors, so if we have some values like this:
val good = json"""{"type": "Polygon", "coordinates": [[0, 0], [1, 0], [1, 1], [0, 1]] }"""
val bad1 = json"""true"""
val bad2 = json"""{"type": "Shape", "coordinates": [[0, 0], [1, 0], [1, 1], [0, 1]] }"""
val bad3 = json"""{"type": "Polygon", "coordinates": [[0], [1, 0], [1, 2, 3, 4], [0, 1]] }"""
val bad4 = json"""{"type": "Polygon", "coordinates": [1, 0] }"""
The results look like this:
scala> polygonSchema.validate(good)
res0: cats.data.ValidatedNel[io.circe.schema.ValidationError,Unit] = Valid(())
scala> polygonSchema.validate(bad1).swap.map(_.toList).toList.flatten.map(_.getMessage).foreach(println)
#: expected type: JSONObject, found: Boolean
scala> polygonSchema.validate(bad2).swap.map(_.toList).toList.flatten.map(_.getMessage).foreach(println)
#/type: #: only 1 subschema matches out of 2
#/type:
scala> polygonSchema.validate(bad3).swap.map(_.toList).toList.flatten.map(_.getMessage).foreach(println)
#/coordinates: 2 schema violations found
#/coordinates/0: expected minimum item count: 2, found: 1
#/coordinates/2: expected maximum item count: 3, found: 4
scala> polygonSchema.validate(bad4).swap.map(_.toList).toList.flatten.map(_.getMessage).foreach(println)
#/coordinates: 2 schema violations found
#/coordinates/0: expected type: JSONArray, found: Integer
#/coordinates/1: expected type: JSONArray, found: Integer
The details of these errors and the error messages are subject to change.
This project supports the Scala code of conduct and we want all of its channels (Gitter, GitHub, etc.) to be welcoming environments for everyone.
Please see the Circe contributors' guide for details on how to submit a pull request.
circe-json-schema is licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.