Documentation metamodel (DEPRECATED)
Status: intermediate draft / proposal
Authors and contributors:
- Chris Mungall (author)
Status:
- DEPRECATED
Date: 2012
Document Type: metadata_description
See: https://github.com/obophenotype/uberon/issues/301
This article describes a proposed inline documentation system used by Uberon. The article is intended to be a component of the system.
Note this system was originally implemented in 2012 and abandoned as being too hard to maintain. See 301 for details.
We may try and resurrect parts of the system, and derive the RDF from the wiki, using the model described here.
Documentation is essential for ontology development. yet there is no standard way to document an ontology. In addition, there is a tendency for external documentation (wiki pages, web pages, etc) to drift from the ontology.
The goal is for an ontology to be as self-documenting as possible. In addition to the standard metadata associated with each class, we embed articles in the ontology. These articles may describe abstract design patterns or templates that are repeated throughout the ontology, or the modeling of a particular piece of biology (e.g. the heart). Some articles are of interest to users of the ontology, as they describe in more detail the system being represented and why it was represented in a particular way. Other articles may be solely for the developers of the ontology.
Each article is represented as an individual, and gets a unique URI. For example, the URI for this article is http://purl.obolibrary.org/obo/uberon/references/reference_0000000.
Each article is then adorned with metadata, using properties from vocabularies such as dublin core. The text of the article is represented using dc:description with a string value. The text is authored using a variant of markdown syntax, which can then be translated to html.
Each article is of a specific type. The categories used include:
- ontology documentation
- biological modeling
- ontology design pattern
- metadata documentation
Currently the documentation system assumes a flat hierarchy and assertions to leaf nodes. The vocabulary used for the above is not yet stable.
Any properties can be used, but the recommended set is:
- dc:date (1) (currently the year as an int, for historic reasons)
- dc:creator (1 or more) - the main author(s)
- dc:contributor (0 or more)
- dc:title (1, required)
- dc:abstract (1, required)
- dc:description (1, required) in markdown format
- rdfs:seeAlso (0 or more) - links to other related articles or resources
The publishing status ontology (pso) is used to give each article a status such as 'initial-draft'
Each article can be references multiple times in the main ontology, in different ways.
Sometimes a class may point to an article - for example, if an ontology class implements a certain design pattern or template described in an article, then a 'implements design pattern' annotation property connects the two.
Sometimes it may be more appropriate to link an axiom annotation to an article.
Articles can be viewed when references.owl is loaded alongside the main ontology in the ontology editing environment, but this is not appropriate for everyone.
Each article can be viewed on the web via its purl
Ontology editors should edit the file references-edit.omn in git - any new articles created should be in their idrange - see uberonref-idranges.owl.
The file can be edited in a text editor (the recommended text editor emacs plus Phil Lord's omn-mode.el, plus ubref-helper.el). Note that the author should be adept in manchester notation.
The prefered route is to open the articles ontology in Protege, navigating to the 'individuals by type' tab (insert image here).
In both cases, the main text should go in the dc:description tab using markdown format. Note that hashes should be used for headings rather than underlines.
The format used is a variant called ontology markdown. Class labels can be written in backtics - the derived documentation will make PURL links from these (to be implemented).
In general each article type should follow a certain template (to be documented).
The ontology release manager will generate the derived documentation from this file.
The current implementation has been abandoned, but we retain a description of it here:
The references-edit.omn is translated to an rdf/owl ontology - references.owl
A perl script (owldoc2md.pl) generates individual markdown (.md) files from this owl file (using a to-be-released API). It assumes some of the annotation properties listed above are used.
Each markdown file is then converted to an html file using pandoc.
The html file has the same name as the localname of the URI. It is committed to svn, and the svn property svn:mime-type is set to text/html
This system was inspired by Matt Brush's REO documentation system developed at OHSU, and by David Osumi-Sutherland's org-mode system, as well as by Phil Lord's articles on ontology documentation and applying literate programming ideas to ontologies.