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"}].
Patterns
The pattern and patternProperties keywords use the syntax of RE2
(https://github.com/google/re2/wiki/Syntax), the same syntax as the =~
operator, and are matched in time linear in the length of the text. A
pattern matches if it matches any part of the text, and $ matches at
the end of the text only. Look-around, backreferences, atomic groups and
possessive quantifiers do not exist in this syntax. A schema with a pattern
RE2 refuses is an error, even if the subject never reaches the pattern. A
rule written with look-ahead is written as several pattern keywords under
allOf instead:
{"type": "string", "minLength": 12, "allOf": [{"pattern": "[0-9]"}, {"pattern": "[A-Z]"}]}.
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;
isCompliant
isCompliant(validationSubject, OBJECT schema):
This function tests the validationSubject for compliance 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;
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";
isCompliantWithExternalSchemas
isCompliantWithExternalSchemas(validationSubject, OBJECT jsonSchema, ARRAY externalSchemas):
This function tests the validationSubject for compliance 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.
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;