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. The FactStore only stores the relation and not the entities itself. It only uses references to entities by using the entities' URI. The entities itself should be handled by another component, e.g. the Entityhub. A fact is defined by a fact schema which is defined over types of entities.
A fact schema can be defined between an arbitrary number of entities. In most cases a fact schema is defined between two or three entities. For example, the fact schema 'works-for' can be defined as a relation between entities of type 'Person' and 'Organization'. The Fact Store interface allows the creation of custom fact schemata and to store facts according to these custom schemata. The Fact Store provides a simple way to define and store facts. This component is meant to be used in scenarios where a simple solution is sufficient and it is not required to define a complex ontology with reasoning support.
Read on and have a look at a concrete example or go to the FactStore specification page for more details. If you need some information about its realization, read the notes about its implementation concept.
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 schema.org.
According to schema.org is a person 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 an Apache Stanbol launcher that includes the FactStore and navigate your browser to http://localhost:8080/factstore. There you will find more information and the documentation of the FactStore's REST API.