jsonschema

This library contains the functions for testing the compliance of a value with a JSON schema.

JSON Schema Validation

Validate data structures against JSON Schema 2020-12 specifications. Two modes: simple boolean checks and detailed validation results with errors.

Function Selection

Need Function Returns
Pass/fail check isCompliant boolean
Pass/fail with $ref isCompliantWithExternalSchemas boolean
Detailed errors validate object
Detailed with $ref validateWithExternalSchemas object

Simple Validation

Check if input matches expected structure:

policy "validate request body"
permit
    action == "api:create"
where
    var schema = {
        "type": "object",
        "properties": {
            "name": { "type": "string", "minLength": 1 },
            "age":  { "type": "integer", "minimum": 0 }
        },
        "required": ["name"]
    };
    jsonschema.isCompliant(resource.body, schema);

Example: resource.body = {"name": "Alice", "age": 30}. Schema requires object with string “name” (min 1 char) and optional integer “age” (min 0). Returns true.

Using $ref for Schema Composition

When schemas reference other schemas via $ref, pass referenced schemas in the externalSchemas array. Each external schema must have an $id field matching the $ref URI.

policy "validate with shared schemas"
permit
where
    var addressSchema = {
        "$id": "https://example.com/address",
        "type": "object",
        "properties": {
            "city": { "type": "string" },
            "zip":  { "type": "string", "pattern": "^[0-9]{5}$" }
        },
        "required": ["city", "zip"]
    };
    var orderSchema = {
        "type": "object",
        "properties": {
            "shipping": { "$ref": "https://example.com/address" }
        }
    };
    jsonschema.isCompliantWithExternalSchemas(
        resource.order, orderSchema, [addressSchema]
    );

Example: resource.order = {"shipping": {"city": "Berlin", "zip": "10115"}}. The orderSchema references addressSchema via $ref. The validator resolves $ref by matching the URI to the $id in externalSchemas. Returns true.

Detailed Error Information

Use validate functions to get error locations and messages:

policy "reject with details"
deny
    action == "submit"
where
    var result = jsonschema.validate(resource.form, resource.formSchema);
    !result.valid;
obligation
    { "type": "validationError", "errors": result.errors }

Example: If resource.form = {"zip": "ABC"} fails pattern validation, result.errors contains: [{"path": "/zip", "message": "does not match pattern ^[0-9]{5}$", "type": "pattern", "schemaPath": "/properties/zip"}].

validate

validate(validationSubject, OBJECT schema): This function validates the validationSubject against the provided JSON schema schema and returns a detailed validation result.

The result contains a valid boolean field and an errors array with detailed information about any validation failures. Each error includes the location in the subject (path), a human-readable message, the validation keyword that failed (type), and the schema location (schemaPath).

The schema itself cannot be validated and improper schema definitions may lead to unexpected results.

Note: The schema is expected to comply with: JSON Schema 2020-12

Example:

policy "validate_document_metadata"
permit action == "upload:document";
  var metadataSchema = {
    "type": "object",
    "properties": {
      "classification": { "enum": ["public", "internal", "confidential", "secret"] },
      "owner": { "type": "string", "minLength": 1 },
      "createdAt": { "type": "string", "format": "date-time" }
    },
    "required": ["classification", "owner"]
  };
  var result = jsonschema.validate(resource.metadata, metadataSchema);
  result.valid;

validateWithExternalSchemas

validateWithExternalSchemas(validationSubject, OBJECT jsonSchema, ARRAY externalSchemas): This function validates the validationSubject against the provided JSON schema schema and returns a detailed validation result including error details.

The result contains a valid boolean field and an errors array with detailed information about any validation failures. Each error includes the location in the subject (path), a human-readable message, the validation keyword that failed (type), and the schema location (schemaPath).

The schema itself cannot be validated and improper schema definitions may lead to unexpected results. If the jsonSchema contains external references to other schemas, the validation function looks up the schemas in externalSchemas based on explicitly defined $id field in the schemas. If no $id field is provided, the schema will not be detectable.

Note: The schema is expected to comply with: JSON Schema 2020-12

Example:

policy "validate_api_request_with_shared_schemas"
permit action == "api:call";
  var addressSchema = {
    "$id": "https://schemas.company.com/address",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "street": { "type": "string" },
      "city": { "type": "string" },
      "country": { "type": "string", "minLength": 2, "maxLength": 2 }
    },
    "required": ["street", "city", "country"]
  };
  var userSchema = {
    "$id": "https://schemas.company.com/user",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "userId": { "type": "string", "format": "uuid" },
      "email": { "type": "string", "format": "email" },
      "role": { "enum": ["user", "admin", "auditor"] },
      "address": { "$ref": "https://schemas.company.com/address" }
    },
    "required": ["userId", "email", "role"]
  };
  var result = jsonschema.validateWithExternalSchemas(
    resource.userData,
    userSchema,
    [addressSchema]
  );
  result.valid || result.errors[0].type == "required";

isCompliant

isCompliant(validationSubject, OBJECT schema): This function tests the validationSubject for compliance with the with the provided JSON schema schema.

The schema itself cannot be validated and improper schema definitions may lead to unexpected results. If validationSubject is compliant with the schema, the function returns true, else it returns false.

Note: The schema is expected to comply with: JSON Schema 2020-12

Example:

policy "example"
permit
  var jsonSchema = {
                     "type": "boolean"
                   };
  jsonschema.isCompliant(true, jsonSchema) == true;
  jsonschema.isCompliant(123, jsonSchema) == false;

isCompliantWithExternalSchemas

isCompliantWithExternalSchemas(validationSubject, OBJECT jsonSchema, ARRAY externalSchemas): This function tests the validationSubject for compliance with the with the provided JSON schema schema.

The schema itself cannot be validated and improper schema definitions may lead to unexcpected results. If validationSubject is compliant with the schema, the function returns true, else it returns false. If the jsonSchema contains external references to other schemas, the validation function looks up the schemas in externalSchemas based on explicitly defined $id field in the schemas. If no $id field is provided, the schema will not be detectable.

Note: The schema is expected to comply with: JSON Schema 2020-12

Example:

policy "example"
permit
  var externals = {
        "$id": "https://example.com/coordinates",
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "title": "Coordinates",
        "type": "object",
        "properties" : {
            "x": { "type": "integer" },
            "y": { "type": "integer" },
            "z": { "type": "integer" }
        }
    };
  var schema = {
        "$id": "https://example.com/triangle.schema.json",
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "title": "Triangle",
        "type": "object",
        "properties": {
            "A": { "$ref": "https://example.com/coordinates" },
            "B": { "$ref": "https://example.com/coordinates" },
            "C": { "$ref": "https://example.com/coordinates" }
      };
  var valid = {
           "A" : { "x" : 1, "y" : 2, "z" : 3 },
           "B" : { "x" : 1, "y" : 2, "z" : 3 },
           "C" : { "x" : 1, "y" : 2, "z" : 3 }
        };
  isCompliantWithExternalSchemas(valid, schema, externals) == true;
  var invalid = {
           "A" : { "x" : "I AM NOT A NUMBER I AM A FREE MAN", "y" : 2, "z" : 3 },
           "B" : { "x" : 1, "y" : 2, "z" : 3 },
           "C" : { "x" : 1, "y" : 2, "z" : 3 }
        };
  isCompliantWithExternalSchemas(invalid, schema, externals) == false;