From 264c6bead90d077ffebe5795796d7bd0fb86d873 Mon Sep 17 00:00:00 2001 From: bergi Date: Fri, 7 Jul 2017 11:44:30 +0200 Subject: [PATCH 1/4] initial HTML respec version --- interface-spec.html | 491 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 491 insertions(+) create mode 100644 interface-spec.html diff --git a/interface-spec.html b/interface-spec.html new file mode 100644 index 0000000..28e2238 --- /dev/null +++ b/interface-spec.html @@ -0,0 +1,491 @@ + + + + + Interface Specification: RDF Representation + + + + +
+

+

+
+ +
+

+ This document provides a specification of a low level interface definition representing RDF data + independent of a serialized format in a JavaScript environment. The task force which defines + this interface was formed by RDF JavaScript library developers with the wish to make existing + and future libraries interoperable. This definition strives to provide the minimal necessary + interface to enable interoperability of libraries such as serializers, parsers and higher level + accessors and manipulators. +

+
+ +
+

Design elements and principles

+ + + +

+ A list of these properties maintained on the + + RDFJS Representation Task Force wiki + . +

+
+ +
+

Data interfaces

+ + UML data interface diagram + + +
+

Term interface

+ + 
+    interface Term {
+      attribute string termType;
+      attribute string value;
+      boolean equals(Term other);
+    };
+
+ +

+ Term is an abstract interface. +

+

+ termType contains a value that identifies the concrete interface of the term, since + Term itself is not directly instantiated. Possible values include "NamedNode", + "BlankNode", "Literal", "Variable" and + "DefaultGraph". +

+

+ value is refined by each interface which extends Term. +

+

+ equals() returns true if and only if other has the same + termType and the same contents (as defined by concrete subclasses). +

+
+ +
+

NamedNode interface

+ + 
+    interface NamedNode : Term {
+      attribute string termType;
+      attribute string value;
+      boolean equals(Term other);
+    };
+
+ +

+ termType contains the constant "NamedNode". +

+

+ value the IRI of the named node (example: "http://example.org/resource"). +

+

+ equals() returns true if and only if other has + termType "NamedNode" and the same value. +

+
+ +
+

BlankNode interface

+ + 
+    interface BlankNode : Term {
+      attribute string termType;
+      attribute string value;
+      boolean equals(Term other);
+    };
+
+ +

+ termType contains the constant "BlankNode". +

+

+ value blank node name as a string, without any serialization specific prefixes, + e.g. when parsing, if the data was sourced from Turtle, remove "_:", if it was + sourced from RDF/XML, do not change the blank node name (example: "blank3") +

+

+ equals() returns true if and only if other has + termType "BlankNode" and the same value. +

+
+ +
+

Literal interface

+ + 
+    interface Literal : Term {
+      attribute string termType;
+      attribute string value;
+      attribute string language;
+      attribute NamedNode datatype;
+      boolean equals(Term other);
+    };
+
+ +

+ termType contains the constant "Literal". +

+

+ value the text value, unescaped, without language or type (example: + "Brad Pitt") +

+

+ language the language as lowercase BCP-47 [[!BCP47]] string (examples: + "en", "en-gb") or an empty string if the literal has no language. +

+

+ datatype a NamedNode whose IRI represents the datatype of the literal. +

+

+ If the literal has a language, its datatype has the IRI + "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString". Otherwise, if no + datatype is explicitly specified, the datatype has the IRI + "http://www.w3.org/2001/XMLSchema#string". +

+

+ equals() returns true if and only if other has + termType "Literal" and the same value, + language, and datatype. +

+
+ +
+

Variable interface

+ + 
+    interface Variable : Term {
+      attribute string termType;
+      attribute string value;
+      boolean equals(Term other);
+    };
+
+ +

+ termType contains the constant "Variable". +

+

+ value the name of the variable without leading "?" (example: + "a"). +

+

+ equals() returns true if and only if other has + termType "Variable" and the same value. +

+
+ +
+

DefaultGraph interface

+ + 
+    interface DefaultGraph : Term {
+      attribute string termType;
+      attribute string value;
+      boolean equals(Term other);
+    };
+
+ +

+ An instance of DefaultGraph represents the default graph. It's only allowed to + assign a DefaultGraph to the graph property of a Quad. +

+

+ termType contains the constant "DefaultGraph". +

+

+ value contains an empty string as constant value. +

+

+ equals() returns true if and only if other has + termType "DefaultGraph". +

+
+ +
+

Triple interface

+ + 
+    interface Triple {};
+
+    Triple implements Quad;
+
+ +

+ Triple is an alias of Quad. +

+
+ +
+

Quad interface

+ + 
+    interface Quad {
+      attribute Term subject;
+      attribute Term predicate;
+      attribute Term object;
+      attribute Term graph;
+      boolean equals(Quad other);
+    };
+
+ +

+ subject the subject, which is a NamedNode, BlankNode or + Variable. +

+

+ predicate the predicate, which is a NamedNode or + Variable. +

+

+ object the object, which is a NamedNode, Literal, + BlankNode or Variable. +

+

+ graph the named graph, which is a DefaultGraph, + NamedNode, BlankNode or Variable. +

+

+ equals() returns true if and only if the argument is a) of the same + type b) has all components equal. +

+
+ +
+

DataFactory interface

+ + 
+    interface DataFactory {
+      NamedNode namedNode(string value);
+      BlankNode blankNode(optional string value);
+      Literal literal(string value, optional (string or NamedNode) languageOrDatatype);
+      Variable variable(string value);
+      DefaultGraph defaultGraph();
+      Quad triple(Term subject, Term predicate, Term object);
+      Quad quad(Term subject, Term predicate, Term object, optional Term graph);
+    };
+
+ +

+ For default values of the instance properties and valid values requirements, + see the individual interface definitions. +

+

+ namedNode() returns a new instance of NamedNode. +

+

+ blankNode() returns a new instance of BlankNode. If the value + parameter is undefined a new identifier for the blank node is generated for each call. +

+

+ literal() returns a new instance of Literal. If + languageOrDatatype is a NamedNode, then it is used for the value of + datatype. Otherwise languageOrDatatype is used for the value of + language. +

+

+ variable() returns a new instance of Variable. This method is + optional. +

+

+ defaultGraph() returns an instance of DefaultGraph. +

+

+ triple() returns a new instance of Quad with graph set to + DefaultGraph. +

+

+ quad()returns a new instance of Quad. +

+
+
+ +
+

Stream interfaces

+

+ Streams are used only in a readable manner. This requires only a single queue per stream, which + simplifies implementations and doesn't have performance drawbacks, compared to writeable + streams. +

+ + UML data interface diagram + +
+

Stream interface

+ + 
+    interface Stream : EventEmitter {
+      Quad read();
+      attribute Event readable;
+      attribute Event end;
+      attribute Event error;
+      attribute Event data;
+      attribute Event prefix;
+    };
+
+ +

+ read() This method pulls a quad out of the internal buffer and returns it. If there + is no quad available, then it will return null. +

+

+ readable When a quad can be read from the stream, it will emit this event. +

+

+ end This event fires when there will be no more quads to read. +

+

+ error `error(Error error)` This event fires if any error occurs. The `message` describes the error. +

+

+ data `data(Quad quad)` This event is emitted for every quad that can be read from the stream. The `quad` is the content of the data. +

+

Optional Events

+

+ These events are not required, but if an implementation wishes to support such events, they should conform to these definitions: +

+

+ prefix `prefix(string prefix, NamedNode iri)` This event is emitted every time a prefix is mapped to some IRI. +

+
+ +
+

Source interface

+ + 
+    interface Source {
+      Stream match(optional (Term or RegExp) subject, optional (Term or RegExp) predicate, optional (Term or RegExp) object, optional (Term or RegExp) graph);
+    };
+
+ +

+ A Source is an object that emits quads. It can contain quads but also generate them on the + fly. For example, parsers and transformations which generate quads can implement the Source + interface. +

+

+ match() Returns a stream that processes all quads matching the pattern. +

+
+ +
+

Sink interface

+ + 
+    interface Sink {
+      EventEmitter import(Stream stream);
+    };
+
+ +

+ A Sink is an object that consumes data from different kinds of streams. It can store the + content of the stream or do some further processing. For example parsers, serializers, + transformations and stores can implement the Sink interface. +

+

+ import() Consumes the given stream. The end and error + events are used like described in the Stream interface. Depending on the use + case, subtypes of EventEmitter or Stream are used. +

+

Typical use cases

+
    +
  • Parser:
    Stream<Quad> import(Stream stream)
    • +
  • Serializer
    Stream import(Stream<Quad> stream)
    • +
  • Transformation
    Stream<Quad> import(Stream<Quad> stream)
    • +
  • Store
    EventEmitter .import(Stream<Quad> stream)
    • +
+
+ +
+

Store interface

+ + 
+    interface Store {
+      EventEmitter remove(Stream stream);
+      EventEmitter removeMatches(optional (Term or RegExp) subject, optional (Term or RegExp) predicate, optional (Term or RegExp) object, optional (Term or RegExp) graph);
+      EventEmitter deleteGraph((Term or string) graph);
+    };
+
+    Store implements Source;
+    Store implements Sink;
+
+ +

+ A Store is an object that usually used to persist quads. The interface allows removing quads, + beside read and write access. The quads can be stored locally or remotely. Access to stores + LDP or SPARQL endpoints can be implemented with a Store inteface. +

+

+ remove() Removes all streamed quads. The end and error + events are used like described in the Stream interface. +

+

+ removeMatches() All quads matching the pattern will be removed. The + end and error events are used like described in the + Stream interface. +

+

+ deleteGraph() Deletes the given named graph. The end and + error events are used like described in the Stream interface. +

+
+
+ + From c4b07702ec281d0ad7d7806c410b19a5c34e3982 Mon Sep 17 00:00:00 2001 From: Thomas Bergwinkl Date: Mon, 10 Jul 2017 16:13:28 +0200 Subject: [PATCH 2/4] replaced PNG images with SVGs --- interface-spec.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/interface-spec.html b/interface-spec.html index 28e2238..013376d 100644 --- a/interface-spec.html +++ b/interface-spec.html @@ -88,7 +88,7 @@

Design elements and principles

Data interfaces

- UML data interface diagram + UML data interface diagram
@@ -365,7 +365,7 @@

Stream interfaces

streams.

- UML data interface diagram + UML data interface diagram

Stream interface

From b50c1e2c72f1dff35b05980d240eca2204c64fbf Mon Sep 17 00:00:00 2001 From: bergi Date: Mon, 17 Jul 2017 23:37:46 +0200 Subject: [PATCH 3/4] added editors and authors --- interface-spec.html | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/interface-spec.html b/interface-spec.html index 013376d..c8ec626 100644 --- a/interface-spec.html +++ b/interface-spec.html @@ -19,8 +19,26 @@ url: "https://www.bergnet.org/people/bergi/card#me", company: "Zazuko", companyURL: "http://zazuko.com/" + }, { + name: "Ruben Verborgh", + url: "https://ruben.verborgh.org/", + company: "Ghent University – imec", + companyURL: "http://idlab.ugent.be/" + }], + authors: [{ + name: "Michael Luggen", + url: "http://oiu.ch", + company: "Bern University of Applied Sciences", + companyURL: "http://www.bfh.ch" + }, { + name: "Blake Regalia", + company: "STKO Lab @ UCSB", + companyURL: "http://stko.geog.ucsb.edu/" + }, { + name: "Piero Savastano", + url: "http://pieroit.org", + company: "Freelance Data Scientist" }], - authors: [], bugTracker: { open: "https://github.com/rdfjs/representation-task-force/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20", new: "https://github.com/rdfjs/representation-task-force/issues/new" From 670ec89048acb2e2917a409461e5c6236db4a747 Mon Sep 17 00:00:00 2001 From: bergi Date: Thu, 20 Jul 2017 11:55:06 +0200 Subject: [PATCH 4/4] copied editors to authors, added elf Pavlik --- interface-spec.html | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/interface-spec.html b/interface-spec.html index c8ec626..8834b9a 100644 --- a/interface-spec.html +++ b/interface-spec.html @@ -26,10 +26,18 @@ companyURL: "http://idlab.ugent.be/" }], authors: [{ + name: "Thomas Bergwinkl", + url: "https://www.bergnet.org/people/bergi/card#me", + company: "Zazuko", + companyURL: "http://zazuko.com/" + }, { name: "Michael Luggen", url: "http://oiu.ch", company: "Bern University of Applied Sciences", companyURL: "http://www.bfh.ch" + }, { + name: "elf Pavlik", + url: "https://elf-pavlik.hackers4peace.net/" }, { name: "Blake Regalia", company: "STKO Lab @ UCSB", @@ -38,6 +46,11 @@ name: "Piero Savastano", url: "http://pieroit.org", company: "Freelance Data Scientist" + }, { + name: "Ruben Verborgh", + url: "https://ruben.verborgh.org/", + company: "Ghent University – imec", + companyURL: "http://idlab.ugent.be/" }], bugTracker: { open: "https://github.com/rdfjs/representation-task-force/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20",