Author: buildbot
Date: Fri Jan 13 13:49:39 2012
New Revision: 802542
Log:
Staging update by buildbot for stanbol
Added:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/factstore/specification.html
Modified:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/factstore/index.html
Modified:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/factstore/index.html
==============================================================================
---
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/factstore/index.html
(original)
+++
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/factstore/index.html
Fri Jan 13 13:49:39 2012
@@ -52,6 +52,7 @@
<div id="content">
<h1 class="title">Factstore</h1>
<p>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 <em>fact</em>. 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.</p>
+<p>Read on and have a look at a concrete example or go to the <a
href="specification.html">FactStore specification</a> page for more details.</p>
<h2 id="example">Example</h2>
<p>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.</p>
<p>For this, we first need to create a so called fact schema that tells the
FactStore what we would like to store. A fact schema has a unique name (often
an URI is used) to identify it. To specify what kinds of entities we would like
to store, we specify the type of the entities. Each type has an URI and should
be defined by some ontology. For example, we can use the ontology specified by
http://schema.org/.</p>
Added:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/factstore/specification.html
==============================================================================
---
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/factstore/specification.html
(added)
+++
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/factstore/specification.html
Fri Jan 13 13:49:39 2012
@@ -0,0 +1,353 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+ <title>Apache Stanbol - FactStore Specification</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png"
href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+</head>
+
+<body>
+ <div id="navigation">
+ <img alt="Apache Stanbol" width="220" height="101"
src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/>
+ <h1 id="stanbol_links">Stanbol links</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Tutorial</a></li>
+<li><a href="/stanbol/docs/trunk/downloads.html">Downloads</a></li>
+<li><a href="/stanbol/docs/trunk/building.html">Building from Source</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a></li>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL";>Issue
Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org";>Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html";>Become a
Sponsor</a></li>
+<li><a href="http://www.apache.org/security/";>Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">FactStore Specification</h1>
+ <p>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.</p>
+<p>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:</p>
+<ul>
+<li>Persistence storage for n-ary facts about entities</li>
+<li>Query language to query for a single fact</li>
+<li>Query language to query for combinations of facts (reasoning)</li>
+</ul>
+<p>In the following, we will define the required interfaces for the FactStore
plus the required query language.</p>
+<p>''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).</p>
+<p>''Note'': The FactStore does not provide any SPARQL endpoint so far. This
could be part of an extended version.</p>
+<h2 id="store_interface">Store Interface</h2>
+<p>The store interface allows clients to put new fact schemata and according
facts (instances of that schemata) to the FactStore.</p>
+<h3 id="publish_a_new_fact_schema">Publish a New Fact Schema</h3>
+<p>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.</p>
+<p>Path: /factstore/facts/{fact-schema-name}</p>
+<p>Method: PUT with data type application/json returns HTTP 201 (created) on
success.</p>
+<p>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.</p>
+<p>Example 1: PUT
/factstore/facts/http%3A%2F%2Fiks-project.eu%2Font%2FemployeeOf with the
following data</p>
+<div class="codehilite"><pre><span class="p">{</span>
+ <span class="s">"@context"</span> <span class="p">:</span>
+ <span class="p">{</span>
+ <span class="s">"iks"</span> <span class="p">:</span> <span
class="s">"http://iks-project.eu/ont/"</span><span class="p">,</span>
+ <span class="s">"#types"</span> <span class="p">:</span>
+ <span class="p">{</span>
+ <span class="s">"person"</span> <span class="p">:</span>
<span class="s">"iks:person"</span><span class="p">,</span>
+ <span class="s">"organization"</span> <span class="p">:</span>
<span class="s">"iks:organization"</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>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</p>
+<p>Instead one can use the cURL tool for this. Store the fact schema in a JSON
file and then use this command.</p>
+<p>curl
http://localhost:8080/factstore/facts/http%3A%2F%2Fiks-project.eu%2Font%2FemployeeOf
-T spec-example1.json</p>
+<p>|-
+ |valign="top"|Example 2: || PUT
/factstore/facts/http%3A%2F%2Fwww.schema.org%2FEvent.attendees<br>with the
following data</p>
+<p>{
+ "@context" :
+ {
+ "sorg" : "http://www.schema.org/";,
+ "#types" :
+ {
+ "event" : "sorg:Event",
+ "attendee" : ["sorg:Person","sorg:Organization"]
+ }
+ }
+ }</p>
+<p><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></p>
+<p>''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]
+|}</p>
+<p>==== Get Fact Schema ====</p>
+<p>{|
+ |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:</p>
+<p>{
+ "@context" :
+ {
+ "#types" :
+ {
+ "person" : "http://iks-project.eu/ont/person";,
+ "organization" : "http://iks-project.eu/ont/organization";
+ }
+ }
+ }</p>
+<p>|-
+|Status || Implemented in [http://incubator.apache.org/stanbol/ Apache Stanbol]
+|}</p>
+<p>==== 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</p>
+<p>{
+ "@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"}
+ }</p>
+<p><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</p>
+<p>{
+ "@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"; }
+ }
+ ]
+ }</p>
+<p><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</p>
+<p>{
+ "@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" }
+ }
+ ]
+ }</p>
+<p><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]
+ |}</p>
+<p>=== Query Interface ===</p>
+<p>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.</p>
+<p>==== Query for Facts of a Certain Type ====</p>
+<p>{|
+ |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"</p>
+<p>{
+ "@context" : {
+ "iks" : "http://iks-project.eu/ont/";
+ },
+ "select" : [ "person" ],
+ "from" : "iks:employeeOf",
+ "where" : [
+ {
+ "=" : {
+ "organization" : { "@iri" : "http://uni-paderborn.de"; }
+ }
+ }
+ ]
+ }</p>
+<p><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></p>
+<p>{
+ "@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";
+ }
+ ]
+ }</p>
+<p><nowiki>If there is only one entry in the result set, this would be
returned as follows.</nowiki></p>
+<p>{
+ "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"; }
+ }
+ }
+ ]
+ }</p>
+<p><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></p>
+<p>{
+ "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.
+ |}</p>
+<p>==== 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"</p>
+<p>{
+ "@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></p>
+<p>{
+ "@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" }
+ ]
+ }</p>
+<p>|}</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0";>Apache
License, Version 2.0</a>.
+ <br />
+ Apache, Stanbol and the Apache feather and Stanbol logos are
trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
