Annotations

Annotation collection is a process that happens alongside validation. Annotations are only present in a successful validation result:

Validator.Result result = new ValidatorFactory().validate(schema, instance);

// Collected annotation during the validation process
List<Annotation> annotations = result.getAnnotations(); 

Annotation collection is described in detail in specification. Some annotation will be discarded and not present in the final result.

Annotation type

Documentation.

annotation (Object)

Annotation value. Can be of any type.

Example: List.of("foo")

evaluationPath (String)

JSON pointer representing evaluation point in schema JSON.

Example: /properties

instanceLocation (String)

JSON pointer representing evaluation point in instance JSON.

Example: /data

keyword (String)

Keyword name associated with given evaluation point.

Example: properties

schemaLocation (String)

Absolute schema location (URI) which uniquely identifies given schema.

Example: https://harrel.dev/3077cb97#

Provided annotations

Some keywords defined by specification also define the annotation which they should produce:

Keyword	Description	Type	Example
`properties`	Set of property names which were validated by this keyword.	`Set<String>`	`Set.of("prop1", "prop2")`
`additionalProperties`
`patternProperties`
`unevaluatedProperties`
`prefixItems`	Number of items validated by this keyword. If all items were validated, then `Boolean.TRUE`.	`Integer` or `Boolean.TRUE`	`2`, `Boolean.TRUE`
`items` (legacy)	Number of items validated by this keyword. If all items were validated, then `Boolean.TRUE`.	`Integer` or `Boolean.TRUE`	`2`, `Boolean.TRUE`
`items` (Draft 2020-12)	`Boolean.TRUE` if validated successfully, meaning all remaining items were validated.	`Boolean.TRUE`	`Boolean.TRUE`
`additionalItems`
`unevaluatedItems`
`contains`	List of item indices (ordered) which validated against `contains` schema.	`List<Integer>`	`List.of(0, 4, 5)`

Examples

Object

Schema	Instance
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "urn:object", "properties": { "foo": { "title": "foo schema", "type": "number" }, "bar": { "$ref": "#/$defs/bar" }, "baz": false }, "unevaluatedProperties": true, "$defs": { "bar": { "const": "bar" } } }	{ "foo": 1, "bar": "bar", "bax": {} }

Produces the following annotations:

`annotation`	`evaluationPath`	`instanceLocation`	`keyword`	`schemaLocation`
`"foo schema"`	/properties/foo/title	/foo	title	urn:object#/properties/foo
`Set.of("bar", "foo")`	/properties	(empty string)	properties	urn:object#
`Set.of("bax")`	/unevaluatedProperties	(empty string)	unevaluatedProperties	urn:object#

Array

Schema	Instance
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "urn:array", "prefixItems": [ { "type": "boolean" }, { "type": "string" } ], "items": { "type": "number" }, "contains": { "unknownKeyword": "value", "type": "number", "multipleOf": 2 } }	[ true, "second value", 1, 2, 3, 4 ]

Produces the following annotations:

`annotation`	`evaluationPath`	`instanceLocation`	`keyword`	`schemaLocation`
`"value"`	/contains/unknownKeyword	/3	unknownKeyword	urn:array#/contains
`"value"`	/contains/unknownKeyword	/5	unknownKeyword	urn:array#/contains
`List.of(3, 5)`	/contains	(empty string)	contains	urn:array#
`2`	/prefixItems	(empty string)	prefixItems	urn:array#
`true`	/items	(empty string)	items	urn:array#

04 August 2025