Introduction to jsonvalidate

You need a JSON schema file; see json-schema.org for details on writing these. Often someone else has done the hard work of writing one for you, and you can just check that the JSON you are producing or consuming conforms to the schema.

They describe a JSON based product catalogue, where each product has an id, a name, a price, and an optional set of tags. A JSON representation of a product is:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme's catalog",
    "type": "object",
    "properties": {
        "id": {
            "description": "The unique identifier for a product",
            "type": "integer"
        },
        "name": {
            "description": "Name of the product",
            "type": "string"
        },
        "price": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true
        },
        "tags": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "minItems": 1,
            "uniqueItems": true
        }
    },
    "required": ["id", "name", "price"]
}

This ensures the types of all fields, enforces presence of id, name and price, checks that the price is not negative and checks that if present tags is a unique list of strings.

There are two ways of passing the schema in to R; as a string or as a filename. If you have a large schema loading as a file will generally be easiest! Here’s a string representing the schema (watch out for escaping quotes):

schema <- '{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme\'s catalog",
    "type": "object",
    "properties": {
        "id": {
            "description": "The unique identifier for a product",
            "type": "integer"
        },
        "name": {
            "description": "Name of the product",
            "type": "string"
        },
        "price": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true
        },
        "tags": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "minItems": 1,
            "uniqueItems": true
        }
    },
    "required": ["id", "name", "price"]
}'

The returned object is a function that takes as its first argument a json string, or a filename of a json file. The empty list will fail validation because it does not contain any of the required fields:

The attribute “errors” is a data.frame and is present only when the json fails validation. The error messages come straight from ajv and they may not always be that informative.

Alternatively, to throw an error if the json does not validate, add error = TRUE to the call:

The names comes from within the ajv source, and may be annoying to work with programmatically.

There is also a simple interface where you take the schema and the json at the same time:

However, this will be much slower than building the schema object once and using it repeatedly.

Prior to 1.4.0, the recommended way of building a reusable validator object was to use jsonvalidate::json_validator; this is still supported but note that it has different defaults to jsonvalidate::json_schema (using imjv for backward compatibility).

While we do not intend on removing this old interface, new code should prefer both jsonvalidate::json_schema and the ajv engine.

Combining schemas

You can combine schemas with ajv engine. You can reference definitions within one schema

schema <- '{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "definitions": {
    "city": { "type": "string" }
  },
  "type": "object",
  "properties": {
    "city": { "$ref": "#/definitions/city" }
  }
}'
json <- '{
    "city": "Firenze"
}'
jsonvalidate::json_validate(json, schema, engine = "ajv")

## [1] TRUE

You can reference schema from other files

city_schema <- '{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "string",
  "enum": ["Firenze"]
}'
address_schema <- '{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type":"object",
  "properties": {
    "city": { "$ref": "city.json" }
  }
}'

path <- tempfile()
dir.create(path)
address_path <- file.path(path, "address.json")
city_path <- file.path(path, "city.json")
writeLines(address_schema, address_path)
writeLines(city_schema, city_path)
jsonvalidate::json_validate(json, address_path, engine = "ajv")

## [1] TRUE

You can combine schemas in subdirectories. Note that the $ref path needs to be relative to the schema path. You cannot use absolute paths in $ref and jsonvalidate will throw an error if you try to do so.

user_schema = '{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "required": ["address"],
  "properties": {
    "address": {
      "$ref": "sub/address.json"
    }
  }
}'

json <- '{
  "address": {
    "city": "Firenze"
  }
}'

path <- tempfile()
subdir <- file.path(path, "sub")
dir.create(subdir, showWarnings = FALSE, recursive = TRUE)
city_path <- file.path(subdir, "city.json")
address_path <- file.path(subdir, "address.json")
user_path <- file.path(path, "schema.json")
writeLines(city_schema, city_path)
writeLines(address_schema, address_path)
writeLines(user_schema, user_path)
jsonvalidate::json_validate(json, user_path, engine = "ajv")

## [1] TRUE

Introduction to jsonvalidate

Rich FitzJohn

2025-02-07

Combining schemas