Skip to content

Latest commit

 

History

History
341 lines (259 loc) · 12.2 KB

README.md

File metadata and controls

341 lines (259 loc) · 12.2 KB
Raw

The Hypertopic protocol is to the Social Semantic Web what SPARQL is to the Formal Semantic Web. It is based on the Hypertopic model which is an alternative to RDF/RDFS.

In the Hypertopic model:

  • attribute types are defined by users,
  • knowledge models depends on a subjective modality.

In the Hypertopic protocol:

  • updating models is considered as important as reading them,
  • horizontal scaling is preferred to formal expressivity.

To achieve that, we defined it as a "RESTful" protocol.

Requirements & Design choices

This version of the protocol (v2) meets additional requirements:

  • Features
    • Confrontation of data from different services
  • Performance
    • Complex tasks with a fixed number of HTTP requests
    • Easy cache managing (logs could be enough)
    • Batch creations (imports)
  • Quality & project management
    • Reuse services instead of code
    • v1 and v2 usable at the same time on the same data (for transition)
  • Ease of coding
    • Atomic resources (no more partial updates needed)
    • No more ad-hoc URL parsing
    • Same parsing code for every type format
    • Implementable on SQL and noSQL datastore
    • Implementable with REST frameworks

To meet these requirements we had to opt for:

  • Non-located items

To get the description of an item, clients often need to mash-up attributes and topics stored or generated on different servers. We once implemented a "remote item" mechanism, however this handles as a special case something that will get more and more common (esp. with Argos & Cassandre, Argos & Steatite). Instead we will consider that every item is identified by a UUID which must be checked for links on any known server. The same approach will be used for other objects, to optimize distribution and service reuse.

  • Documentary items

There was no efficient way to do complex algorithms if the link between sources and fragments were handled by item-item. Moreover, most of algorithms were not tractable without being limited to a single corpus. Therefore we decided that what would be tagged would have "(corpus,source,fragment)" as its primary key (fragment can be equals to "none").

We considered standard or well-known URI schemes for user-named contents such as corpora, hash contents such as resources, and plain text fragment identifiers. But we chose the simplest way to refer them (UUIDs and coordinates).

Data model

Note: Item-Item will remain unspecified until we have more real cases for it.

Objects

Objects can be created, read, updated and deleted through the standard HTTP methods (POST, GET, PUT, and DELETE respectively).

Their payloads complies with the JSON standard format.

On creation, objects are given an "_id" by the service. If it handles conflict detection, they are given a "_rev" on each write action.

TODO: explain _rev and _id handling.

TODO: explain _changes handling.

Please note that, in order to allow specialized processing and to reduce network latency, the normal way to read an object is through a view. The only time to GET an object is before modifying it.

TODO: explain the data model (esp. corpus, items, highlights)

Corpus

A corpus MUST have a corpus_name (which can be empty), and MAY have users.

{
  "corpus_name": "N1", 
  "users": ["U1", "U2"]
}

Item

An item MUST have an item_corpus. It MAY have an item_name, a resource, topics (with a viewpoint) and highlights (with coordinates, viewpoint and topic).

{
  "item_name": "N2", 
  "item_corpus": "C", 
  "resource": "http://acme/bar", 
  "A": "V", 
  "topics": {
    "T1": {"viewpoint":"V1"}
  }, 
  "highlights": {
    "H": {
      "coordinates": [X,Y],
      "viewpoint": "V2",
      "topic": "T2"
    }
  }
}

Reserved attribute names:

  • thumbnail (for items and highlights),
  • text and actor (for highlights).

Viewpoint

A viewpoint MUST have a viewpoint_name (which can be empty). It MAY have users and topics (with name and broader topics). The topics graph should be acyclic.

{
  "viewpoint_name": "N3", 
  "users": ["U1"],
  "topics": {
    "T2": {"name": "N4"},
    "T3": {"name": "N5", "broader":["T2"]}
  }
}

Reserved attribute names:

  • icon (for topics).

Views

Views can be read through the HTTP GET method. Their payloads complies with the JSON standard format.

They are made of rows. Each row has a key (a JSON array) and a value (a JSON object).

TODO: explain distributed objects

TODO: explain distributed links

Corpus

GET /corpus/C

{"rows":[
  {"key":["C"], "value":{"name":"N1"}},
  {"key":["C"], "value":{"user":"U1"}},
  {"key":["C"], "value":{"user":"U2"}},
  {"key":["C","I"], "value":{"name":"N2","resource":"http://acme/bar"}},
  {"key":["C","I"], "value":{"A":"V"}},
  {"key":["C","I"], "value":{"topic":{"viewpoint":"V1","id":"T1"}}},
  {"key":["C","I", "H"], "value":{"coordinates":[X,Y], "topic":{"viewpoint":"V2", "id":"T2"}}}
]}

Item

GET /item/C/I

{"rows":[
  {"key":["C","I"], "value":{"name":"N2","resource":"http://acme/bar"}}, 
  {"key":["C","I"], "value":{"A":"V"}},
  {"key":["C","I"], "value":{"topic":{"viewpoint":"V1","id":"T1"}}},
  {"key":["C","I", "H"], "value":{"coordinates":[X,Y], "topic":{"viewpoint":"V2", "id":"T2"}}}
]}

Resource

GET /item/?resource=http://acme/bar

{"rows":[
  {"key":["http://acme/bar"],"value":{"item":{"corpus":"C","id":"I"}}}
]}

User

GET /user/U1

{"rows":[
  {"key":["U1"], "value":{"corpus":{"id":"C", "name":"N1"}}},
  {"key":["U1"], "value":{"viewpoint":{"id":"V2", "name":"N3"}}}
]}

Viewpoint

GET /viewpoint/V2

{"rows":[
  {"key":["V2"], "value":{"name":"N3"}},
  {"key":["V2"], "value":{"user":"U1"}},
  {"key":["V2"], "value":{"upper":{"id":"T2","name":"N4"}}},
  {"key":["V2","T2"], "value":{"name":"N4"}},
  {"key":["V2","T2"], "value":{"narrower":{"id":"T3", "name":"N5"}}},
  {"key":["V2","T3"], "value":{"name":"N5"}},
  {"key":["V2","T3"], "value":{"broader":{"id":"T2", "name":"N4"}}}
]}

Topic

GET /topic/V2/T2

{"rows":[
  {"key":["V2","T2"], "value":{"name":"N4"}},
  {"key":["V2","T2"], "value":{"narrower":{"id":"T3", "name":"N5"}}}
]}

Attributes by corpus

GET /attribute/C/

{"rows":[
  {"key":["C","A"],"value":"1"}
]}

Attribute

GET /attribute/C/A/

{"rows":[
  {"key":["C","A", "V"],"value":"1"}
]}

Attribute value

GET /attribute/C/A/V

{"rows":[
  {"key":["C","A", "V"],"value":{"item":{"id":"I","name":"N2"}}}
]}

Implementation

Services

GET, POST, PUT, DELETE Argos Cassandre
/CorpusID X X
/ItemID X
/ViewpointID X
GET Argos Cassandre Steatite
/corpus/ID X X X
/item/ID/ID X X X
/item/?resource=URL X X X
/user/ID X X X
/viewpoint/ID X X
/topic/ID/ID X X
/attribute/ID/ X X
/attribute/ID/ZZ/ X X
/attribute/ID/ZZ/ZZ X X

Hypertopic services can be tested with a generic REST client.

Client APIs

References