Merge branch 'feature/rdfstar'

Author: rubensworks

.github/workflows/ci.yml

@@ -22,7 +22,6 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         node-version:
-          - 12.x
           - 14.x
           - 16.x
           - 18.x
@@ -68,9 +67,9 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         node-version:
-          - 12.x
           - 14.x
           - 16.x
+          - 18.x
     steps:
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v3

README.md

@@ -162,6 +162,8 @@ Optionally, the following parameters can be set in the `JsonLdParser` constructo
 * `normalizeLanguageTags`: Whether or not language tags should be normalized to lowercase. _(Default: `false` for JSON-LD 1.1 (and higher), `true` for JSON-LD 1.0)_
 * `streamingProfileAllowOutOfOrderPlainType`: When the streaming profile flag is enabled, `@type` entries MUST come before other properties since they may defined a type-scoped context. However, when this flag is enabled, `@type` entries that do NOT define a type-scoped context may appear anywhere just like a regular property.. _(Default: `false`)_
 * `skipContextValidation`: If JSON-LD context validation should be skipped. This is useful when parsing large contexts that are known to be valid. _(Default: `false`)_
+* `rdfstar`: If embedded nodes and annotated objects should be parsed according to the [JSON-LD star specification](https://json-ld.github.io/json-ld-star/). _(Default: `true`)_
+* `rdfstarReverseInEmbedded`: If embedded nodes in JSON-LD star can have reverse properties. _(Default: `false`)_
 
 ```javascript
 new JsonLdParser({
@@ -179,6 +181,7 @@ new JsonLdParser({
   defaultGraph: namedNode('http://example.org/graph'),
   rdfDirection: 'i18n-datatype',
   normalizeLanguageTags: true,
+  rdfstar: true,
 });
 ```
 
@@ -239,8 +242,9 @@ Other documents will still be parsed correctly as well, with a slightly lower ef
 
 ## Streaming Profile
 
-This parser adheres to both the [JSON-LD 1.1](https://www.w3.org/TR/json-ld/) specification
-and the [JSON-LD 1.1 Streaming specification](https://w3c.github.io/json-ld-streaming/).
+This parser adheres to the [JSON-LD 1.1](https://www.w3.org/TR/json-ld/) specification,
+the [JSON-LD 1.1 Streaming](https://w3c.github.io/json-ld-streaming/) specification,
+and the [JSON-LD star](https://json-ld.github.io/json-ld-star/) specification.
 
 By default, this parser assumes that JSON-LD document
 are *not* in the [streaming document form](https://w3c.github.io/json-ld-streaming/#streaming-document-form).
@@ -261,6 +265,8 @@ This parser implements the following [JSON-LD specifications](https://json-ld.or
 * JSON-LD 1.1 - Transform JSON-LD to RDF
 * JSON-LD 1.1 - Error handling
 * JSON-LD 1.1 - Streaming Transform JSON-LD to RDF
+* [JSON-LD star](https://json-ld.github.io/json-ld-star/) - Transform JSON-LD star to RDF
+* [JSON-LD star](https://json-ld.github.io/json-ld-star/) - Error handling
 
 ## Performance
 

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?
   }
 
@@ -318,12 +321,13 @@ export class JsonLdParser extends Transform implements RDF.Sink<EventEmitter, RD
    */
   public async flushBuffer(depth: number, keys: any[]) {
     let subjects: RDF.Term[] = this.parsingContext.idStack[depth];
-    if (!subjects) {
+    const subjectsWasDefined = !!subjects;
+    if (!subjectsWasDefined) {
       subjects = this.parsingContext.idStack[depth] = [ this.util.dataFactory.blankNode() ];
     }
 
     // Flush values at this level
-    const valueBuffer: { predicate: RDF.Term, object: RDF.Term, reverse: boolean }[] =
+    const valueBuffer: { predicate: RDF.Term, object: RDF.Term, reverse: boolean, isEmbedded: boolean }[] =
       this.parsingContext.unidentifiedValuesBuffer[depth];
     if (valueBuffer) {
       for (const subject of subjects) {
@@ -336,13 +340,7 @@ export class JsonLdParser extends Transform implements RDF.Sink<EventEmitter, RD
             // Flush values to stream if the graph @id is known
             this.parsingContext.emittedStack[depth] = true;
             for (const bufferedValue of valueBuffer) {
-              if (bufferedValue.reverse) {
-                this.parsingContext.emitQuad(depth, this.util.dataFactory.quad(
-                  bufferedValue.object, bufferedValue.predicate, subject, graph));
-              } else {
-                this.parsingContext.emitQuad(depth, this.util.dataFactory.quad(
-                  subject, bufferedValue.predicate, bufferedValue.object, graph));
-              }
+              this.util.emitQuadChecked(depth, subject, bufferedValue.predicate, bufferedValue.object, graph, bufferedValue.reverse, bufferedValue.isEmbedded);
             }
           }
         } else {
@@ -355,12 +353,14 @@ export class JsonLdParser extends Transform implements RDF.Sink<EventEmitter, RD
                 object: subject,
                 predicate: bufferedValue.predicate,
                 subject: bufferedValue.object,
+                isEmbedded: bufferedValue.isEmbedded,
               });
             } else {
               subGraphBuffer.push({
                 object: bufferedValue.object,
                 predicate: bufferedValue.predicate,
                 subject,
+                isEmbedded: bufferedValue.isEmbedded,
               });
             }
           }
@@ -389,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];
+    }
   }
 
   /**
@@ -637,4 +654,14 @@ export interface IJsonLdParserOptions {
    * This is useful when parsing large contexts that are known to be valid.
    */
   skipContextValidation?: boolean;
+  /**
+   * If embedded nodes and annotated objects should be parsed according to the JSON-LD star specification.
+   * Defaults to true
+   */
+  rdfstar?: boolean;
+  /**
+   * If embedded nodes may use reverse properties
+   * Defaults to false.
+   */
+  rdfstarReverseInEmbedded?: boolean;
 }

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.
  */
@@ -36,6 +38,8 @@ export class ParsingContext {
   public readonly rdfDirection?: 'i18n-datatype' | 'compound-literal';
   public readonly normalizeLanguageTags?: boolean;
   public readonly streamingProfileAllowOutOfOrderPlainType?: boolean;
+  public readonly rdfstar: boolean;
+  public readonly rdfstarReverseInEmbedded?: boolean;
 
   // Stack of indicating if a depth has been touched.
   public readonly processingStack: boolean[];
@@ -63,10 +67,12 @@ export class ParsingContext {
   public readonly jsonLiteralStack: boolean[];
   // Triples that don't know their subject @id yet.
   // L0: stack depth; L1: values
-  public readonly unidentifiedValuesBuffer: { predicate: RDF.Term, object: RDF.Term, reverse: boolean }[][];
+  public readonly unidentifiedValuesBuffer: { predicate: RDF.Term, object: RDF.Term, reverse: boolean, isEmbedded: boolean }[][];
   // 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 }[][];
+  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[] }[];
@@ -92,6 +98,8 @@ export class ParsingContext {
     this.rdfDirection = options.rdfDirection;
     this.normalizeLanguageTags = options.normalizeLanguageTags;
     this.streamingProfileAllowOutOfOrderPlainType = options.streamingProfileAllowOutOfOrderPlainType;
+    this.rdfstar = options.rdfstar !== false;
+    this.rdfstarReverseInEmbedded = options.rdfstarReverseInEmbedded;
 
     this.topLevelProperties = false;
     this.activeProcessingMode = parseFloat(this.processingMode);
@@ -111,6 +119,7 @@ export class ParsingContext {
     this.jsonLiteralStack = [];
     this.unidentifiedValuesBuffer = [];
     this.unidentifiedGraphsBuffer = [];
+    this.annotationsBuffer = [];
 
     this.pendingContainerFlushBuffers = [];
 
@@ -342,7 +351,7 @@ export class ParsingContext {
    * @return {{predicate: Term; object: Term; reverse: boolean}[]} An element of
    *                                                               {@link ParsingContext.unidentifiedValuesBuffer}.
    */
-  public getUnidentifiedValueBufferSafe(depth: number): { predicate: RDF.Term, object: RDF.Term, reverse: boolean }[] {
+  public getUnidentifiedValueBufferSafe(depth: number): { predicate: RDF.Term, object: RDF.Term, reverse: boolean, isEmbedded: boolean }[] {
     let buffer = this.unidentifiedValuesBuffer[depth];
     if (!buffer) {
       buffer = [];
@@ -357,7 +366,7 @@ export class ParsingContext {
    * @return {{predicate: Term; object: Term; reverse: boolean}[]} An element of
    *                                                               {@link ParsingContext.unidentifiedGraphsBuffer}.
    */
-  public getUnidentifiedGraphBufferSafe(depth: number): { subject: RDF.Term, predicate: RDF.Term, object: RDF.Term }[] {
+  public getUnidentifiedGraphBufferSafe(depth: number): { subject: RDF.Term, predicate: RDF.Term, object: RDF.Term, isEmbedded: boolean }[] {
     let buffer = this.unidentifiedGraphsBuffer[depth];
     if (!buffer) {
       buffer = [];
@@ -366,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.
    */
@@ -406,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
   }