Handle annotations as RDF-star statements

rubensworks · rubensworks · commit 0f451a621863 · 2023-01-20T16:19:49.000+01:00
diff --git a/lib/JsonLdParser.ts b/lib/JsonLdParser.ts
@@ -20,6 +20,7 @@ import {EntryHandlerKeywordValue} from "./entryhandler/keyword/EntryHandlerKeywo
 import {ParsingContext} from "./ParsingContext";
 import {Util} from "./Util";
 import {parse as parseLinkHeader} from "http-link-header";
+import { EntryHandlerKeywordAnnotation } from './entryhandler/keyword/EntryHandlerKeywordAnnotation';
 
 /**
  * A stream transformer that parses JSON-LD (text) streams to an {@link RDF.Stream}.
@@ -36,6 +37,7 @@ export class JsonLdParser extends Transform implements RDF.Sink<EventEmitter, RD
     new EntryHandlerKeywordNest(),
     new EntryHandlerKeywordType(),
     new EntryHandlerKeywordValue(),
+    new EntryHandlerKeywordAnnotation(),
     new EntryHandlerContainer(),
     new EntryHandlerKeywordUnknownFallback(),
     new EntryHandlerPredicate(),
@@ -251,7 +253,7 @@ export class JsonLdParser extends Transform implements RDF.Sink<EventEmitter, RD
     }
 
     // Skip further processing if this node is part of a literal
-    if (this.util.isLiteral(depth)) {
+    if (await this.util.isLiteral(keys, depth)) {
       handleKey = false;
     }
 
@@ -304,6 +306,7 @@ export class JsonLdParser extends Transform implements RDF.Sink<EventEmitter, RD
     this.parsingContext.jsonLiteralStack.splice(depth, 1);
     this.parsingContext.validationStack.splice(depth - 1, 2);
     this.parsingContext.literalStack.splice(depth, this.parsingContext.literalStack.length - depth);
+    this.parsingContext.annotationsBuffer.splice(depth, 1);
     // TODO: just like the literal stack, splice all other stack until the end as well?
   }
 
@@ -386,6 +389,23 @@ export class JsonLdParser extends Transform implements RDF.Sink<EventEmitter, RD
       }
       this.parsingContext.unidentifiedGraphsBuffer.splice(depth, 1);
     }
+
+    // Push unhandled annotations up the stack as nested annotations
+    const annotationsBuffer = this.parsingContext.annotationsBuffer[depth];
+    if (annotationsBuffer) {
+      // Throw an error if we reach the top, and still have annotations
+      if (annotationsBuffer.length > 0 && depth === 1) {
+        this.parsingContext.emitError(new ErrorCoded(`Annotations can not be made on top-level nodes`,
+          ERROR_CODES.INVALID_ANNOTATION));
+      }
+
+      // Pass the annotations buffer up one level in the stack
+      const annotationsBufferParent = this.parsingContext.getAnnotationsBufferSafe(depth - 1);
+      for (const annotation of annotationsBuffer) {
+        annotationsBufferParent.push(annotation);
+      }
+      delete this.parsingContext.annotationsBuffer[depth];
+    }
   }
 
   /**
diff --git a/lib/ParsingContext.ts b/lib/ParsingContext.ts
@@ -5,6 +5,8 @@ import * as RDF from "@rdfjs/types";
 import {ContextTree} from "./ContextTree";
 import {IJsonLdParserOptions, JsonLdParser} from "./JsonLdParser";
 
+export type AnnotationsBufferEntry = { predicate: RDF.Term, object: RDF.Term, reverse: boolean, nestedAnnotations: AnnotationsBufferEntry[], depth: number };
+
 /**
  * Data holder for parsing information.
  */
@@ -69,6 +71,8 @@ export class ParsingContext {
   // Quads that don't know their graph @id yet.
   // L0: stack depth; L1: values
   public readonly unidentifiedGraphsBuffer: { subject: RDF.Term, predicate: RDF.Term, object: RDF.Term, isEmbedded: boolean }[][];
+  // Stack of annotation objects on incomplete nodes.
+  public readonly annotationsBuffer: AnnotationsBufferEntry[][];
 
   // Depths that should be still flushed
   public pendingContainerFlushBuffers: { depth: number, keys: any[] }[];
@@ -115,6 +119,7 @@ export class ParsingContext {
     this.jsonLiteralStack = [];
     this.unidentifiedValuesBuffer = [];
     this.unidentifiedGraphsBuffer = [];
+    this.annotationsBuffer = [];
 
     this.pendingContainerFlushBuffers = [];
 
@@ -370,6 +375,20 @@ export class ParsingContext {
     return buffer;
   }
 
+  /**
+   * Safely get or create the depth value of {@link ParsingContext.annotationsBuffer}.
+   * @param {number} depth A depth.
+   * @return {} An element of {@link ParsingContext.annotationsBuffer}.
+   */
+  public getAnnotationsBufferSafe(depth: number): AnnotationsBufferEntry[] {
+    let buffer = this.annotationsBuffer[depth];
+    if (!buffer) {
+      buffer = [];
+      this.annotationsBuffer[depth] = buffer;
+    }
+    return buffer;
+  }
+
   /**
    * @return IExpandOptions The expand options for the active processing mode.
    */
@@ -410,6 +429,16 @@ export class ParsingContext {
       this.unidentifiedValuesBuffer[depth] = this.unidentifiedValuesBuffer[depth + depthOffset];
       delete this.unidentifiedValuesBuffer[depth + depthOffset];
     }
+    if (this.annotationsBuffer[depth + depthOffset - 1]) {
+      if (!this.annotationsBuffer[depth - 1]) {
+        this.annotationsBuffer[depth - 1] = [];
+      }
+      this.annotationsBuffer[depth - 1] = [
+        ...this.annotationsBuffer[depth - 1],
+        ...this.annotationsBuffer[depth + depthOffset - 1],
+      ];
+      delete this.annotationsBuffer[depth + depthOffset - 1];
+    }
 
     // TODO: also do the same for other stacks
   }
diff --git a/lib/Util.ts b/lib/Util.ts
@@ -3,7 +3,7 @@ import {ContextParser, ERROR_CODES, ErrorCoded, JsonLdContextNormalized,
 import * as RDF from "@rdfjs/types";
 import {DataFactory} from "rdf-data-factory";
 import {EntryHandlerContainer} from "./entryhandler/EntryHandlerContainer";
-import {ParsingContext} from "./ParsingContext";
+import { AnnotationsBufferEntry, ParsingContext } from "./ParsingContext";
 
 // tslint:disable-next-line:no-var-requires
 const canonicalizeJson = require('canonicalize');
@@ -144,14 +144,22 @@ export class Util {
 
   /**
    * Check if the given key exists inside an embedded node as direct child.
-   * @param {JsonLdContextNormalized} context A JSON-LD context.
    * @param {string} parentKey The parent key.
    * @return {boolean} If the property is embedded.
    */
   public static isPropertyInEmbeddedNode(parentKey: string): boolean {
     return parentKey === '@id';
   }
 
+  /**
+   * Check if the given key exists inside an annotation object as direct child.
+   * @param {string} parentKey The parent key.
+   * @return {boolean} If the property is an annotation.
+   */
+  public static isPropertyInAnnotationObject(parentKey: string): boolean {
+    return parentKey === '@annotation';
+  }
+
   /**
    * Check if the given IRI is valid.
    * @param {string} iri A potential IRI.
@@ -277,6 +285,9 @@ export class Util {
           case '@index':
             valueIndex = subValue;
             break;
+          case '@annotation':
+            // This keyword is allowed, but is processed like normal nodes
+            break;
           default:
             throw new ErrorCoded(`Unknown value entry '${key}' in @value: ${JSON.stringify(value)}`,
               ERROR_CODES.INVALID_VALUE_OBJECT);
@@ -764,11 +775,16 @@ export class Util {
    * This will also check higher levels,
    * because if a parent is a literal,
    * then the deeper levels are definitely a literal as well.
+   * @param {any[]} keys The keys.
    * @param {number} depth The depth.
    * @return {boolean} If we are processing a literal.
    */
-  public isLiteral(depth: number): boolean {
+  public async isLiteral(keys: any[], depth: number): Promise<boolean> {
     for (let i = depth; i >= 0; i--) {
+      if (await this.unaliasKeyword(keys[i], keys, i) === '@annotation') {
+        // Literals may have annotations, which require processing of inner nodes.
+        return false;
+      }
       if (this.parsingContext.literalStack[i] || this.parsingContext.jsonLiteralStack[i]) {
         return true;
       }
@@ -958,6 +974,35 @@ export class Util {
     } else {
       this.parsingContext.emitQuad(depth, quad);
     }
+
+    // Flush annotations
+    const annotationsBuffer = this.parsingContext.annotationsBuffer[depth];
+    if (annotationsBuffer) {
+      for (const annotation of annotationsBuffer) {
+        this.emitAnnotation(depth, quad, annotation);
+      }
+      delete this.parsingContext.annotationsBuffer[depth];
+    }
+  }
+
+  // This is a separate function to enable recursion
+  protected emitAnnotation(depth: number, quad: RDF.BaseQuad, annotation: AnnotationsBufferEntry) {
+    // Construct annotation quad
+    let annotationQuad;
+    if (annotation.reverse) {
+      this.validateReverseSubject(annotation.object);
+      annotationQuad = this.dataFactory.quad(annotation.object, annotation.predicate, quad);
+    } else {
+      annotationQuad = this.dataFactory.quad(quad, annotation.predicate, annotation.object);
+    }
+
+    // Emit annotated quad
+    this.parsingContext.emitQuad(depth, annotationQuad);
+
+    // Also emit nested annotations
+    for (const nestedAnnotation of annotation.nestedAnnotations) {
+      this.emitAnnotation(depth, annotationQuad, nestedAnnotation);
+    }
   }
 
 }
diff --git a/lib/containerhandler/ContainerHandlerIndex.ts b/lib/containerhandler/ContainerHandlerIndex.ts
@@ -69,7 +69,7 @@ export class ContainerHandlerIndex implements IContainerHandler {
             // Otherwise, attach the index to the node identifier
             for (const indexValue of indexValues) {
               await EntryHandlerPredicate.handlePredicateObject(parsingContext, util, keys, depth + 1,
-                indexProperty, indexValue, false, false);
+                indexProperty, indexValue, false, false, false);
             }
           }
         }
diff --git a/lib/containerhandler/ContainerHandlerType.ts b/lib/containerhandler/ContainerHandlerType.ts
@@ -59,7 +59,7 @@ export class ContainerHandlerType implements IContainerHandler {
       if (type) {
         // Push the type to the stack using the rdf:type predicate
         await EntryHandlerPredicate.handlePredicateObject(parsingContext, util, keys, depth + 1,
-          util.rdfType, type, false, false);
+          util.rdfType, type, false, false, false);
       }
 
       // Flush any pending flush buffers
diff --git a/lib/entryhandler/EntryHandlerArrayValue.ts b/lib/entryhandler/EntryHandlerArrayValue.ts
@@ -2,6 +2,7 @@ import * as RDF from "@rdfjs/types";
 import {ParsingContext} from "../ParsingContext";
 import {Util} from "../Util";
 import {IEntryHandler} from "./IEntryHandler";
+import { ERROR_CODES, ErrorCoded } from '../../../jsonld-context-flatten';
 
 /**
  * Handles values that are part of an array.
@@ -141,6 +142,12 @@ export class EntryHandlerArrayValue implements IEntryHandler<boolean> {
     }
 
     parsingContext.listPointerStack[depth] = listPointer;
+
+    // Error if an annotation was defined
+    if (parsingContext.rdfstar && parsingContext.annotationsBuffer[depth]) {
+      parsingContext.emitError(new ErrorCoded(`Found an illegal annotation inside a list`,
+        ERROR_CODES.INVALID_ANNOTATION));
+    }
   }
 
 }
diff --git a/lib/entryhandler/EntryHandlerPredicate.ts b/lib/entryhandler/EntryHandlerPredicate.ts
@@ -1,6 +1,6 @@
 import {ERROR_CODES, ErrorCoded} from "jsonld-context-parser";
 import * as RDF from "@rdfjs/types";
-import {ParsingContext} from "../ParsingContext";
+import { AnnotationsBufferEntry, ParsingContext } from "../ParsingContext";
 import {Util} from "../Util";
 import {IEntryHandler} from "./IEntryHandler";
 
@@ -21,17 +21,18 @@ export class EntryHandlerPredicate implements IEntryHandler<boolean> {
    * @param {Term} object The object.
    * @param {boolean} reverse If the property is reversed.
    * @param {boolean} isEmbedded If the property exists in an embedded node as direct child.
+   * @param {boolean} isAnnotation If the property exists in an annotation object.
    * @return {Promise<void>} A promise resolving when handling is done.
    */
   public static async handlePredicateObject(parsingContext: ParsingContext, util: Util, keys: any[], depth: number,
                                             predicate: RDF.Term, object: RDF.Term,
-                                            reverse: boolean, isEmbedded: boolean) {
+                                            reverse: boolean, isEmbedded: boolean, isAnnotation: boolean) {
     const depthProperties: number = await util.getPropertiesDepth(keys, depth);
     const depthOffsetGraph = await util.getDepthOffsetGraph(depth, keys);
     const depthPropertiesGraph: number = depth - depthOffsetGraph;
 
     const subjects = parsingContext.idStack[depthProperties];
-    if (subjects) {
+    if (subjects && !isAnnotation) {
       // Emit directly if the @id was already defined
       for (const subject of subjects) {
         // Check if we're in a @graph context
@@ -65,7 +66,44 @@ export class EntryHandlerPredicate implements IEntryHandler<boolean> {
       if (reverse) {
         util.validateReverseSubject(object);
       }
-      parsingContext.getUnidentifiedValueBufferSafe(depthProperties).push({predicate, object, reverse, isEmbedded});
+
+      // Either push to the annotations or the actual value buffer
+      if (isAnnotation) {
+        // Only add to buffer if rdfstar is enabled
+        if (parsingContext.rdfstar) {
+          // Error if an @id was defined
+          if (parsingContext.idStack[depth]) {
+            parsingContext.emitError(new ErrorCoded(`Found an illegal @id inside an annotation: ${parsingContext.idStack[depth][0].value}`,
+              ERROR_CODES.INVALID_ANNOTATION));
+          }
+
+          // Error if we're in an embedded node
+          for (let i = 0; i < depth; i++) {
+            if (await util.unaliasKeyword(keys[i], keys, i) === '@id') {
+              parsingContext.emitError(new ErrorCoded(`Found an illegal annotation inside an embedded node`,
+                ERROR_CODES.INVALID_ANNOTATION));
+            }
+          }
+
+          // Store new annotation in the buffer
+          const annotationsBuffer = parsingContext.getAnnotationsBufferSafe(depthProperties);
+          const newAnnotation: AnnotationsBufferEntry = { predicate, object, reverse, nestedAnnotations: [], depth: depthProperties };
+          annotationsBuffer.push(newAnnotation);
+
+          // Check in the buffer if any annotations were defined at a deeper depth,
+          // if so, they are considered nested annotations.
+          for (let i = annotationsBuffer.length - 2; i >= 0; i--) {
+            // We iterate in reverse order, to enable easy item removal from the back.
+            const existingAnnotation = annotationsBuffer[i];
+            if (existingAnnotation.depth > depthProperties) {
+              newAnnotation.nestedAnnotations.push(existingAnnotation);
+              annotationsBuffer.splice(i, 1);
+            }
+          }
+        }
+      } else {
+        parsingContext.getUnidentifiedValueBufferSafe(depthProperties).push({ predicate, object, reverse, isEmbedded });
+      }
     }
   }
 
@@ -108,15 +146,22 @@ export class EntryHandlerPredicate implements IEntryHandler<boolean> {
       const objects = await util.valueToTerm(context, key, value, depth, keys);
       if (objects.length) {
         for (let object of objects) {
+          // Based on parent key, check if reverse, embedded, and annotation.
           let parentKey = await util.unaliasKeywordParent(keys, depth);
           const reverse = Util.isPropertyReverse(context, keyOriginal, parentKey);
-          if (parentKey === '@reverse') {
-            // Check parent of parent when checking if we're in an embedded node if in @reverse
-            depth--;
-            parentKey = await util.unaliasKeywordParent(keys, depth);
+          let parentDepthOffset = 0;
+          while (parentKey === '@reverse' || typeof parentKey === 'number') {
+            // Check parent of parent when checking while we're in an array or in @reverse
+            if (typeof parentKey === 'number') {
+              parentDepthOffset++;
+            } else {
+              depth--;
+            }
+            parentKey = await util.unaliasKeywordParent(keys, depth - parentDepthOffset);
           }
           const isEmbedded = Util.isPropertyInEmbeddedNode(parentKey);
           util.validateReverseInEmbeddedNode(key, reverse, isEmbedded);
+          const isAnnotation = Util.isPropertyInAnnotationObject(parentKey);
 
           if (value) {
             // Special case if our term was defined as an @list, but does not occur in an array,
@@ -143,7 +188,7 @@ export class EntryHandlerPredicate implements IEntryHandler<boolean> {
           }
 
           await EntryHandlerPredicate.handlePredicateObject(parsingContext, util, keys, depth,
-            predicate, object, reverse, isEmbedded);
+            predicate, object, reverse, isEmbedded, isAnnotation);
         }
       }
     }
diff --git a/lib/entryhandler/keyword/EntryHandlerKeywordAnnotation.ts b/lib/entryhandler/keyword/EntryHandlerKeywordAnnotation.ts
@@ -0,0 +1,26 @@
+import {ParsingContext} from "../../ParsingContext";
+import {Util} from "../../Util";
+import {EntryHandlerKeyword} from "./EntryHandlerKeyword";
+import { ERROR_CODES, ErrorCoded } from '../../../../jsonld-context-flatten';
+
+/**
+ * Handles @annotation entries.
+ */
+export class EntryHandlerKeywordAnnotation extends EntryHandlerKeyword {
+
+  constructor() {
+    super('@annotation');
+  }
+
+  public async handle(parsingContext: ParsingContext, util: Util, key: any, keys: any[], value: any, depth: number)
+    : Promise<any> {
+    // Validate value
+    if (typeof value === 'string' || (typeof value === 'object' && value['@value'])) {
+      parsingContext.emitError(new ErrorCoded(`Found illegal annotation value: ${JSON.stringify(value)}`,
+        ERROR_CODES.INVALID_ANNOTATION));
+    }
+
+    // Rest of the processing is done as regular nodes
+  }
+
+}
diff --git a/lib/entryhandler/keyword/EntryHandlerKeywordId.ts b/lib/entryhandler/keyword/EntryHandlerKeywordId.ts
diff --git a/lib/entryhandler/keyword/EntryHandlerKeywordType.ts b/lib/entryhandler/keyword/EntryHandlerKeywordType.ts
diff --git a/test/JsonLdParser-test.ts b/test/JsonLdParser-test.ts

Original file line number	Diff line number	Diff line change
`@@ -69,7 +69,7 @@ export class ContainerHandlerIndex implements IContainerHandler {`
`69`	`69`	`// Otherwise, attach the index to the node identifier`
`70`	`70`	`for (const indexValue of indexValues) {`
`71`	`71`	`await EntryHandlerPredicate.handlePredicateObject(parsingContext, util, keys, depth + 1,`
`72`		`- indexProperty, indexValue, false, false);`
	`72`	`+ indexProperty, indexValue, false, false, false);`
`73`	`73`	`}`
`74`	`74`	`}`
`75`	`75`	`}`
Original file line number	Diff line number	Diff line change
`@@ -59,7 +59,7 @@ export class ContainerHandlerType implements IContainerHandler {`
`59`	`59`	`if (type) {`
`60`	`60`	`// Push the type to the stack using the rdf:type predicate`
`61`	`61`	`await EntryHandlerPredicate.handlePredicateObject(parsingContext, util, keys, depth + 1,`
`62`		`- util.rdfType, type, false, false);`
	`62`	`+ util.rdfType, type, false, false, false);`
`63`	`63`	`}`
`64`	`64`
`65`	`65`	`// Flush any pending flush buffers`
Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@ import * as RDF from "@rdfjs/types";`
`2`	`2`	`import {ParsingContext} from "../ParsingContext";`
`3`	`3`	`import {Util} from "../Util";`
`4`	`4`	`import {IEntryHandler} from "./IEntryHandler";`
	`5`	`+import { ERROR_CODES, ErrorCoded } from '../../../jsonld-context-flatten';`
`5`	`6`
`6`	`7`	`/**`
`7`	`8`	`* Handles values that are part of an array.`
`@@ -141,6 +142,12 @@ export class EntryHandlerArrayValue implements IEntryHandler<boolean> {`
`141`	`142`	`}`
`142`	`143`
`143`	`144`	`parsingContext.listPointerStack[depth] = listPointer;`
	`145`	`+`
	`146`	`+ // Error if an annotation was defined`
	`147`	`+ if (parsingContext.rdfstar && parsingContext.annotationsBuffer[depth]) {`
	`148`	+ parsingContext.emitError(new ErrorCoded(`Found an illegal annotation inside a list`,
	`149`	`+ ERROR_CODES.INVALID_ANNOTATION));`
	`150`	`+ }`
`144`	`151`	`}`
`145`	`152`
`146`	`153`	`}`