Technical Whitepaper
The architecture of Topincs is based on REST, which is an architectural style, described by Roy Fielding in his dissertation. The current implementation depends on Apache 2, MySQL and PHP 4, which are commonly referred to as AMP. The server can be run on every operating system, that supports AMP, which, to my knowledge, are Windows, Linux, and Mac OS X. In principle, also other combinations of the web server, programming language and database system are possible. The usage of the HTTP protocol, however, is central. As as long as the HTTP interface does not change, the clients will be able to continue working with the server. It uses a uniform interface and stateless communication. It violates the Hypermedia as the Engine of the Application State constraint of REST, since the clients can not evolve independently of the server.
Every item of the Topic Map Data Model (TMDM) is assigned a URI, which functions as its item identifier and allows manipulation via the HTTP methods, PUT, GET, POST, and DELETE. Thus, if you want to create a topic in a topic map, you POST the topic to the URI of the map. This request returns the URI under which the new topic will be addressable.
If you want to add a name to this topic, you post the name to the URI of the topic and are returned the URI of the name. If you discover a typing error in the name, you PUT a new version of the name to the URI of the name. If the name becomes superfluous, you send a DELETE request to the URI of the name. After that, the name is no longer addressable under its item identifier.
The URIs that function as item identifiers follow a strict form. Every Topincs installation can host multiple independent stores. Every store has a base URI under which is it addressable. By default a Topincs installation comes with one store which is located at http://yourhost/topincs/. The maps in this store are located in http://myhost/topincs/maps/. Table 1 shows exemplary URIs for all constructs in the Topic Map Data Model.
| Topic map | http://yourhost/topincs/topicmaps/yourmap/ |
| Topic | http://yourhost/topincs/topics/1 |
| Name | http://yourhost/topincs/names/1 |
| Variants | http://yourhost/topincs/variants/1 |
| Occurrences | http://yourhost/topincs/occurrences/1 |
| Association | http://yourhost/topincs/associations/1 |
| Roles | http://yourhost/topincs/roles/1 |
JSON Topic Maps
The data format used for topic maps in Topincs is JSON Topic Maps, JTM. This format is not officially governed by anybody, but is rather an invention of mine. In a web browser environment it is just much more convenient to work with JSON than XML.
JSON stands for JavaScript Object Notation and
is a very simple and easy to use alternative to XML. Douglas
Crockford, the man behind json.org, calls it the fat-free
alternative to XML
. As the name says, it allows the notation of
JavaScript objects. Serialization and deserialization is a
one-liner. Support in the browser is native, and on the server-side
numerous packages exist for handling JSON.
JTM as it is used in Topincs is an exact serialization of the items as they are specified in the TMDM. For example a topic name looks as follows:
{"value":"Robert Cerny",
"type":"http://psi.topicmaps.com/iso13250/topic-name",
"reifier":null,
"scope":[]}JTM is at the moment the only format that the Server understands on manipulation requests (PUT and POST). It is just a matter of resources to adjust the server to understand XTM 1.1 on incoming requests. On GETting items, the server provides XTM 1.0, XTM 1.1 and JTM 1.0. And it provides an XHTML representation of the items.
Further readings
There is two conference papers which elaborate the ideas around Topincs in greater detail:
