metalsmith-ldschema v3.0.0
metalsmith-ldschema
Metalsmith plugin for generating Web documentation for a linked data vocabulary. Inspired by https://schema.org
Requirements and Dependencies/Assumptions
- Node v10.15.0 or later
- Metalsmith (^2.3.0)
- Metalsmith Layouts (^2.3.1) plus a JSTransformer of your choosing.
- Metalsmith Permalinks (^2.2.0)
- Docker (optional but desirable)
Installation
- Create a new static Web site using metalsmith
yarn add metalsmith-ldschema
- Create one or more RDF files in your site directory. Your rdf-schema vocabulary will be defined in these files. While any RDF serialization should be supported by the site generator, it has at present been tested with JSON-LD and Turtle
Configuration Settings
The following represents an example configuration:
metalsmith(__dirname)
.source('./src')
.destination('./site')
.use(ldschema({
classLayout: 'class.hbs',
propertyLayout: 'property.hbs',
indexLayout: 'index.hbs',
base: 'http://schema.howarddierking.com',
query: `(SPARQL query)`,
isClass: <Term> => <Boolean>
getLayout: (<Options>, <String>) => <String>
}));
classLayout
(optional) - Layout file to use when renderingrdfs:Class
terms. Default value isclass.hbs
and expects to use the handlebars template engine via jstransformer-handlebarspropertyLayout
(optional) - Layout file to use when renderingrdf:Property
terms. Default value isproperty.hbs
and expects to use the handlebars template engine via jstransformer-handlebarsindexLayout
(optional) - Layout file to use when rendering an index page of allrdfs:Class
terms. Default value isindex.hbs
and expects to use the handlebars template engine via jstransformer-handlebarsbase
(optional) - Hostname (including scheme) for the Web site. This value is used as a mask for determining whether or not thehref
value in the view model is an absolute or relative URI. Ifbase
matches the url.origin value of a term'sid
,href
will be a relative URI - otherwise, it will be an absolute URI.query
(optional) - SPARQL query used to dynamically build the view model. The view model will contain the properties specified in theselect
clause of the SPARQL query with the leading '?' character removed. Note that the SPARQL engine used in rdflib.js does not support the full set of language capabilities. The default query covers basic RDF metadata and is as follows:
prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>
select ?id ?type ?label ?comment ?parent ?domain ?range
where
{
?id rdf:type ?type ;
rdfs:label ?label .
OPTIONAL {
?id rdfs:comment ?comment .
}
OPTIONAL {
?id rdfs:domain ?domain;
rdfs:range ?range .
}
OPTIONAL {
?id rdfs:subClassOf ?parent .
}
}
isClass
(optional) - A predicate function used to filter the complete set of terms so that classes can be displayed as a part of the index page. The default value filters on thetype
parameter equalling the valuerdfs:Class
.getLayout
(optional) - A selection function used to determine the metalsmith layout based on a term's type. The default function selects the value specified byoptions.classLayout
oroptions.propertyLayout
(or a default layout file value) based on whether the term's type isrdfs:Class
orrdf:Property
, respectively.
View Models
When building views, each template will be supplied with a view model containing either a single term or a list of terms (classes
in the case of the index page), depending on the type of page being rendered. For both property and class templates, the term will be held in the variable term
and will contain properties based on either the supplied or the default SPARQL query. For example, the default query will yield a term view model resembling the following:
id
\<URI> - URI of the termtype
\<URI> - Term typelabel
\<String> - Self-explanatorycomment
\<String> - Self-explanatorydomain
\<URI> - For property terms, domain represents the class on which the property may be foundrange
\<URI> - For property terms, range represents the possible types that the property value may be
In addition to the properties created from the supplied SPARQL query, the library adds the additional properties based on the provided input. Note that while the specific terms are no longer significant (thereby supporting ontologies other than RDF and RDFS), the parameter names need to be consistent in a supplied SPARQL query.
href
\<String> - URL to the term for the Web site. Based on thebase
configuration value, will be either an absolute or relative URLproperties
\<Term> - For class terms, properties associated with the class viardfs:domain
valueFor
\<Term> - For class terms, properties for which the class may be a type viardfs:range
parentClasses
\<Term> - For class terms, parent classes as specified byrdfs:subClassOf
childClasses
\<Term> - For class terms, child classes as specified byrdfs:subClassOf
usedOn
\<Term> - For property terms, classes on which the property may be found as specified byrdfs:range
expectedTypes
\<Term> - For property terms, possible types for the property as specified byrdfs:range
Using the Local Server
A common convention in ontology building is to use casing to differentiate classes from properties. This means that it's not uncommon to have a property and a class with the same name but different casing. Popular file systems like OSX's HFS have support for case-sensitivity, but it requires additional operating system configuration (e.g. journaling) which may be made increasingly complex by the addition of developer operating systems.
Rather than ask users to change core OS settings, the Docker image metalsmith-ldjson-server
is provided as a local server. This server is built on Alpine Linux and a file system that provides full support for case-sensitive filenames.
To use, simply mount your metalsmith-ldschema project directory into /project
, map your desired local port to 8080
in the container and execute a command as follows:
docker run -it \
-v "$(pwd):/project" \
-p 8080:8080 howarddierking/metalsmith-ldschema-host:latest \
"yarn install && npx bower install --allow-root && yarn run build"
Tests
Tests for the plugin can be run with yarn run test
from within the plugin directory
Reference Site
Until comprehensive documentation can be created, the general use cases can be seen through the included reference applications.