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:

  1. Install locally.

    npm install @inrupt/artifact-generator

  2. Run by referencing generator’s index.js from within the node_modules directory. For example:

    node node_modules/@inrupt/artifact-generator/index.js <command> <options>

Commands#

The Artifact Generator supports the following commands

generate

Generates the artifacts.

init

Initializes a configuration YAML file.

validate

Validates a configuration YAML file.

watch

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:

--inputResources

Set to the PetRock vocabulary’s URI https://team.inrupt.net/public/vocab/PetRock.ttl.

--noprompt

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.