Interact with JSON schemas

Description

Interact with JSON schemas, using them to validate json strings or serialise objects to JSON safely.

This interface supersedes json_schema and changes some default arguments. While the old interface is not going away any time soon, users are encouraged to switch to this interface, which is what we will develop in the future.

Public fields

Methods

Public methods

• json_schema$new()

• json_schema$validate()

• json_schema$serialise()

Method new()

Create a new json_schema object.

Usage

json_schema$new(schema, engine = "ajv", reference = NULL, strict = FALSE)

Arguments

Method validate()

Usage

json_schema$validate(
  json,
  verbose = FALSE,
  greedy = FALSE,
  error = FALSE,
  query = NULL
)

Arguments

Method serialise()

Usage

json_schema$serialise(object)

Arguments

Examples

# This is the schema from ?json_validator
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"]
}'

# We're going to use a validator object below
v <- jsonvalidate::json_validator(schema, "ajv")

# And this is some data that we might generate in R that we want to
# serialise using that schema
x <- list(id = 1, name = "apple", price = 0.50, tags = "fruit")

# If we serialise to json, then 'id', 'name' and "price' end up a
# length 1-arrays
jsonlite::toJSON(x)

# ...and that fails validation
v(jsonlite::toJSON(x))

# If we auto-unbox then 'fruit' ends up as a string and not an array,
# also failing validation:
jsonlite::toJSON(x, auto_unbox = TRUE)
v(jsonlite::toJSON(x, auto_unbox = TRUE))

# Using json_serialise we can guide the serialisation process using
# the schema:
jsonvalidate::json_serialise(x, schema)

# ...and this way we do pass validation:
v(jsonvalidate::json_serialise(x, schema))

# It is typically much more efficient to construct a json_schema
# object first and do both operations with it:
obj <- jsonvalidate::json_schema$new(schema)
json <- obj$serialise(x)
obj$validate(json)

Safe JSON serialisation

Description

Safe serialisation of json with unboxing guided by the schema.

Usage

json_serialise(
  object,
  schema,
  engine = "ajv",
  reference = NULL,
  strict = FALSE
)

Arguments

Details

When using jsonlite::toJSON we are forced to deal with the differences between R's types and those available in JSON. In particular:

• R has no scalar types so it is not clear if 1 should be serialised as a number or a vector of length 1; jsonlite provides support for "automatically unboxing" such values (assuming that length-1 vectors are scalars) or never unboxing them unless asked to using jsonlite::unbox

• JSON has no date/time values and there are many possible string representations.

• JSON has no data.frame or matrix type and there are several ways of representing these in JSON, all equally valid (e.g., row-wise, column-wise or as an array of objects).

• The handling of NULL and missing values (NA, NaN) are different

• We need to chose the number of digits to write numbers out at, balancing precision and storage.

These issues are somewhat lessened when we have a schema because we know what our target type looks like. This function attempts to use the schema to guide serialisation of json safely. Currently it only supports detecting the appropriate treatment of length-1 vectors, but we will expand functionality over time.

For a user, this function provides an argument-free replacement for jsonlite::toJSON, accepting an R object and returning a string with the JSON representation of the object. Internally the algorithm is:

1. serialise the object with jsonlite::toJSON, with auto_unbox = FALSE so that length-1 vectors are serialised as a length-1 arrays.

2. operating entirely within JavaScript, deserialise the object with JSON.parse, traverse the object and its schema simultaneously looking for length-1 arrays where the schema says there should be scalar value and unboxing these, and re-serialise with JSON.stringify

There are several limitations to our current approach, and not all unboxable values will be found - at the moment we know that schemas contained within a oneOf block (or similar) will not be recursed into.

Value

A string, representing object in JSON format. As for jsonlite::toJSON we set the class attribute to be json to mark it as serialised json.

Warning

Direct use of this function will be slow! If you are going to serialise more than one or two objects with a single schema, you should use the serialise method of a json_schema object which you create once and pass around.

Examples

# This is the schema from ?json_validator
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"]
}'

# We're going to use a validator object below
v <- jsonvalidate::json_validator(schema, "ajv")

# And this is some data that we might generate in R that we want to
# serialise using that schema
x <- list(id = 1, name = "apple", price = 0.50, tags = "fruit")

# If we serialise to json, then 'id', 'name' and "price' end up a
# length 1-arrays
jsonlite::toJSON(x)

# ...and that fails validation
v(jsonlite::toJSON(x))

# If we auto-unbox then 'fruit' ends up as a string and not an array,
# also failing validation:
jsonlite::toJSON(x, auto_unbox = TRUE)
v(jsonlite::toJSON(x, auto_unbox = TRUE))

# Using json_serialise we can guide the serialisation process using
# the schema:
jsonvalidate::json_serialise(x, schema)

# ...and this way we do pass validation:
v(jsonvalidate::json_serialise(x, schema))

# It is typically much more efficient to construct a json_schema
# object first and do both operations with it:
obj <- jsonvalidate::json_schema$new(schema)
json <- obj$serialise(x)
obj$validate(json)

Validate a json file

Description

Validate a single json against a schema. This is a convenience wrapper around json_validator(schema)(json) or json_schema$new(schema, engine = "ajv")$validate(json). See json_validator() for further details.

Usage

json_validate(
  json,
  schema,
  verbose = FALSE,
  greedy = FALSE,
  error = FALSE,
  engine = "imjv",
  reference = NULL,
  query = NULL,
  strict = FALSE
)

Arguments

Examples

# A simple schema example:
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"]
}'

# Test if some (invalid) json conforms to the schema
jsonvalidate::json_validate("{}", schema, verbose = TRUE)

# Test if some (valid) json conforms to the schema
json <- '{
    "id": 1,
    "name": "A green door",
    "price": 12.50,
    "tags": ["home", "green"]
}'
jsonvalidate::json_validate(json, schema)

# Test a fraction of a data against a reference into the schema:
jsonvalidate::json_validate(json, schema,
                            query = "tags", reference = "#/properties/tags",
                            engine = "ajv", verbose = TRUE)

Create a json validator

Description

Create a validator that can validate multiple json files.

Usage

json_validator(schema, engine = "imjv", reference = NULL, strict = FALSE)

Arguments

Value

A function that can be used to validate a schema. Additionally, the function has two attributes assigned: v8 which is the JavaScript context (used internally) and engine, which contains the name of the engine used.

Validation Engines

We support two different json validation engines, imjv ("is-my-json-valid") and ajv ("Another JSON Validator"). imjv was the original validator included in the package and remains the default for reasons of backward compatibility. However, users are encouraged to migrate to ajv as with it we support many more features, including nested schemas that span multiple files, meta schema versions later than draft-04, validating using a subschema, and validating a subset of an input data object.

If your schema uses these features we will print a message to screen indicating that you should update when running interactively. We do not use a warning here as this will be disruptive to users. You can disable the message by setting the option jsonvalidate.no_note_imjv to TRUE. Consider using withr::with_options() (or simply suppressMessages()) to scope this option if you want to quieten it within code you do not control. Alternatively, setting the option jsonvalidate.no_note_imjv to FALSE will print the message even non-interactively.

Updating the engine should be simply a case of adding engine = "ajv" to your json_validator or json_validate calls, but you may see some issues when doing so.

• Your json now fails validation: We've seen this where schemas spanned several files and are silently ignored. By including these, your data may now fail validation and you will need to either fix the data or the schema.

• Your code depended on the exact payload returned by imjv: If you are inspecting the error result and checking numbers of errors, or even the columns used to describe the errors, you will likely need to update your code to accommodate the slightly different format of ajv

• Your schema is simply invalid: If you reference an invalid metaschema for example, jsonvalidate will fail

Using multiple files

Multiple files are supported. You can have a schema that references a file child.json using {"$ref": "child.json"}—in this case if child.json includes an id or ⁠$id⁠ element it will be silently dropped and the filename used to reference the schema will be used as the schema id.

The support is currently quite limited - it will not (yet) read sub-child schemas relative to child schema ⁠$id⁠ url, and does not support reading from URLs (only local files are supported).

Examples

# A simple schema example:
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"]
}'

# Create a validator function
v <- jsonvalidate::json_validator(schema)

# Test if some (invalid) json conforms to the schema
v("{}", verbose = TRUE)

# Test if some (valid) json conforms to the schema
v('{
    "id": 1,
    "name": "A green door",
    "price": 12.50,
    "tags": ["home", "green"]
}')

# Using features from draft-06 or draft-07 requires the ajv engine:
schema <- "{
  '$schema': 'http://json-schema.org/draft-06/schema#',
  'type': 'object',
  'properties': {
    'a': {
      'const': 'foo'
    }
  }
}"

# Create the validator
v <- jsonvalidate::json_validator(schema, engine = "ajv")

# This confirms to the schema
v('{"a": "foo"}')

# But this does not
v('{"a": "bar"}')