Author: fchrist
Date: Fri Jan 13 13:49:32 2012
New Revision: 1231066
URL: http://svn.apache.org/viewvc?rev=1231066&view=rev
Log:
STANBOL-456 Started to move FactStore specification from IKS Wiki
Added:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/specification.mdtext
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/index.mdtext
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/index.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/index.mdtext?rev=1231066&r1=1231065&r2=1231066&view=diff
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/index.mdtext
(original)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/index.mdtext
Fri Jan 13 13:49:32 2012
@@ -2,6 +2,8 @@ Title: Factstore
The FactStore is a component that let's use store relations between entities
identified by their URIs. A relation between two or more entities is called a
*fact*. The FactStore let's you store N-ary facts according to a user defined
fact schema. In consequence you can store relations between N participating
entities.
+Read on and have a look at a concrete example or go to the [FactStore
specification](specification.html) page for more details.
+
## Example
Imagine you want to store the fact that the person named John Doe works for
the company Winzigweich. John Doe is represented by the URI
http://www.doe.com/john and the company by http://www.winzigweich.de. This fact
is stored as a relation between the entity http://www.doe.com/john and
http://www.winzigweich.de.
Added:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/specification.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/specification.mdtext?rev=1231066&view=auto
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/specification.mdtext
(added)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/specification.mdtext
Fri Jan 13 13:49:32 2012
@@ -0,0 +1,329 @@
+Title: FactStore Specification
+
+The FactStore is designed to store semantic relations in terms of facts about
entities and their relationships. Additionally, the FactStore specifies a
simple SQL-like query language expressed in JSON-LD to search for semantic
relations and to reason through the use of joined relationships. This
specification defines required interfaces for the FactStore in terms of RESTful
API interfaces and a concept for a possible implementation.
+
+In the following, we will refer to semantic relationships as facts about
entities. For example, the relation âemplyeeOfâ may be a fact about two
entities one of type person and one of type organization. Facts are n-ary
meaning that the number of participating entities is not limited. The FactStore
implements a store for facts plus the ability to query for single facts and for
combinations of facts. In summary, the FactStore provides:
+
+- Persistence storage for n-ary facts about entities
+- Query language to query for a single fact
+- Query language to query for combinations of facts (reasoning)
+
+In the following, we will define the required interfaces for the FactStore
plus the required query language.
+
+''Note'': Interfaces will be defined as RESTful service APIs. The payload of
service calls is specified using [http://www.json-ld.org/spec/ED/20110507/
JSON-LD] (Specification version 20110507).
+
+''Note'': The FactStore does not provide any SPARQL endpoint so far. This
could be part of an extended version.
+
+## Store Interface ##
+
+The store interface allows clients to put new fact schemata and according
facts (instances of that schemata) to the FactStore.
+
+### Publish a New Fact Schema ###
+
+Allows clients to publish new fact schemata to the FactStore. Each fact is an
n-tuple where each element of that tuple defines a certain type of entity. A
fact schema defines which types of entities and their roles are part of
instances of that fact.
+
+Path: /factstore/facts/{fact-schema-name}
+
+Method: PUT with data type application/json returns HTTP 201 (created) on
success.
+
+Data: The fact schema is sent as the PUT payload in JSON-LD format as a
JSON-LD profile. The name of the fact is given by the URL. The elements of the
schema are defined in the "#types" section of the JSON-LD "#context". Each
element is specified using a unique role name for that entity plus the entity
type specified by an URN.
+
+Example 1: PUT /factstore/facts/http%3A%2F%2Fiks-project.eu%2Font%2FemployeeOf
with the following data
+
+ {
+ "@context" :
+ {
+ "iks" : "http://iks-project.eu/ont/";,
+ "#types" :
+ {
+ "person" : "iks:person",
+ "organization" : "iks:organization"
+ }
+ }
+ }
+
+will create the new fact schema for "employeeOf" at the given URL which is in
decoded representation: /factstore/facts/http://iks-project.eu/ont/employeeOf
+
+Instead one can use the cURL tool for this. Store the fact schema in a JSON
file and then use this command.
+
+ curl
http://localhost:8080/factstore/facts/http%3A%2F%2Fiks-project.eu%2Font%2FemployeeOf
-T spec-example1.json
+
+ |-
+ |valign="top"|Example 2: || PUT
/factstore/facts/http%3A%2F%2Fwww.schema.org%2FEvent.attendees<br>with the
following data
+
+ {
+ "@context" :
+ {
+ "sorg" : "http://www.schema.org/";,
+ "#types" :
+ {
+ "event" : "sorg:Event",
+ "attendee" : ["sorg:Person","sorg:Organization"]
+ }
+ }
+ }
+
+<nowiki>will create the new fact schema for "attendees" at the given URL which
is in decoded representation:
/factstore/facts/http://www.schema.org/Event.attendees.</nowiki>
+
+''Note'': <nowiki>That this fact schema uses the ability to define more than
one possible type for a role. The role 'attendee' can be of type
http://www.schema.org/Person or http://www.schema.org/Organization.</nowiki>
+|-
+|Status || Implemented in [http://incubator.apache.org/stanbol/ Apache Stanbol]
+|}
+
+==== Get Fact Schema ====
+
+{|
+ |valign="top"|Description: || Allows clients to get the definition of an
existing fact schema.
+ |-
+ |Path: || /factstore/facts/{fact-schema-name}
+ |-
+ |Method: || GET with data type application/json returns HTTP 200 on success.
+ |-
+ |valign="top"|Data: || The fact schema is returned as a JSON-LD profile.
+ |-
+ |valign="top"|Example: || GET
/factstore/facts/http%3A%2F%2Fiks-project.eu%2Font%2FemployeeOf<br>will return
the following data:
+
+ {
+ "@context" :
+ {
+ "#types" :
+ {
+ "person" : "http://iks-project.eu/ont/person";,
+ "organization" : "http://iks-project.eu/ont/organization";
+ }
+ }
+ }
+
+|-
+|Status || Implemented in [http://incubator.apache.org/stanbol/ Apache Stanbol]
+|}
+
+==== Publish New Facts ====
+{|
+ |valign="top"|Description:||Allows clients to publish a new facts according
to a defined fact schema that was previously published to the FactStore. Each
new fact is an n-tuple according to its schema where each tuple element
identifies an entity using its unique IRI.
+ |-
+ |Path:||/factstore/facts
+ |-
+ |Method:||POST with data type application/json returns HTTP 201 (created) on
success.
+ |-
+ |valign="top"|Data:||The facts are sent as the POST payload in JSON-LD format
referring to the defined JSON-LD profile. The name of the fact is given in the
"@profile" element of the JSON-LD object. The JSON-LD object contains a list of
facts under the attribute "facts" where each element of that list is an n-tuple
of entity instances according to fhe fact schema. The instance of an entity can
be specified either by its unique IRI or by specifying the instance by example.
+Using the instance by example variant requires the FactStore to resolve the
entity in an EntityHub. An entity by example is specified by defining
attributes and required values of the searched entity. A fact can only be
stored if all entities can be uniquely identified either by their IRI or by
example.
+ |-
+ |valign="top"|Example 1:||POST /factstore/facts<br>
+with the following data
+
+ {
+ "@context" : {
+ "iks" : "http://iks-project.eu/ont/";,
+ "upb" : "http://upb.de/persons/";
+ },
+ "@profile" : "iks:employeeOf",
+ "person" : { "@iri" : "upb:bnagel" },
+ "organization" : { "@iri" : "http://uni-paderborn.de"}
+ }
+
+<nowiki>creates a new fact of type http://iks-project.eu/ont/employeeof
specifying that the person http://upb.de/persons/bnagel is employee of the
organization defined by the IRI http://uni-paderborn.de.</nowiki>
+ |-
+ |valign="top"|Example 2:||POST /factstore/facts<br>
+with the following data to create several facts of the same type at once
+
+ {
+ "@context" : {
+ "iks" : "http://iks-project.eu/ont/";,
+ "upb" : "http://upb.de/persons/";
+ },
+ "@profile" : "iks:employeeOf",
+ "@" : [
+ { "person" : { "@iri" : "upb:bnagel" },
+ "organization" : { "@iri" : "http://uni-paderborn.de"; }
+ },
+ { "person" : { "@iri" : "upb:fchrist" },
+ "organization" : { "@iri" : "http://uni-paderborn.de"; }
+ }
+ ]
+ }
+
+<nowiki>creates two new facts of type http://iks-project.eu/ont/employeeof
specifying that the persons http://upb.de/persons/bnagel and
http://upb.de/persons/fchrist are employees of the organization defined by the
IRI http://uni-paderborn.de.</nowiki>
+ |-
+ |valign="top"|Example 3:||POST /factstore/facts<br>
+with the following data to create several facts of different type
+
+ {
+ "@context" : {
+ "iks" : "http://iks-project.eu/ont/";,
+ "upb" : "http://upb.de/persons/";
+ },
+ "@" : [
+ { "@profile" : "iks:employeeOf",
+ "person" : { "@iri" : "upb:bnagel" },
+ "organization" : { "@iri" : "http://uni-paderborn.de"; }
+ },
+ { "@profile" : "iks:friendOf",
+ "person" : { "@iri" : "upb:bnagel" },
+ "friend" : { "@iri" : "upb:fchrist" }
+ }
+ ]
+ }
+
+<nowiki>creates two new facts. The first one of type
http://iks-project.eu/ont/employeeof specifying that the person
http://upb.de/persons/bnagel is employee of the organization defined by the IRI
http://uni-paderborn.de. The second of type http://iks-project.eu/ont/friendOf
specifying that http://upb.de/persons/fchrist is a friend of
http://upb.de/persons/bnagel.</nowiki>
+ |-
+ |Status || Implemented in [http://incubator.apache.org/stanbol/ Apache
Stanbol]
+ |}
+
+=== Query Interface ===
+
+The query interface allows clients to query for facts and combination of facts
(reasoning). The JSON-LD query structure is inspired by SQL using SELECT FROM
[JOIN] WHERE constructs. Depending on the implementation the JSON-LD queries
may be transformed directly into valid SQL queries.
+
+==== Query for Facts of a Certain Type ====
+
+{|
+ |valign="top"|Description:||Allows clients to query stored facts of a
specific type defined by the fact's schema. The clients specify the desired
fact plus an arbitrary number of entities that play some role in the fact.
+ |-
+ |Path:||/factstore/query
+ |-
+ |Method:||POST with data type application/json returns application/json
+ |-
+ |valign="top"|Data:||The query is specified by a JSON-LD object in the
payload of the request. The query defines a "select" to specify the desired
type of result to be returned in the result set. The "from" part specifies the
fact type to query and the "where" clause specifies constraints to be
fulfilled.<br>
+Note:For the moment constraints only support the equals "=" relation. There
may be more relations like ">" in future versions of this specification. If
there is more than one constraint all constraints are concatenated by "AND".
+ |-
+ |valign="top"|Example 1:||POST /factstore/query<br>
+with the following data"
+
+ {
+ "@context" : {
+ "iks" : "http://iks-project.eu/ont/";
+ },
+ "select" : [ "person" ],
+ "from" : "iks:employeeOf",
+ "where" : [
+ {
+ "=" : {
+ "organization" : { "@iri" : "http://uni-paderborn.de"; }
+ }
+ }
+ ]
+ }
+
+<nowiki>returns the list of all persons participating in the fact of type
http://iks-project.eu/ont/employeeOf where the organization is
http://uni-paderborn.de. The result is sent back in JSON-LD format with the
result set specified by the select clause.</nowiki>
+
+ {
+ "@subject" : [
+ {
+ "@subject" : "_bnode1",
+ "PERSON" : "http://upb.de/persons/gengels";
+ },
+ {
+ "@subject" : "_bnode2",
+ "PERSON" : "http://upb.de/persons/ssauer";
+ },
+ {
+ "@subject" : "_bnode3",
+ "PERSON" : "http://upb.de/persons/bnagel";
+ },
+ {
+ "@subject" : "_bnode4",
+ "PERSON" : "http://upb.de/persons/fchrist";
+ }
+ ]
+ }
+
+<nowiki>If there is only one entry in the result set, this would be returned
as follows.</nowiki>
+
+ {
+ "PERSON" : "http://upb.de/persons/fchrist";
+ }
+ |-
+ |valign="top"| Status: || Example 1 is implemented and should work in latest
[http://incubator.apache.org/stanbol/ Apache Stanbol] versions.
+ |-
+ |valign="top"| Example 2: || GET /factstore/query?q=<br>
+with the following data as the request parameter "q"
+ {
+ "@context" : {
+ "iks" : "http://iks-project.eu/ont/";
+ },
+ "select" : [
+ "person.name", "person.email"
+ ],
+ "from" : "iks:employeeOf",
+ "where" : [
+ {
+ "=" : {
+ "organization" : { "@iri" : "http://upb.de"; }
+ }
+ }
+ ]
+ }
+
+<nowiki>returns a list with names and e-mail addresses of all persons
participating in the fact of type http://iks-project.eu/ont/employeeOf where
the organization is http://upb.de. The result is sent back in JSON-LD format
with the result set specified by the select clause.</nowiki>
+
+ {
+ "resultset": [
+ { "person.name" : "Gregor Engels",
+ "person.email": "[email protected]" },
+ { "person.name" : "Stefan Sauer",
+ "person.email": "[email protected]" },
+ { "person.name" : "Benjamin Nagel",
+ "person.email": "[email protected]" },
+ { "person.name" : "Fabian Christ",
+ "person.email": "[email protected]" }
+ ]
+ }
+ |-
+ |Status || Implemention in progress.
+ |}
+
+==== Query for Combinations of Facts ====
+{|
+ |Description:||Allows clients to query for combinations of facts.
+ |-
+ |Path:||/factstore/query?q=
+ |-
+ |Method:||GET with data type application/json returns application/json
+ |-
+ |Data:||The query is specified by a JSON-LD object in request parameter "q"
of the request. The query defines a "select" to specify the desired type of
result to be returned in the result set. Instead of using a "from" part this
type of query supports joins over facts using the "join" field. The "join"
field specifies which facts are joined by specifying the elements of the facts
that are evaluated to be equal during the join. The "where" clause specifies
constraints over the join to be fulfilled.<br>
+Note: For the moment constraints only support the equals "=" relation. There
may be more relations like ">" in future versions of this specification. If
there is more than one constraint all constraints are concatenated by "AND".
+ |-
+ |valign="top"|Example:||GET /factstore/query?q=<br>
+with the following request data in request parameter "q"
+
+ {
+ "@context" : {
+ "iks" : "http://iks-project.eu/ont/";
+ },
+ "select": [
+ "iks:friendOf.friend.name"
+ ],
+ "join" : {
+ "iks:employeeOf.person" : "iks:friendOf.person"
+ },
+ "where" : [
+ {
+ "=" : {
+ "iks:employeeOf.organization" : {
+ "@iri" : "http://upb.de";
+ }
+ }
+ },
+ {
+ "=" : {
+ "iks:friendOf.friend.city" : "Paderborn"
+ }
+ }
+ ]
+ }
+<nowiki>
+will return a list of names of all the friends living in Paderborn of the
employees of the University of Paderborn. The result in JSON-LD format would
look like the following.</nowiki>
+
+ {
+ "@context" : {
+ "iks" : "http://iks-project.eu/ont/";
+ },
+ "resultset": [
+ { "iks:friendOf.friend.name" : "Schmidt" },
+ { "iks:friendOf.friend.name" : "Meier" },
+ { "iks:friendOf.friend.name" : "Schneider" },
+ { "iks:friendOf.friend.name" : "Schuster" }
+ ]
+ }
+
+|}
