Annotation Support

Annotation Support

JSON Schema annotations are schema metadata collected during validation. They are different from assertion keywords: assertions decide whether an instance is valid, while annotations describe useful information about instance locations that were successfully evaluated by a schema.

This library supports JSON Schema annotation collection as an opt-in feature. It can be useful for schema-driven UI, documentation, diagnostics, API tooling, code generation, and application logic that needs metadata from a schema after validation.

Enable annotation collection

Annotation collection is disabled by default. Enable it when creating the JsonValidator:

var jsonValidator = new JsonValidator(jsonSchema, new JsonValidatorOptions
{
    CollectAnnotations = true
});

To receive annotations in ValidationResult.Annotations, validate with JsonSchemaOptions.OutputFormat set to OutputFormat.List:

ValidationResult validationResult = jsonValidator.Validate(instance, new JsonSchemaOptions
{
    OutputFormat = OutputFormat.List
});

Annotations are returned only when:

• JsonValidatorOptions.CollectAnnotations is true when the validator is created.
• JsonSchemaOptions.OutputFormat is OutputFormat.List when validation is executed.
• The validation result is valid.
• The schema application that contains the annotation keyword succeeds.
• The annotation keyword applies to the current instance type.

For example, format, contentEncoding, contentMediaType, and contentSchema annotations apply to string instances. Non-string instances can still be valid for these keywords, but no annotation is produced for them.

contentSchema is collected only when it is adjacent to contentMediaType, following the JSON Schema specification requirement that contentSchema should be ignored without contentMediaType.

Example

using LateApexEarlySpeed.Json.Schema;
using LateApexEarlySpeed.Json.Schema.Common;

string jsonSchema = """
{
  "title": "User email",
  "description": "A contact email address.",
  "format": "email"
}
""";

string instance = "\"user@example.com\"";

var jsonValidator = new JsonValidator(jsonSchema, new JsonValidatorOptions
{
    CollectAnnotations = true
});

ValidationResult validationResult = jsonValidator.Validate(instance, new JsonSchemaOptions
{
    OutputFormat = OutputFormat.List
});

foreach (var annotation in validationResult.Annotations)
{
    Console.WriteLine($"{annotation.Keyword}: {annotation.Value}");
}

This can produce annotations such as:

title: User email
description: A contact email address.
format: email

Annotation result data

Each item in ValidationResult.Annotations contains the annotation value and location information that connects the result back to both the JSON instance and the JSON Schema location that produced it.

• Keyword: The JSON Schema keyword that produced the annotation, such as title, description, default, or format.
• Value: The annotation value from the schema keyword. This is represented as a JsonElement, so it can be a string, number, boolean, object, array, or null depending on the keyword.
• InstanceLocation: The JSON Pointer location of the instance value that the annotation applies to.
• RelativeKeywordLocation: The relative JSON Pointer location of the annotation keyword in the schema evaluation path. It can include by-reference applicators such as $ref or $dynamicRef.
• SchemaResourceBaseUri: The base URI of the schema resource that contributed the annotation.
• SubSchemaRefFullUri: The full URI of the resolved subschema location that contributed the annotation.

The location fields use the same concepts as validation error output. They are useful when building tools that need to map schema metadata back to a specific JSON value and schema resource.

Performance

Annotation collection is opt-in. If JsonValidatorOptions.CollectAnnotations is not enabled, normal validation does not collect annotation output.

For repeated validation, continue reusing JsonValidator instances when possible. A JsonValidator represents a parsed schema, so reusing it avoids repeatedly parsing schema text and keeps validation efficient.

Test coverage

Annotation behavior is verified with the official JSON Schema annotation test suite.