Include instance in annotation handler and allow undefined return

Author: jdesrosiers

lib/experimental.d.ts

@@ -73,7 +73,7 @@ export type Keyword<A> = {
   collectEvaluatedProperties?: (compiledKeywordValue: A, instance: JsonNode, context: ValidationContext, isTop?: boolean) => Set<string> | false;
   collectEvaluatedItems?: (compiledKeywordValue: A, instance: JsonNode, context: ValidationContext, isTop?: boolean) => Set<number> | false;
   collectExternalIds?: (visited: Set<string>, parentSchema: Browser<SchemaDocument>, schema: Browser<SchemaDocument>) => Promise<Set<string>>;
-  annotation?: <B>(compiledKeywordValue: A) => B;
+  annotation?: <B>(compiledKeywordValue: A, instance: JsonNode) => B | undefined;
 };
 
 export type ValidationContext = {

lib/keywords/validation.js

@@ -85,12 +85,13 @@ const interpret = (url, instance, { ast, dynamicAnchors, errors, annotations, ou
             }
             errors.push(...context.errors);
           } else {
-            if (keywordHandler.annotation) {
+            const annotation = keywordHandler.annotation?.(keywordValue, instance);
+            if (annotation !== undefined) {
               schemaAnnotations.unshift({
                 keyword: keywordId,
                 absoluteKeywordLocation: schemaUri,
                 instanceLocation: Instance.uri(instance),
-                annotation: keywordHandler.annotation(keywordValue)
+                annotation: annotation
               });
             }
             for (const contextAnnotation of context.annotations) {