Generate Vocabulary Artifacts#
In addition to Inrupt’s vocabulary libraries, which provide convenience objects for many common terms/identifiers, Inrupt also provides an Artifact Generator to generate your own set of convenience objects.
The Artifact Generator can take as input existing online
vocabulary(ies), local .ttl
file(s), or a combination of both, and
your generated set can be a subset or an extension of existing
vocabularies.
Install/Run#
To run, you can use npx
to run the generator without needing to
install it locally:
npx @inrupt/artifact-generator <command> <options>
Alternatively, you can install the generator locally and run:
Install locally.
npm install @inrupt/artifact-generator
Run by referencing generator’s
index.js
from within thenode_modules
directory. For example:node node_modules/@inrupt/artifact-generator/index.js <command> <options>
Commands#
The Artifact Generator supports the following commands
|
Generates the artifacts. |
|
Initializes a configuration YAML file. |
|
Validates a configuration YAML file. |
|
Watches the input vocabulary resources (specified in the configuration YAML file) to automatically regenerate the artifacts if any of the input resources change. |
To see all available commands, you can specify the --help
option:
npx @inrupt/artifact-generator --help
Options#
The Artifact Generator includes options to:
Select a subset of terms to include from the source vocab in the generated artifact.
Enhance selected terms, for example with additional translations.
Provide the version number for the output module.
Specify a custom prefix for the output module name.
Specify a custom NPM registry where the generated artifact will be published.
Generate artifacts for other programming languages; e.g., Java.
Options can be provided to the Artifact Generator using the Command-Line Interface (CLI) or, for more advanced features such as generating artifacts for different programming languages, a YAML config file.
To see all available options for the supported commands, specify the
--help
option after the command:
npx @inrupt/artifact-generator <command> --help
For example, the following lists the options for the generate
command:
npx @inrupt/artifact-generator generate --help
Generate Artifacts using the CLI#
To generate artifacts from existing vocabulary (or vocabularies), use
the --inputResources
option to pass in either the URI if the vocabulary is
online or the filepath if the vocabulary is local.
From a Single Input Resource#
The following example uses the Inrupt’s publicly available PetRock
vocabulary (available at
https://team.inrupt.net/public/vocab/PetRock.ttl) to generate a
JavaScript artifact PET_ROCK.js
.
npx @inrupt/artifact-generator generate --inputResources https://team.inrupt.net/public/vocab/PetRock.ttl --noprompt
That is, the generate operation specifies the following options:
|
Set to the PetRock vocabulary’s URI
|
|
Optional. Specified to suppress interactive prompts during the generation process. |
You can run npx @inrupt/artifact-generator generate --help
for more
details on the options.
The generate operation creates a JavaScript artifact PET_ROCK.js
that provides constants for all the terms described within the public
Pet Rock vocabulary. The PET_ROCK.js
artifact is located
in the Generated/SourceCodeArtifacts/JavaScript/GeneratedVocab
directory under the current directory.
From Multiple Input Resources#
The files passed to --inputResources
can be remote or local. You
can pass in multiple vocabulary resources to --inputResources
as a
space-delimited list.
Note
If passing in multiple resources, the resources must share the same namespace.
For example, consider the following local files Event.ttl
and
Organization.ttl
that represent subsets of the Schema.org
vocabulary:
@prefix ns3: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix schema: <http://schema.org/> .
schema:Event a rdfs:Class ;
rdfs:label "Event" ;
rdfs:comment "An event happening at a certain time and location, such as a concert, lecture, or festival. Ticketing information may be added via the [[offers]] property. Repeated events may be structured as separate Event objects." ;
rdfs:subClassOf schema:Thing ;
ns3:equivalentClass <http://purl.org/dc/dcmitype/Event> .
schema:Thing a rdfs:Class ;
rdfs:label "Thing" ;
rdfs:comment "The most generic type of item." .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix schema: <http://schema.org/> .
schema:Organization a rdfs:Class ;
rdfs:label "Organization" ;
rdfs:comment "An organization such as a school, NGO, corporation, club, etc." ;
rdfs:subClassOf schema:Thing .
schema:Thing a rdfs:Class ;
rdfs:label "Thing" ;
rdfs:comment "The most generic type of item." .
To generate an artifact using the two resources, pass the file paths to
--inputResources
as a space delimited list.
npx @inrupt/artifact-generator generate --inputResources ./Event.ttl ./Organization.ttl --noprompt
Create a Front-End JavaScript Artifact#
By default, the generate
command generates the required Rollup config to bundle the artifact. You can
deactivate the bundling by setting --supportBundling
to false:
npx @inrupt/artifact-generator generate --inputResources https://team.inrupt.net/public/vocab/PetRock.ttl --noprompt --supportBundling=false
Rollup is the default option from the CLI. You can specify other bundlers (e.g., Parcel, Webpack, etc.) in the YAML configuration file.
Use Generated Artifacts in a JavaScript App#
Once generated, the artifact can be used directly in applications, both Node.js and browser based.
For example, after you add PET_ROCK.js
as a dependency to a project as
generated-vocab-pet-rock
, you can then use the library as in the
the following code snippet:
// ...
import { PET_ROCK } from 'generated-vocab-pet-rock';
console.log("What is Pet Rock 'shininess'?\n");
console.log("Our vocabulary describes it as:");
console.log(PET_ROCK.shininess.comment);
console.log("Or in Spanish (our Pet Rock vocab has Spanish translations!):");
console.log(PET_ROCK.shininess.asLanguage('es').comment);
Generate Artifacts using YAML Configuration File#
The previous examples used the available command-line options to configure the artifact generation. Alternatively, you can use a YAML configuration file.
For example, the previous PET_ROCK.js
generation can be performed
using the following YAML config file ./example/mypetrock.yml
:
artifactName: generated-vocab-test
artifactGeneratorVersion: 0.13.4
artifactToGenerate:
- programmingLanguage: "JavaScript"
artifactVersion: "0.1.0"
solidCommonVocabVersion: "0.5.3"
artifactDirectoryName: "JavaScript"
templateInternal: "solidCommonVocabDependent/javascript/vocab.hbs"
sourceFileExtension: "js"
languageKeywordsToUnderscore:
- "class"
- "abstract"
- "default"
packaging:
- packagingTool: "NPM"
npmModuleScope: "@example/scope"
packagingTemplates:
- templateInternal: solidCommonVocabDependent/javascript/index.hbs
fileName: index.js
- templateInternal: solidCommonVocabDependent/javascript/package.hbs
fileName: package.json
- packagingTool: rollup
packagingFolder: config
packagingTemplates:
- templateInternal: generic/javascript/rollup.config.hbs
fileName: rollup.config.js
vocabList:
- inputResources:
- "https://team.inrupt.net/public/vocab/PetRock.ttl"
To generate using the configuration file, pass the YAML config file to
the --vocabListFile
option:
npx @inrupt/artifact-generator generate --vocabListFile ./example/mypetrock.yml --noprompt
YAML Configuration Options#
You can use the generator to initialise the YAML file with all the required options.
npx @inrupt/artifact-generator init
Once generated, you can customize the file as required.
The following example YAML file shows all available configuration options.
##
# GENERAL INFORMATION
##
# Name of the generated artifact.
artifactName: generated-vocab-test
# MANDATORY. Version of the @inrupt/artifact-generator with which this YAML file is compatible
artifactGeneratorVersion: 1.0.0
##
# VERSIONING INFORMATION
##
# This section is not mandatory
versioning:
# Type of the versioning protocol. This is for documentation purpose.
type: git
# URL of the target repository. This is used in some packaging systems (e.g. NPM)
url: https://repository.git
# These files will be generated at the root of the target artifact
versioningTemplates:
# A template name. It can reference existing internal templates supplied
# within the Artifact Generator, or custom templates relative to this
# configuration file.
- templateInternal: ".gitignore.hbs"
# The name of the file generated from the template
fileName: ".gitignore"
##
# TARGET ARTIFACT CONFIGURATION
##
# MANDATORY, and must contain at least one artifact
artifactToGenerate:
# The generated programming language. This is for documentation purpose.
- programmingLanguage: Java
# The version of the generated artifact. This is used for packaging. Be aware that versioning policies differ
# depending on the package manager (e.g. NPM does not allow re-publication of the same version, while Maven does)
artifactVersion: 3.2.1-SNAPSHOT
# The version of the Vocab Term library (e.g. https://github.com/inrupt/solid-cpommon-vocab-js for JavaScript,
# https://github.com/inrupt/solid-cpommon-vocab-java for Java) upon which the generated vocabularies
# will depend. This is used for packaging.
solidCommonVocabVersion: "0.1.0-SNAPSHOT"
# MANDATORY The sub-directory of the output directory in which the current artifact will be generated.
artifactDirectoryName: Java
# MANDATORY - Must be one (and only one) of either:
# - templateInternal References a Handlebars template internally
# provided by the Artifact Generator, and relative to it's internal
# "templates" directory.
# - templateCustom References a Handlebars template relative to
# the configuration file.
templateInternal: solidCommonVocabDependent/java/rdf4j/vocab.hbs
# MANDATORY The extension that is appended after the name of the generated source code files.
sourceFileExtension: java
# These terms will be prefixed by an underscore in the generated code.
# It allows us prevent conflicts if a term from a vocabulary is also a
# keyword in the target language.
languageKeywordsToUnderscore:
- class
- abstract
# Package name. This is a Java-specific option. More generally, each 'artifactToGenerate' object is used to define
# environment variables that are used to instantiate the template. Without changing the core code, it is therefore
# possible to use language-specific options in the YAML file and to use them in the templates.
javaPackageName: com.inrupt.testing
##
# PACKAGING CONFIGURATION
##
# The packaging options are artifact-specific. They are not mandatory.
packaging:
# This is for documentation purpose
- packagingTool: maven
# As for the 'artifactToGenerate', the 'packaging' objects are passed to the appropriate template. Therefore,
# the generator code is agnostic to the variables defined here. For instance, the groupId thereafter is used
# in the 'pom.hbs' template.
groupId: com.inrupt.test
rdf4jVersion: 2.5.3
packagingTemplates:
# MANDATORY The template(s) instantiated once to generate the target packaging code.
# It can reference a handlebars template relative to the YAML file, and also
# accepts 'jpom.hbs', 'package.hbs', 'index.hbs', 'webpack.dev.config.hbs'
# and 'webpack.dev.config.hbs'.
- templateInternal: solidCommonVocabDependent/java/rdf4j/pom.hbs
# The name of the generated packaging file
fileName: pom.xml
- programmingLanguage: JavaScript
artifactVersion: 10.11.12
solidCommonVocabVersion: "^1.0.10"
artifactDirectoryName: JavaScript
templateInternal: solidCommonVocabDependent/javascript/vocab.hbs
sourceFileExtension: js
packaging:
# Note how different packaging tools can be used for the same artifact (e.g. NPM and webpack, or
# Gradle and Maven), and how each of these packaging tools may generate more than one file.
- packagingTool: npm
# This is an NPM-specific option, used in the generated package.json
npmModuleScope: "@inrupt/"
packagingTemplates:
- templateInternal: solidCommonVocabDependent/javascript/package.hbs
fileName: package.json
- templateInternal: solidCommonVocabDependent/javascript/index.hbs
fileName: javascript/index.js
- packagingTool: webpack
# If this is set (not mandatory), the packaging files are instanciated in this directory
packagingFolder: config
packagingTemplates:
- templateInteral: webpack.dev.config.hbs
fileName: webpack.dev.config.js
- templateInteral: webpack.prod.config.hbs
fileName: webpack.prod.config.js
##
# INPUT VOCABULARIES
##
vocabList:
# Description of the vocabulary, that will be used as a comment describing the generated class
- description: Snippet of Schema.org from Google, Microsoft, Yahoo and Yandex with selective terms having translations
# MANDATORY A list of resources, which can be any mixture of local RDF files (whose path may be absolute,
# or relative to the YAML file itself) or remote IRI's, from which a single vocabulary source file will
# be generated.
inputResources:
- https://schema.org/version/latest/schema.ttl
# The name of the generated vocabulary class. For instance, if set to `foo`, the corresponding Java class will
# be `FOO.java`. If not set, the generator will look in the source RDF vocabulary for the
# `vann:preferredNamespacePrefix` property, and if it is not defined the generation will be interrupted.
nameAndPrefixOverride: schema-inrupt-ext
# When using only a portion of a large vocabulary, this option specifies a second input vocabulary that defines the subset of terms that are to be
# generated from the `inputResources`. Moreover, it also enables adding custom information to a vocabulary you don't have control over (e.g. adding
# translations for existing labels or comments, or overriding existing values, or adding completely new terms, etc.). For an example, see https://github.com/inrupt/artifact-generator/blob/develop/test/resources/vocabs/schema-inrupt-ext.ttl.
termSelectionResource: ../test/resources/vocabs/schema-inrupt-ext.ttl
Template files#
The template files defined in the YAML determine the code generated
by the artifact generator. The reason for this configuration is that the
artifact generator can output vocabulary artifacts in multiple programming
languages and in a form compatible with any of a number of existing RDF
libraries. The options that can be specified for templateInternal
can
be seen in the templates
directory of the artifact generator repo.
If you need to support a programming language or RDF library not
covered by a provided template, or if you need to make your own changes
to the generated output, you can supply your own template files using
templateCustom
.
For example, the default JavaScript template uses the Inrupt library
@inrupt/solid-common-vocab to output
generated vocabulary terms as VocabTerm
objects. These objects give
developers access to all the meta-data associated with individual
vocabulary terms (e.g., the rdfs:comments
, the rdfs:seeAlso
links, the rdfs:isDefinedBy
).
YAML Validation#
Using the validate
command, you can validate a YAML config file to
ensure it is correctly formatted for artifact generation:
npx @inrupt/artifact-generator validate --vocabListFile ./example/your-generator-config.yml
Automatic Artifact Regeneration#
Using the watch
command, you can start a process to continuously
watch a list of vocabularies specified in the YAML configuration file
and re-generate the artifacts in response to changes:
npx @inrupt/artifact-generator watch --vocabListFile ./example/your-generator-config.yml
The process runs in the foreground until you hit “Enter”.
Repository#
For more examples, as well as example .ttl
files for term
selection, see the Artifact generator repository.