From 12c79589b7f5e5ef82f4b6d2ac2fc67caa05ae88 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Mon, 10 Sep 2018 16:48:05 -0700 Subject: [PATCH] WebIDL for `fromRdf` and `toRdf` algorithms. Defines new interfaces for RdfDataset, RdfGraph, RdfTriple, and RdfLiteral. Fixes #27. --- common/terms.html | 2 +- index.html | 305 ++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 253 insertions(+), 54 deletions(-) diff --git a/common/terms.html b/common/terms.html index 4fef7b6e..de63293d 100644 --- a/common/terms.html +++ b/common/terms.html @@ -182,7 +182,7 @@ as specified in the Data Model section of the JSON-LD specification [[JSON-LD11]]. A linked data graph is a generalized representation of an - RDF graph + RDF graph as defined in [[!RDF11-CONCEPTS]].
list
A list is an ordered sequence of IRIs, diff --git a/index.html b/index.html index 2e3828de..024a35b9 100644 --- a/index.html +++ b/index.html @@ -685,7 +685,7 @@

RDF Serialization/Deserialization

--> -

Using the Serialize RDF as JSON-LD algorithm +

Using the Serialize RDF as JSON-LD Algorithm a developer could transform this document into expanded JSON-LD:

RDF Serialization/Deserialization

The example above is the JSON-LD serialization of the output of the - Serialize RDF as JSON-LD algorithm, + Serialize RDF as JSON-LD Algorithm, where the algorithm's use of dictionaries are replaced with JSON objects.

Note that the output above could easily be compacted using the technique outlined in the previous section. It is also possible to deserialize the JSON-LD document back - to RDF using the Deserialize JSON-LD to RDF algorithm.

+ to RDF using the Deserialize JSON-LD to RDF Algorithm.

@@ -3788,7 +3788,7 @@

RDF Serialization/Deserialization Algorithms

implementations with random access to dictionary elements.

-

Deserialize JSON-LD to RDF algorithm

+

Deserialize JSON-LD to RDF Algorithm

This algorithm deserializes a JSON-LD document to an RDF dataset. Please note that RDF does not allow a blank node to be used @@ -3843,8 +3843,10 @@

Overview

Algorithm

-

The algorithm takes a JSON-LD document element and returns an - RDF dataset. Unless the produceGeneralizedRdf option +

The algorithm takes a dictionary node map, which + is the result of the Node Map Generation algorithm and + an RDF dataset dataset into which new graphs and triples are added. + Unless the produceGeneralizedRdf option is set to true, RDF triple containing a blank node predicate are excluded from output.

@@ -3858,18 +3860,19 @@

Algorithm

to 0.

    -
  1. Expand element according to the - Expansion algorithm.
    2. -
  2. Generate a node map according to the - Node Map Generation algorithm.
    3. -
  3. Initialize an empty RDF dataset dataset.
  4. For each graph name and graph in node map ordered by graph name:
    1. If graph name is not well-formed, continue with the next graph name-graph pair.
      2. -
    2. Initialize triples as an empty array.
      3. +
    3. If graph name is @default, set + set triples to the value of the defaultGraph + attribute of dataset. + Otherwise, initialize graph as an empty RdfGraph + and add to dataset using its + add method along with graph name + for graphName.
    4. For each subject and node in graph ordered by subject:
        @@ -3880,10 +3883,13 @@

        Algorithm

        ordered by property:
        1. If property is @type, then for each - type in values, append a triple - composed of subject, rdf:type, - and type to triples. - unless type is not well-formed.
          2. + type in values, + create a new RdfTriple + composed of subject, rdf:type for predicate, + and type for object + and add to triples + using its add method, + unless type is not well-formed.
        2. Otherwise, if property is a keyword continue with the next property-values pair.
        3. Otherwise, if property is a blank node identifier and @@ -3909,24 +3915,20 @@

          Algorithm

          null, indicating a non-well-formed RDF resource that has to be ignored.
          4. -
        4. Append all triples from - list triples to triples.
          5. +
        5. Add all RdfTriple instances from + list triples to triples using + its using its add method.
    5. -
  5. If graph name is @default, add - triples to the default graph in dataset.
    6. -
  6. Otherwise, create a named graph in dataset - composed of graph name and add triples.
-
  • Return dataset.
    • -
    +

    Object to RDF Conversion

    @@ -4076,7 +4078,7 @@

    Algorithm

    -
    +

    Serialize RDF as JSON-LD Algorithm

    This algorithm serializes an RDF dataset consisting of a @@ -4095,7 +4097,7 @@

    Overview

    and generating a JSON-LD document in expanded form for all RDF literals, IRIs and blank node identifiers. - If the use native types flag is set to true, + If the useNativeTypes flag is set to true, RDF literals with a datatype IRI that equals xsd:integer or xsd:double are converted @@ -4106,20 +4108,24 @@

    Overview

    lexical form as described in . - Unless the use rdf:type flag is set to true, rdf:type + Unless the useRdfType flag is set to true, rdf:type predicates will be serialized as @type as long as the associated object is either an IRI or blank node identifier.

    -
    +

    Algorithm

    The algorithm takes one required and three optional inputs: an RDF dataset dataset - and the three flags use native types, use rdf:type, + and the three flags useNativeTypes, useRdfType, and the ordered flag, used to order dictionary member keys lexicographically, where noted that all default to false.

    +

    The dataset is iterable to iterate over graphs and graph names + contained within the RdfDataset. Each graph is also iterable + for iterating over triples contained within the RdfGraph.

    +
    1. Initialize default graph to an empty dictionary.
    2. Initialize graph map to a dictionary consisting @@ -4155,7 +4161,7 @@

      Algorithm

      consisting of a single member @id whose value is set to object.
    3. If predicate equals rdf:type, the - use rdf:type flag is not true, and object + useRdfType flag is not true, and object is an IRI or blank node identifier, append object to the value of the @type member of node; unless such an item already exists. @@ -4165,7 +4171,7 @@

      Algorithm

      RDF triple.
    4. Set value to the result of using the RDF to Object Conversion algorithm, - passing object and use native types.
      5. + passing object and useNativeTypes.
    5. If node does not have an predicate member, create one and initialize its value to an empty array.
    6. If there is no item equivalent to value in the array @@ -4227,7 +4233,7 @@

      Algorithm

      and node has no other members apart from an optional @type member whose value is an array with a single item equal to rdf:List, - node represents a well-formed list node. + node represents a well-formed list node. Perform the following steps to traverse the list backwards towards its head:
      1. Append the only item of rdf:first member of @@ -4296,7 +4302,7 @@

        Overview

        value objects whereas IRIs and blank node identifiers are transformed to node objects. - If the use native types flag is set to true, + If the useNativeTypes flag is set to true, RDF literals with a datatype IRI that equals xsd:integer or xsd:double are converted @@ -4313,7 +4319,7 @@

        Overview

        Algorithm

        This algorithm takes two required inputs: a value to be converted - to a dictionary and a flag use native types.

        + to a dictionary and a flag useNativeTypes.

        1. If value is an IRI or a @@ -4326,7 +4332,7 @@

          Algorithm

        2. Initialize a new empty dictionary result.
        3. Initialize converted value to value.
        4. Initialize type to null
          5. -
        5. If use native types is true +
        6. If useNativeTypes is true
          1. If the datatype IRI @@ -4370,7 +4376,7 @@

            Algorithm

    -
    +

    Data Round Tripping

    @@ -4453,13 +4459,13 @@

    Data Round Tripping

    space.

    To ensure lossless round-tripping the - Serialize RDF as JSON-LD algorithm - specifies a use native types flag which controls whether + Serialize RDF as JSON-LD Algorithm + specifies a useNativeTypes flag which controls whether RDF literals with a datatype IRI equal to xsd:integer, xsd:double, or xsd:boolean are converted to their JSON-native - counterparts. If the use native types flag is set to + counterparts. If the useNativeTypes flag is set to false, all literals remain in their original string representation.

    @@ -4473,7 +4479,6 @@

    Data Round Tripping

    -

    The Application Programming Interface

    @@ -4508,7 +4513,6 @@

    The JsonLdProcessor Interface

    in this document mention this directly.

    -      [Constructor]
       interface JsonLdProcessor {
         static Promise<JsonLdDictionary> compact(
           JsonLdInput input,
@@ -4521,11 +4525,17 @@ 
    The JsonLdProcessor Interface
    
           JsonLdInput input,
           optional JsonLdContext? context,
           optional JsonLdOptions? options);
+        static Promise<sequence<JsonLdDictionary>> fromRdf(
+          RdfDataset input,
+          optional JsonLdOptions? options);
+        static Promise<RdfDataset> toRdf(
+          JsonLdInput input,
+          optional JsonLdOptions? options);
       };
    -
    compact
    +
    compact

    Compacts the given input using the context according to the steps in the @@ -4636,7 +4646,7 @@

    The JsonLdProcessor Interface

    The dictionary or array of dictionaries to perform the expansion upon or an IRI referencing the JSON-LD document to expand.
    options
    -
    A set of options to configure the used algorithms such. This allows, e.g., +
    A set of options to configure the used algorithms. This allows, e.g., to set the input document's base IRI.
    @@ -4653,7 +4663,7 @@

    The JsonLdProcessor Interface

  • Set expanded input to the result of using the expand method using input and options - with ordered set to false. + with ordered set to false.
  • If context is a dictionary having an @context member, set context to that member's value, otherwise to context.
  • Initialize an active context using context; @@ -4664,9 +4674,7 @@

    The JsonLdProcessor Interface

    compactToRelative option is true, to the IRI of the currently being processed document, if available; otherwise to null.
    • -
  • Initialize an empty identifier map and a counter (set to 0) - to be used by the - Generate Blank Node Identifier algorithm.
    • +
  • Initialize an empty identifier map.
  • Set flattened output to the result of using the Flattening algorithm, passing expanded input as element, active context, and if passed, the @@ -4690,7 +4698,80 @@

    The JsonLdProcessor Interface

    passed or null is passed, the result will not be compacted but kept in expanded form.
    options
    -
    A set of options to configure the used algorithms such. This allows, e.g., +
    A set of options to configure the used algorithms. This allows, e.g., + to set the input document's base IRI.
    + + + +
    fromRdf
    +
    +

    Transforms the given input into + a JSON-LD document in expanded form + according to the steps in the Serialize RDF as JSON-LD Algorithm:

    + +

    This interface does not define a means of creating + an RdfDataset from an arbitrary input, other than the + toRdf method.

    + +
      +
    1. Create a new Promise promise and return it. The + following steps are then executed asynchronously.
      2. +
    2. Set expanded result to the result of invoking the + Serialize RDF as JSON-LD Algorithm + method using dataset + and options.
      3. +
    3. Create a new RdfDataset dataset.
      4. +
    4. Create a new dictionary node map.
      5. +
    5. Invoke the + Node Map Generation algorithm, passing + expanded input as element and node map.
      6. +
    6. Invoke the + Deserialize JSON-LD to RDF Algorithm
      7. + passing node map, dataset, and if passed, the + produceGeneralizedRdf flag in options +
    7. Fulfill the promise passing dataset.
      8. +
    + +
    +
    input
    +
    The dictionary or array of dictionaries or an IRI + referencing the JSON-LD document to flatten.
    +
    options
    +
    A set of options to configure the used algorithms. This allows, e.g., + to set the input document's base IRI.
    +
    +
    + +
    toRdf
    +
    +

    Transforms the given input into an RdfDataset + according to the steps in the Deserialize JSON-LD to RDF Algorithm:

    + +
      +
    1. Create a new Promise promise and return it. The + following steps are then executed asynchronously.
      2. +
    2. Set expanded input to the result of using the + expand + method using input + and options.
      3. +
    3. Create a new RdfDataset dataset.
      4. +
    4. Create a new dictionary node map.
      5. +
    5. Invoke the + Node Map Generation algorithm, passing + expanded input as element and node map.
      6. +
    6. Invoke the + Deserialize JSON-LD to RDF Algorithm
      7. + passing node map, dataset, and if passed, the + produceGeneralizedRdf flag in options +
    7. Fulfill the promise passing dataset.
      8. +
    + +
    +
    input
    +
    The dictionary or array of dictionaries or an IRI + referencing the JSON-LD document to flatten.
    +
    options
    +
    A set of options to configure the used algorithms. This allows, e.g., to set the input document's base IRI.
    @@ -4712,14 +4793,123 @@

    The JsonLdProcessor Interface

    IRI which an be dereferenced to retrieve a valid JSON document.

    The JsonLdContext type is used to refer to a value that that may be a dictionary, a string representing an IRI, or an array of dictionaries and strings.

    - + + +
    +

    RDF Dataset Interfaces

    + +

    The RdfDataset interface describes operations on an RDF dataset used by the fromRdf and toRdf methods in the JsonLdProcessor interface. The interface may be used for constructing a new RDF dataset, which has a default graph accessible via the defaultGraph attribute.

    + + 
    +      [Constructor]
+      interface RdfDataset {
+        readonly attribute RdfGraph defaultGraph;
+        void add(USVString graphName, RdfGraph graph);
+        iterable<USVString?, RdfGraph>;
+      };
+
    + +
    +
    defaultGraph
    +
    Provides access to the default graph associated with the RDF dataset.
    +
    add
    +
    +

    Adds an RdfGraph and its associated graph name to the RdfDataset. Used by the Deserialize JSON-LD to RDF Algorithm.

    + +
    +
    graphName
    +
    The graph name associated with graph. + graphName MUST be a well-formed IRI or blank node identifier. +
    +
    graph
    +
    The RdfGraph to add to the RdfDataset.
    +
    +
    +
    iterable
    +
    The value pairs to iterate over + are the list of graph name-graph pairs, with the + graph name being null (for the default + graph), an IRI or blank node identifier and graph an + RdfGraph instance.
    +
    + +

    The RdfGraph interface describes operations on an RDF graph used by the fromRdf and toRdf methods in the JsonLdProcessor interface. The interface may be used for constructing a new RDF graph, which is composed of zero or more RdfTriple instances.

    + + 
    +      [Constructor]
+      interface RdfGraph {
+        void add(RdfTriple triple);
+        iterable<RdfTriple>;
+      };
+
    + +
    +
    add
    +
    +

    Adds an RdfTriple to the RdfGraph. Used by the Deserialize JSON-LD to RDF Algorithm.

    + +
    +
    triple
    +
    The RdfTriple to add to the RdfGraph.
    +
    +
    +
    iterable
    +
    A value iterator + over the RdfTriple instances associated with the graph. + Note that a given RdfTriple instance may appear + in more than one graph within a particular RdfDataset instance.
    +
    + +

    The RdfTriple interface describes an RDF Triple.

    + + 
    +      [Constructor]
+      interface RdfTriple {
+        readonly attribute USVString subject;
+        readonly attribute USVString predicate;
+        readonly attribute (USVString or RdfLiteral) object;
+      };
+
    + +
    +
    subject
    +
    An absolute IRI or blank node identifier denoting the subject of the triple.
    +
    predicate
    +
    An absolute IRI denoting the predicate of the triple. + If used to represent a Generalized RDF Dataset, it may also be a blank node identifier.
    +
    object
    +
    An absolute IRI, blank node identifier or literal denoting the object of the triple.
    +
    + +

    The RdfLiteral interface describes an RDF Literal.

    + + 
    +      [Constructor]
+      interface RdfLiteral {
+        readonly attribute USVString value;
+        readonly attribute USVString datatype;
+        readonly attribute USVString? language;
+      };
+
    + +
    +
    value
    +
    The lexical value of the literal.
    +
    datatype
    +
    An absolute IRI denoting the datatype IRI of the literal. + If the value is rdf:langString, language MUST be specified.
    +
    language
    +
    An optional language tag as defined by [[!BCP47]]. If this value is specified, + datatype MUST be rdf:langString
    +
    +

    The JsonLdOptions Type

    @@ -4738,6 +4928,8 @@

    The JsonLdOptions Type

    boolean ordered = false; USVString processingMode = null; boolean produceGeneralizedRdf = true; + boolean useNativeTypes = false; + boolean useRdfType = false; }; --> @@ -4758,7 +4950,9 @@

    The JsonLdOptions Type

    A context that is used to initialize the active context when expanding a document.
    produceGeneralizedRdf
    If set to true, the JSON-LD processor may emit blank nodes for - triple predicates, otherwise they will be omitted.
    + triple predicates, otherwise they will be omitted. + Generalized RDF Datasets + are defined in [[!RDF11-CONCEPTS]].
    processingMode
    Sets the processing mode. If set to json-ld-1.0 or json-ld-1.1, the @@ -4777,6 +4971,11 @@

    The JsonLdOptions Type

    base option or document location when compacting.
    frameExpansion
    Enables special frame processing rules for the Expansion Algorithm.
    +
    Enables special rules for the Serialize RDF as JSON-LD Algorithm + to use JSON-LD native types as values, where possible.
    +
    useRdfType
    +
    Enables special rules for the Serialize RDF as JSON-LD Algorithm + causing rdf:type properties to be kept as IRIs in the output, rather than use @type.
    ordered
    If set to true, certain algorithm processing steps where indicated are ordered lexicographically. @@ -5130,7 +5329,7 @@

    Changes since 1.0 Recommendation of 16 January 2014

    members of node objects, are expanded or compacted relative to the base IRI using string concatenation.
  • Lists may now have members which are themselves lists.
    • -
  • The Deserialize JSON-LD to RDF algorithm +
  • The Deserialize JSON-LD to RDF Algorithm has been updated to ensure that only well-formed triples are emitted; previously, it only ensured that triples containing relative IRIs were excluded.
    • @@ -5146,7 +5345,7 @@

    Changes since 1.0 Recommendation of 16 January 2014

    Changes since JSON-LD Community Group Final Report