Skip to content

santhosh-tekuri/jsonschema

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

jsonschema v5.1.1

License GoDoc Go Report Card Build Status codecov.io

Package jsonschema provides json-schema compilation and validation.

Benchmarks

Features:

  • implements draft 2020-12, draft 2019-09, draft-7, draft-6, draft-4
  • fully compliant with JSON-Schema-Test-Suite, (excluding some optional)
    • list of optional tests that are excluded can be found in schema_test.go(variable skipTests)
  • validates schemas against meta-schema
  • full support of remote references
  • support of recursive references between schemas
  • detects infinite loop in schemas
  • thread safe validation
  • rich, intuitive hierarchial error messages with json-pointers to exact location
  • supports output formats flag, basic and detailed
  • supports enabling format and content Assertions in draft2019-09 or above
    • change Compiler.AssertFormat, Compiler.AssertContent to true
  • compiled schema can be introspected. easier to develop tools like generating go structs given schema
  • supports user-defined keywords via extensions
  • implements following formats (supports user-defined)
    • date-time, date, time, duration, period (supports leap-second)
    • uuid, hostname, email
    • ip-address, ipv4, ipv6
    • uri, uriref, uri-template(limited validation)
    • json-pointer, relative-json-pointer
    • regex, format
  • implements following contentEncoding (supports user-defined)
    • base64
  • implements following contentMediaType (supports user-defined)
    • application/json
  • can load from files/http/https/string/[]byte/io.Reader (supports user-defined)

see examples in godoc

The schema is compiled against the version specified in $schema property. If "$schema" property is missing, it uses latest draft which currently implemented by this library.

You can force to use specific version, when $schema is missing, as follows:

compiler := jsonschema.NewCompiler()
compiler.Draft = jsonschema.Draft4

This package supports loading json-schema from filePath and fileURL.

To load json-schema from HTTPURL, add following import:

import _ "github.com/santhosh-tekuri/jsonschema/v5/httploader"

Rich Errors

The ValidationError returned by Validate method contains detailed context to understand why and where the error is.

schema.json:

{
      "$ref": "t.json#/definitions/employee"
}

t.json:

{
    "definitions": {
        "employee": {
            "type": "string"
        }
    }
}

doc.json:

1

assuming err is the ValidationError returned when doc.json validated with schema.json,

fmt.Printf("%#v\n", err) // using %#v prints errors hierarchy

Prints:

[I#] [S#] doesn't validate with file:///Users/santhosh/jsonschema/schema.json#
  [I#] [S#/$ref] doesn't validate with 'file:///Users/santhosh/jsonschema/t.json#/definitions/employee'
    [I#] [S#/definitions/employee/type] expected string, but got number

Here I stands for instance document and S stands for schema document.
The json-fragments that caused error in instance and schema documents are represented using json-pointer notation.
Nested causes are printed with indent.

To output err in flag output format:

b, _ := json.MarshalIndent(err.FlagOutput(), "", "  ")
fmt.Println(string(b))

Prints:

{
  "valid": false
}

To output err in basic output format:

b, _ := json.MarshalIndent(err.BasicOutput(), "", "  ")
fmt.Println(string(b))

Prints:

{
  "valid": false,
  "errors": [
    {
      "keywordLocation": "",
      "absoluteKeywordLocation": "file:///Users/santhosh/jsonschema/schema.json#",
      "instanceLocation": "",
      "error": "doesn't validate with file:///Users/santhosh/jsonschema/schema.json#"
    },
    {
      "keywordLocation": "/$ref",
      "absoluteKeywordLocation": "file:///Users/santhosh/jsonschema/schema.json#/$ref",
      "instanceLocation": "",
      "error": "doesn't validate with 'file:///Users/santhosh/jsonschema/t.json#/definitions/employee'"
    },
    {
      "keywordLocation": "/$ref/type",
      "absoluteKeywordLocation": "file:///Users/santhosh/jsonschema/t.json#/definitions/employee/type",
      "instanceLocation": "",
      "error": "expected string, but got number"
    }
  ]
}

To output err in detailed output format:

b, _ := json.MarshalIndent(err.DetailedOutput(), "", "  ")
fmt.Println(string(b))

Prints:

{
  "valid": false,
  "keywordLocation": "",
  "absoluteKeywordLocation": "file:///Users/santhosh/jsonschema/schema.json#",
  "instanceLocation": "",
  "errors": [
    {
      "valid": false,
      "keywordLocation": "/$ref",
      "absoluteKeywordLocation": "file:///Users/santhosh/jsonschema/schema.json#/$ref",
      "instanceLocation": "",
      "errors": [
        {
          "valid": false,
          "keywordLocation": "/$ref/type",
          "absoluteKeywordLocation": "file:///Users/santhosh/jsonschema/t.json#/definitions/employee/type",
          "instanceLocation": "",
          "error": "expected string, but got number"
        }
      ]
    }
  ]
}

CLI

to install go install github.com/santhosh-tekuri/jsonschema/v5/cmd/jv@latest

jv [-draft INT] [-output FORMAT] [-assertformat] [-assertcontent] <json-schema> [<json-doc>]...
  -assertcontent
    	enable content assertions with draft >= 2019
  -assertformat
    	enable format assertions with draft >= 2019
  -draft int
    	draft used when '$schema' attribute is missing. valid values 4, 5, 7, 2019, 2020 (default 2020)
  -output string
    	output format. valid values flag, basic, detailed

if no <json-doc> arguments are passed, it simply validates the <json-schema>.
if $schema attribute is missing in schema, it uses latest version. this can be overridden by passing -draft flag

exit-code is 1, if there are any validation errors

Validating YAML Documents

since yaml supports non-string keys, such yaml documents are rendered as invalid json documents.
yaml parser returns map[interface{}]interface{} for object, whereas json parser returns map[string]interface{}.
this package accepts only map[string]interface{}, so we need to manually convert them to map[string]interface{}

https://play.golang.org/p/Hhax3MrtD8r

the above example shows how to validate yaml document with jsonschema.
the conversion explained above is implemented by toStringKeys function