Author: fchrist
Date: Fri Jan 13 13:05:47 2012
New Revision: 1231045
URL: http://svn.apache.org/viewvc?rev=1231045&view=rev
Log:
STANBOL-456 Moved factstore docs into its own sub folder
Added:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/index.mdtext
Removed:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore.mdtext
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/components.mdtext
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/components.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/components.mdtext?rev=1231045&r1=1231044&r2=1231045&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/components.mdtext
(original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/components.mdtext
Fri Jan 13 13:05:47 2012
@@ -29,5 +29,5 @@ We will shortly describe the components
* The [Contenthub](contenthub.html) provides you with a combined index of your
content items together with enhancements to facilitate semantic search on your
entire knowledge base.
-* The [FactStore](factstore.html) is a component that let's use store
relations between entities identified by their URIs. This relation between two
entities is called a _fact_.
+* The [FactStore](factstore/) is a component that let's use store relations
between entities identified by their URIs. This relation between two entities
is called a _fact_.
Added:
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=1231045&view=auto
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/index.mdtext
(added)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/index.mdtext
Fri Jan 13 13:05:47 2012
@@ -0,0 +1,47 @@
+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.
+
+## 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.
+
+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/.
+
+According to http://schema.org/ a person is of type http://schema.org/Person
and an organization is of type http://schema.org/Organization. We will use
these type information to specify the fact schema
http://factschema.org/worksFor. The specification of a fact schema is written
in JSON-LD, like this:
+
+ {
+ "@context" : {
+ "#types" : {
+ "person" : "http://schema.org/Person";,
+ "organization" : "http://schema.org/Organization";
+ }
+ }
+ }
+
+To create this fact schema in the FactStore we have to store it in a *.json
file, e.g. worksFor.json, and PUT it into the FactStore. The path to put the
fact schema is `/factstore/facts/{factSchemaName}`. So for our example this
would be `/factstore/facts/http://factschema.org/worksFor`. Unfortunately, this
is not a valid URI so that we have to URL-encode the name of the fact schema.
This leads to
+`/factstore/facts/http%3A%2F%2Ffactschema.org%2FworksFor`.
+
+_Note_: If you want to avoid this URL-encoding step, you should chose another
name for your fact schema that is not an URI by itself. You are free to do so!
+
+Now to PUT the `worksFor` fact schema we can use this cURL command.
+
+ curl
http://localhost:8080/factstore/facts/http%3A%2F%2Ffactschema.org%2FworksFor -T
worksFor.json
+
+After creating the fact schema we can store the fact that John Doe works for
Winzigweich by POSTing it to the FactStore. The fact is specified in JSON-LD
syntax. The `@profile` defines the fact schema where this fact belongs to.
+
+ {
+ "@profile" : "http://factschema.org/worksFor";,
+ "person" : { "@iri" : "http://www.doe.com/john"; },
+ "organization" : { "@iri" : "http://www.winzigweich.de"}
+ }
+
+Now we can POST this fact, e.g. stored in fact.json, to the FactStore at
`/factstore/facts`. By using cURL it would be this command:
+
+ curl -d @fact.json -H "Content-Type: application/json"
http://localhost:8080/factstore/facts
+
+On success this will return a 201 (Created) and the URI of the newly created
fact in the location header of the response. To retrieve a fact you can GET it
from the returned URI.
+
+## REST API Documentation
+
+To get the latest documentation you should start your copy of Apache Stanbol
and navigate your browser to http://localhost:8080/factstore. There you will
find more information and the documentation of the FactStore's REST API.
\ No newline at end of file
