jan.bio

Publishing subject identifiers with node

Introduction

At the Topic Maps Research and Applications Conference in Leipzig this year, I had the possibility to talk about JavaScript Topic Maps in server environments. As a use case, I presented a server for Published Subject Identifers (PSIs). In this blog post, I’d like to give you a small introduction about how to use the server, as I’ve finally released the sources of the server at GitHub. It’s still pretty unstable and lots of features are still missing, but hey, now it is YOUR chance to become an early adaptor!

Overview

node-psi-server is a server application written in JavaScript. It’s Open Source and the software has been released under the MIT license. The basic idea is that you can take any topic map file and serve all its subject identifiers for a given servername.

node-psi-server can serve subject identifiers from any topic map that fit into memory. It supports logging, caching and templates for the generated pages, including export in HTML5 and JTM. The server can be configured using a simple configuration topic map where you can set default values for publisher, creation date and publishing status (experimental, stable, etc.) as well as occurrence and association types that you want to export for your topics. This way, you can include e.g. dc:description occurrences or type-instance associations all generated pages–if available for the topic in question. Installation

node-psi-server relies on nodejs and the Connect framework. The other dependencies, including the Topic Maps engine tmjs are included in the distribution. You can use git to download the sources directly from GitHub:

git clone http://github.com/jansc/node-psi-server.git

Alternatively, you can download a compressed archive with the sources by clicking on the blue “Downloads” button on the same page. That’s it. If you’re really impatient, take a look at the README file, otherwise, continue to configure your server:

Configuration

The distribution includes a JTM version of the Opera topic map which can be used for testing your installation. Before starting to configure your PSI server, you might be interested in listing all PSIs contained in your topic map. Enter the main folder of node-psi-server and type in the following command at the command line prompt:

node server.js --list examples/opera.jtm psi.ontopia.net

This will list all PSIs from the Opera topic map with a server name psi.ontopia.net. Note that you always start the server with node server.js followed by some options and two required parameters: the topic map filename and the servername for which you want to serve PSI pages. To get more detailed information about available options, type:

node server.js --help

Now, let’s start the PSI server itself:

node server.js --config ./config-sample.jtm \
    examples/opera.jtm psi.ontopia.net

Due to a limitation in tmjs, right now only JTM topic maps are supported. Therefore, the configuration has to be supplied as JTM as well. To make things a bit easier, a sample configuration file in CTM format is included in the distribution. You can find a syntax-hightlighted version of this file at paste.mappify.org. You can adjust this file to your needs and convert it to JTM using Mappify’s tm2tm converter. The options for default values, port number and debug level should be pretty self-explanatory. In addition to that, you can list occurrence and association types that you want to export. If you e.g. want to include a Dublin Core description occurrence for all topics with a description, add the following to you configuration (in CTM syntax):

nps:type-is-published(nps:type : dc:description)

If you want to include all associations of a given type, simply supply the PSI of an association type:

nps:type-is-published(nps:type :
   <http://psi.topicmaps.org/iso13250/model/type-instance>)

After you’ve started the server, something like the following output should appear:

25 Oct 21:42:40 - Reading configuration file `./config-sample.jtm`.
25 Oct 21:42:42 - Imported tm in 1.749secs
25 Oct 21:42:42 - Occurrence types and association types to include on PSI pages:
25 Oct 21:42:42 -  * http://psi.topicmaps.org/iso13250/model/type-instance
25 Oct 21:42:42 -  * http://purl.org/dec/elements/1.1/description
25 Oct 21:42:42 - Prefetching export types:
25 Oct 21:42:42 -  * found http://psi.topicmaps.org/iso13250/model/type-instance
25 Oct 21:42:42 - Server running at http://127.0.0.1:8000/

You should now be able to open the following pages in you web browser: http://localhost:8000/person or http://localhost:8000/city/380-firenze.

Here are some screenshots of the resulting pages:

Outlook Probably the biggest limitation right now is node-psi-server only supports JTM topic maps. Another known problem is, that PSIs containing anchors (that is PSIs with URLs with a #) can’t be served right now. This is because the browser does not send the anchor part of URLs to the server. In addition to that, there is a long list of wanted features: subj3ct.com integration, PSI stop lists, accept-header parsing, more export formats, etc. And lots of bug fixes! Your feedback is very welcome :-)

You might also be interested in the slides from my presentation at the TMRA:

JavaScript Topic Maps in server environments View more presentations from Jan Schreiber.