COMBINE specification infrastructure

The activities of COMBINE span several standards. Each standard is described in multiple specification documents. It is important to be able to refer precisely and consistently to a given standard or to its specification. It is also important to access the documents. In order to do so, COMBINE provides a hierarchy of specifications, that is mirrored both by the structure of identifiers describing the specifications, and the structure of the webpage tree providing access to the documents. Complete list of COMBINE specifications

The hierarchy is based on the notion of subset. An example of structure is given below for SBGN Entity Relationships. An ER specification is a subset of SBGN specifications. SBGN ER Level 1 Version 1.2 is a subset of SBGN ER Level 1 Version 1 specifications. And the PDF version of SBGN ER Level 1 Version 1.2 is a subset of SBGN ER Level 1 Version 1.2 specifications.

specification tree

Specification identifiers

The structure of the identifiers is: ^\w+(\-|\.|\w)*$

The following are all valid identifiers of specifications:

  • sbgn
  • sbgn.er
  • sbgn.er.level-1
  • sbgn.er.level-1.version-1
  • sbgn.er.level-1.version-1.2
  • sbgn.er.level-1.version-1.2.pdf

Those identifiers can be used to build Identifiers.org URIs, such as:

Webpage structure

Identifiers.org is then able to resolve those identifiers to pages on co.mbine.org.

These pages are in fact aliases of the real pages, arranged in a directory tree according to the structure described in the figure. Not all the possible pages exists, and several of the of URLs above can be aliases of the same actual page. The only mandatory pages are the top one for each standard, and the leaves, describing one specification. For instance, the last three URLs above currently (but that may change if the editors wish it) redirect to the description of the latest specification.Therefore the actual pages are:

Maintenance of the pages

It is anticipated that the editors of each project will maintain their own pages. For the standards which do not have an editorial board (yet), the maintainer of the COMBINE site will take over.

Here we will describe the procedure to handle an example standard, the super-hero description markup language (SHDML). SHDML has one level, one version and its specification is distributed as a PDF. We only want to describe the standard in a general way, and provide details of the latest specification.

1. create the top page

  • On the bottom left menu, click "Create content>>Page".
  • Fill in the title (here "Super Hero Description Markup Language").
  • Fill in the content. It should contain a link to downstream specification. Here the latest version of the standard, at http://co.mbine.org/standards/shdml/level-1/version-1
  • In "URL path settings", put "standards/shdml"

2. create the page for the latest specification

  • On the bottom left menu, click "Create content>>Page".
  • Fill in the title (here "SHDML Level 1 Version 1").
  • Fill in the content. It should contain a link to the specification itself.
  • In "URL path settings", put "standards/shdml/level-1/version-1"
  • In "File attachments", upload shdml.level-1.version-1.pdf

3. create the aliases

  • On the bottom left menu, click "Create content>>URL aliases Admin".
  • Select the tab "add alias".
  • In "Existing systems path", put the real page, such as "node/69"
  • In "Path alias", put the address you want to use as alias. For instance "node/69" must be aliased by "specifications/shdml", which therefore becomes alias of "standards/shdml".
  • "node/70" must be aliased by "specifications/shdml.level-1.version-1", which therefore becomes alias of "standards/shdml/level-1/version-1".
  • For the time being, we do not want to create a page for Level 1 of SHDML, and want to point to the last version instead. Therefore, we create another alias from "specifications/shdml.level-1" to "node/70".
  • We can also create an alias from "node/70" to "standards/shdml/level-1" if we do not want the users to reach an empty page when looking for "http://co.mbine.org/standards/shdml/level-1".
  • Finally, we want to access directly the PDF document with a standardised URL as well, so alias "system/files/shdml.level-1.version-1.pdf" to "specifications/shdml.level-1.version-1.pdf"

Note that aliases can be edited at any time. For instance, if a new intermediary page is created, to replace the automatic link to the latest specification.

4. update the central page

Although the infrastructure does not need a central list of all the specifications, it is handy for the users to have an overview of what we cover. Please edit the table at standards/specifications, with both the specification identifier and the corresponding webpage.