ont-app/vocabulary

Integration between Clojure keywords and URIs, plus support for RDF-style language-tagged literals.

Contents

• Installation
• Motivation
• Defining keyword Identifiers (KWIs) mapped to URI namespaces
  • Basic namespace metadata
  • Working with KWIs
    • uri-for
    • qname-for
    • keyword-for
  • Accessing-namespace-metadata
    • put-ns-meta! and get-ns-meta
    • prefix-to-ns
    • ns-to-namespace
    • namespace-to-ns
    • ns-to-prefix
    • clear-caches!
  • Support for SPARQL queries
    • sparql-prefixes-for
    • prepend-prefix-declarations
  • Common Linked Data namespaces
    • Imported with_ont-app.vocabulary.core
    • Imported with ont-app.vocabulary.wikidata
    • Imported with ont-app.vocabulary.linguistics
• Language-tagged strings
• License

Installation

Available at clojars.

 (defproject .....
  :dependencies 
  [...
   [ont-app/vocabulary "<this version>"]
   ...
   ])

Motivation

Clojure provides for the definition of keywords, which function as identifiers within Clojure code, and serve many useful purposes. These keywords can be interned within specific namespaces to avoid collisions. The role played by these keywords is very similar to the role played by URIs within the Linked Open Data (LOD) community, which also has a regime for providing namespaces.

Ont-app/vocabulary provides mappings between Clojure namespaces and URI-based namespaces using declarations within Clojure namespace metadata.

There is also support for a similar arrangement within Clojurescript, though some things are done a little differently given the fact that Clojurescript does not implement namespaces as first-class objects.

These mappings set the stage for using Keyword Identifiers (KWIs) mappable between Clojure code and the larger world through a correspondence with URIs.

Another construct from RDF that may have application more generally in graph-based data is that of a language-tagged literal, which tags strings of natural language with their associated language. For example we could use such tags to express the differing orthographies of "gaol"@en-GB vs. "jail"@en-US. This library defines a custom reader tag lstr for declaring similar language-tagged strings, e.g. #lstr "gaol@en-GB" and #lstr "jail@en-US".

Defining Keyword Identifiers (KWIs) mapped to URI namespaces

(ns ...
 (:require
   ...
   [ont-app.vocabulary.core :as voc] 
   ...))

This will load function definitions interned in the vocabulary.core namespace, and also a number of other ns declarations, each dedicated to a commonly occurring namespace in the world of LOD.

Basic namespace metadata

Within standard (JVM-based) clojure, the minimal specification to support ont-app/vocabulary functionality for a given namespace requires metadata specification as follows:

(ns org.example
  {
    :vann/preferredNamespacePrefix "eg"
    :vann/preferredNamespaceUri "http://example.org/"
  }
  (:require 
  [ont-app.vocabulary.core :as v]
  ...))

This expresses an equivalence between the clojure keyword...

  :eg/example-var

... and the URI ...

 <http://example.org/example-var>

The vann prefix refers to an existing public vocabulary which will be explained in more detail below.

Unfortunately, Clojurescript does not implement namespaces as first-class objects, and so there is no ns object to which we can attach metadata. So ont-app/vocabulary provides this idiom to achieve the same effect in both clj and cljs environments:

(voc/put-ns-meta!
 'org.example
  {
    :vann/preferredNamespacePrefix "eg"
    :vann/preferredNamespaceUri "http://example.org/"
  })

In Clojure, it simply updates the metadata of the named namespace (which may be automatically created with create-ns). In Clojurescript, this updates a dedicated map from org.example to 'pseudo-metadata' in a global atom called cljs-ns-metadata.

Working with KWIs

uri-for

We can get the URI string associated with a keyword:

The function uri-for works for fully qualified keywords, whose aliases interned in the local lexical environment (note the double-colon):

> (require [org.example :as eg]) ;; or any other alias
> (voc/uri-for ::eg/Example)

"http://example.org/Example"
>

We can also usually get away with using a single colon (these are qualified, but not fully qualified ...

> (voc/uri-for :eg/Example)
"http://example.org/Example"
>

... but because the namespace is hard-coded and not bound to clojure's aliasing system, there is the possibility of a clash in the case where the same alias was chosen for two different namesspace. This is not really a problem for well-known prefixes like rdfs or foaf, but may become a bigger problem if you choose a generic prefix like "data".

Also, it's important to note that while ::eg/Example and :eg/Example resolve to the same URI string, the keywords themselves are not equal in Clojure.

This function is called uri-for to reflect common usage, but because any UTF-8 characters can be used, these are actually IRIs. The function iri-for function is also defined as an alias of uri-for.

qname-for

We can get the qname for a keyword:

> (voc/qname-for ::foaf/homepage)
"foaf:homepage"
>

keyword-for

We can get a keyword for a URI string...

> (voc/keyword-for "http://xmlns.com/foaf/0.1/homepage")
:foaf/homepage
>

If the namespace does not have sufficient metadata to create a namespaced keyword, the keyword will be interned in a namespace based on the URI scheme:

> (voc/keyword-for "http://example.com/my/stuff")
:http://example.com/my/stuff))
>

Characters which would choke the reader will be %-escaped. These characters differ depending on whether we're using the jvm or cljs platforms.

There is an optional arity-2 version whose first argument is called when no ns could be resolved:

> (voc/keyword-for (fn [u k] (log/warn "No namespace metadata found for " u) k)
                  "http://example.com/my/stuff")
WARN: No namespace metadata found for "http://example.com/my/stuff"
:http://example.com/my/stuff
>          

Accessing namespace metadata

put-ns-meta! and get-ns-meta

Let's take another look at the metadata we used above to declare mappings between clojure namespaces and RDF namespaces:

(voc/put-ns-meta!
 'org.example
  {
    :vann/preferredNamespacePrefix "eg"
    :vann/preferredNamespaceUri "http://example.org/"
  })

Note that the metadata for this module includes some qualified keywords in this format:

:<prefix>/<name>

The relations preferredNamespaceUri and preferredNamespacePrefix are part of the public VANN vocabulary, with well-defined usage and semantics.

The namespace for vann is also declared as ont-app.vocabulary.vann in the ont_app/vocabulary/core.cljc file, with this declaration:

(voc/put-ns-meta!
 'ont-app.vocabulary.vann
 {
   :rdfs/label "VANN"
   :dc/description "A vocabulary for annotating vocabulary descriptions"
   :vann/preferredNamespaceUri "http://purl.org/vocab/vann"
   :vann/peferredNamespacePrefix "vann"
   :foaf/homepage "http://vocab.org/vann/"
 })

There is an inverse of put-ns-meta! called get-ns-meta:

> (voc/get-ns-metadata 'ont-app.vocabulary.foaf)
{
 :dc/title "Friend of a Friend (FOAF) vocabulary"
 :dc/description "The Friend of a Friend (FOAF) RDF vocabulary,
 described using W3C RDF Schema and the Web Ontology Language."
 :vann/preferredNamespaceUri "http://xmlns.com/foaf/0.1/"
 :vann/preferredNamespacePrefix "foaf"
 :foaf/homepage "http://xmlns.com/foaf/spec/"
 :dcat/downloadURL "http://xmlns.com/foaf/spec/index.rdf"
 :voc/appendix [["http://xmlns.com/foaf/spec/index.rdf"
                 :dcat:mediaType "application/rdf+xml"]]
 })
>

These are much richer descriptions than the minimal example in the previous section, with metadata encoded using several different public vocabularies, described below.

Note that these are all simple key/value declarations except the :voc/appendix declaration which is in the form

:voc/appendix [[<subject> <predicate> <object>]....], 

This includes triples which elaborate on constructs mentioned in the key-value paris in the rest of the metadata, in this case describing the media types of files describing the vocabulary which are available for download at the URLs given.

prefix-to-ns

We can get a map of all the prefixes of namespaces declared within the current lexical environment:

> (voc/prefix-to-ns)
{"dc" #namespace[ont-app.vocabulary.dc],
 "owl" #namespace[ont-app.vocabulary..owl],
 "ontolex" #namespace[ont-app.vocabulary.ontolex],
 "foaf" #namespace[ont-app.vocabulary.foaf],
 ...
 }
 >

In Clojurescript, since there's no ns object, the results would look like this:

> (voc/prefix-to-ns)
{"dc" ont-app.vocabulary.dc,
 "owl" ont-app.vocabulary..owl,
 "ontolex" ont-app.vocabulary.ontolex,
 "foaf" ont-app.vocabulary.foaf,
 ...
 }
 >

ns-to-namespace

We can get the URI namespace associated with an ns

In Clojure:

> (voc/ns-to-namespace (find-ns 'ont-app.vocabulary.foaf))
"http://xmlns.com/foaf/0.1/"
>

In both Clojure and ClojureScript:

> (voc/ns-to-namespace 'ont-app.vocabulary.foaf)
"http://xmlns.com/foaf/0.1/"
>

namespace-to-ns

We can get a map from namespace URIs to their associated clojure namespaces:

> (voc/namespace-to-ns)
{
 "http://www.w3.org/2002/07/owl#"
 #namespace[org.naturallexicon.lod.owl],
 "http://persistence.uni-leipzig.org/nlp2rdf/ontologies/nif-core#"
 #namespace[org.naturallexicon.lod.nif],
 "http://purl.org/dc/elements/1.1/"
 #namespace[org.naturallexicon.lod.dc],
 "http://www.w3.org/ns/dcat#"
 #namespace[org.naturallexicon.lod.dcat],
 ...
 }
>

With the usual allowance for clojurescript described above.

ns-to-prefix

We can get the prefix associated with an ns:

> (voc/ns-to-prefix (voc/cljc-find-ns 'org.naturallexicon.lod.foaf))
"foaf"
>

clear-caches!

For performance reasons, these metadata values are all cached. If you're making changes to the metadata and it's not 'taking', you may need to clear the caches:

> (voc/clear-caches!)

Support for SPARQL queries

RDF is explicitly constructed from URIs, and there is an intimate relationship between SPARQL queries and RDF namespaces. ont-app/vocabulary provides facilities for extracting SPARQL prefix declarations from queries containing qnames.

sparql-prefixes-for

We can infer the PREFIX declarations appropriate to a SPARQL query:

> (voc/sparql-prefixes-for
             "Select * Where{?s foaf:homepage ?homepage}")
("PREFIX foaf: <http://xmlns.com/foaf/0.1/>")
>

prepend-prefix-declarations

Or we can just go ahead and prepend the prefixes...

> (voc/prepend-prefix-declarations
               "Select * Where {?s foaf:homepage ?homepage}")
"PREFIX foaf: <http://xmlns.com/foaf/0.1/>
Select * Where{?s foaf:homepage ?homepage}"
>

Common Linked Data namespaces

Part of the vision of the ont-app project is to provide a medium for expressing what adherents to Domain-driven Design and Behavior-driven Design call a "Ubiquitous Vocabulary". It also shares the vision of the Linked Data community that huge network effects can emerge when vocabularies emerge which are shared amongst a community of users working in the same domain.

There are a large number of public vocabularies dedicated to various application domains, some of which have gained a good deal of traction in the Linked Data community. Ont-app/vocabulary includes declarations of their associated namespaces, packaged within the core module, a module dedicated to wikidata, and another dedicated to linguistics.

Imported with ont-app.vocabulary.core

Requiring the ont-app.vocabulary.core module also loads ns declarations dedicated to some of the most commonly used RDF/Linked Open Data prefixes:

PREFIX	URI	Comments
rdf	https://www.w3.org/2001/sw/wiki/RDF	the basic RDF constructs
rdfs	https://www.w3.org/TR/rdf-schema/	expresses class relations, domain, ranges, etc.
owl	https://www.w3.org/OWL/	for more elaborate ontologies
vann	https://vocab.org/vann/	for annotating vocabulary descriptons
dc	http://purl.org/dc/elements/1.1/	elements of Dublin Core metadata initiative
dct	http://purl.org/dc/terms/	terms for the Dublin Core metadata initiative
sh	https://www.w3.org/TR/shacl/	for defining well-formedness constraints
dcat	https://www.w3.org/TR/vocab-dcat/	Data Catalog vocabulary
foaf	http://xmlns.com/foaf/spec/	the 'Friend of a Friend' vocabulary
skos	http://www.w3.org/2004/02/skos/core#	for thesaurus-type taxonomies
schema.org	https://schema.org/	mostly commercial topics, with web-page metadata and search-engine indexes in mind

Imported with ont-app.vocabulary.wikidata

Requiring the ont-app.vocabulary.wikidata module imports declarations for the several namespaces pertinent to the Wikidata database.

It also defines the value for Wikidata's public SPARQL endpoint is as this constant:

ont-app.vocabulary.wikidata/sparql-endpoint

Imported with ont-app.vocabulary.linguistics

The ont-app.vocabulary.linguistics module declares namespaces for:

PREFIX	URI	Comments
ontolex	http://www.w3.org/ns/lemon/ontolex#	for encoding lexical data
pmn	http://premon.fbk.eu/ontology/core#	PreMOn - dedicated to describing English verbs
nif	http://persistence.uni-leipzig.org/nlp2rdf/ontologies/nif-core#	Natural Language Interchange Format - for annotating corpora

There are also a set of namespaces particular to my Natural Lexicon project, which are still under development.

Language-tagged strings

RDF entails use of language-tagged strings (e.g. "gaol"@en-GB) when providing natural-language content. Typing this directly in Clojure code is a bit a bit awkward, since the inner quotes would need to be escaped.

To enable this language tag, we must require the namespace:

(require ...
  [ont-app.vocabulary.lstr :refer [lang]]
  )

This library defines a reader macro #lstr and accompanying record LangStr to facilitate writing language-tagged strings in clojure. The value above for example would be written: #lstr "gaol@en-GB".

The reader encodes an instance of type LangStr (it is autoiconic):

> (def brit-jail #lstr "gaol@en-GB")
brit-jail
> brit-jail
#lstr "gaol@en-GB"
> (type brit-jail)
ont_app.vocabulary.lstr.LangStr
>

Rendered as a string, the language tag is dropped

> (str #lstr "gaol@en-GB")
"gaol"
>

We get the language tag with lang:

> (lang #lstr "gaol@en-GB")
"en-GB"
>

License

Copyright © 2019-20 Eric D. Scott

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

Natural Lexicon logo - Copyright © 2020 Eric D. Scott. Artwork by Athena M. Scott. Released under Creative Commons Attribution-ShareAlike 4.0 International license. Under the terms of this license, if you display this logo or derivates thereof, you must include an attribution to the original source, with a link to https://github.com/ont-app, or http://ericdscott.com.