Skip to content

Latest commit

 

History

History
197 lines (148 loc) · 8.45 KB

README.md

File metadata and controls

197 lines (148 loc) · 8.45 KB
Raw

Solid Common Vocabularies in RDF

This repository acts like a mono-repo for all the RDF vocabularies defined, controlled or used by Inrupt.

Vocabularies (also known, slightly more formally, as Ontologies) provide the basis to allow developers build interoperable applications by reusing the individual terms (i.e., Classes and Properties) from well-known and public vocabularies (such as Schema.org, or Friend-of-a-Friend (FOAF) or the Dublin Core (DC Terms) etc.), as well as from highly specialised or even private vocabularies, perhaps only ever intended for use within a narrow field, or even only within a single organization.

Convenient developer libraries/modules can be generated automatically from these vocabularies to provide programming language classes (one class per vocabulary) where each class is made up of constants representing the individual terms defined by a single vocabulary. As a developer, you just need to import the individual vocabulary class that you need to have access to the static constants representing each of the terms defined in that vocabulary (see the example below showing how easy it is to access the terms from the popular Friend-of-a-Friend (FOAF) RDF vocabulary).

Because developers typically use terms from multiple, often related vocabularies, it's generally more convenient if we bundle the generated classes from related vocabularies together into a single library/module, making it easier for developers to import.

Inrupt's Artifact Generator is a tool that can generate these convenient developer libraries/modules in multiple programming languages.

Published vocabulary bundles

This repository contains Artifact Generator configuration files for bundles of related vocabularies (each configured in its own sub-directory from the root of this repository).

Note: Below we provide links to the default TypeScript artifacts that Inrupt publishes to npmjs.org (which define individual vocabulary terms using String literals). In fact, we also publish many more artifacts that are more specialized for working with RDF too (e.g., we publish artifacts where the vocabulary terms are typed as IRI from your favorite RDF library, such as in Java from RDF4J, or as NamedNode in JavaScript with RDF/JS).

  • @inrupt/vocab-common-rdf, including dozens of well-known RDF vocabularies: FOAF, LDP, OWL, RDFS, etc.

  • @inrupt/vocab-solid, including vocabularies related to Solid like Solid Terms, WebACL, the Workspace Ontology, etc.

  • Inrupt's vocabulary bundles:

    Within Inrupt we use a number of bundles of vocabularies - for example, we have a bundle of Glossaries that we maintain as RDF vocabularies; we have a bundle for Unit Testing terms; we have a bundle for Inrupt Services; we have a bundle for UI components; etc.

    Of all these bundles, the 'Core' bundle contains vocabularies commonly used right across Inrupt:

To see how and where these bundles are generated, packaged, and published, you'll need to look at the configuration files themselves (i.e., the YAML files) in each of the respective directories (since different artifacts can be generated for different programming languages, and they can each depend on multiple different underlying RDF libraries, and can be published to multiple repositories - in other words, the entire generation process is extremely configurable and flexible!).

Vocabularies referenced in the repository

The general directory structure we use for each vocabulary bundle is as follows:

  • In the root directory we generally provide an Artifact Generator configuration file that configures which vocabularies we wish to bundle together, and how to package and publish multiple artifacts (e.g., multiple npm modules, or multiple Java JARs, etc.).

  • A /CopyOfVocab directory that stores local vocabulary files (typically in Turtle), such as copies of online vocabularies (e.g., if we can't easily access online versions in RDF, or if the hosting server is unreliable).

  • An /Extension directory that stores extension vocabularies that, for example, may provide translations of labels or comments for terms from other vocabularies, or that select subsets of terms from other large vocabularies.

Example usage - JavaScript

To use the terms defined in the common Friend-of-a-Friend (FOAF) vocabulary, which is just one of the vocabularies bundled in the @inrupt/vocab-common-rdf artifact, simply add the following dependency to your project:

npm install @inrupt/vocab-common-rdf

This npm module bundles together many of the most popular and common RDF vocabularies that exist today, of which FOAF is just one. So to import just the FOAF class from that dependency, simply do:

const { FOAF } = require("@inrupt/vocab-common-rdf");

...and now you can very easily and naturally use any of the FOAF terms in your code:

console.log(`The Agent term from the FOAF vocabulary has the IRI: [${FOAF.Agent}]`);

This should produce the output:

The Agent term from the FOAF vocabulary has the IRI: [http://xmlns.com/foaf/0.1/Agent]

Advanced usage

Our artifact generation process can optionally generate static constants that also provide very easy access to certain meta-data that is commonly provided by vocabularies (e.g., rdfs:label and rdfs:comment values, rdfs:seeAlso links, rdfs:isDefinedBy links, etc.).

To take advantage of this capability, you'll need to import one of the specialist artifacts that we routinely generate, one that generates individual vocabulary terms using Inrupt's solid-common-vocab-js library that is designed to pull in meta-data defined in the original RDF vocabulary, and that exposes that meta-data (like rdfs:label, rdfs:comment, rdfs:seeAlso, rdfs:isDefinedBy, etc.) via simple JavaScript methods.

For example, to access the rdfs:comment metadata associated with the FOAF term 'Agent', simply try the following:

mkdir tmp && cd tmp
npm init -y
npm i @inrupt/vocab-common-rdf-solidcommonvocab

Then create a simple index.js file containing these two lines of code:

const { FOAF } = require("@inrupt/vocab-common-rdf-solidcommonvocab");

console.log(`The comment associated with the term 'foaf:Agent' is: [${FOAF.Agent.comment}]`);

...and run it from the command line:

node index

...and you should see this output:

The comment associated with the term 'foaf:Agent' is: [An agent (eg. person, group, software or physical artifact).]

Try it out yourself - on CodeSandbox

Feel free to play around with this yourself using this very simple CodeSandbox example (e.g., see if you can edit this code to display the label and comment for the rather cryptically named fn term from the vCard vocabulary (which is also bundled in the same @inrupt/vocab-common-rdf artifact, exported as the VCARD class): https://codesandbox.io/s/inrupt-rdf-vocab-demo-206e7?file=/src/index.js

Issues & Help

Solid Community Forum

If you have questions about working with Solid, or just want to share what you’re working on, visit the Solid forum. The Solid forum is a good place to meet with the rest of the community.

Bugs and Feature Requests

  • For public feedback, bug reports, and feature requests please file an issue via GitHub.

  • For non-public feedback or support inquiries please use the Inrupt Service Desk.

Documentation

License

MIT © Inrupt