ReSpec Documentation

Overview

ReSpec is a tool used to write technical specifications in a simple and structured way. It is widely used for creating web standards and other technical documents. Model2owl uses ReSpec to generate documentation for a vocabulary defined by a submitted UML model. The documentation is generated as an HTML file and consists of an autogenerated description of the underlying ontology terms, editorial content, metadata, and static assets. This feature is configurable, and a documentation editor has control over editorial content and metadata. The feature is based on Jinja2 templates that compile the model data, metadata, and HTML templates into the ReSpec document. The approach allows customization of the templates. Model2owl produces a ReSpec package as the outcome, which is a folder containing the HTML file and all required resources (artefact files, examples, images, and other static assets).

Usage

This section provides a step-by-step guide on how to generate ReSpec documentation using model2owl. The process is the same but can differ in details depending on whether model2owl is used locally or in an automated workflow (see How to use page).

Prepare an input UML model in XMI format

Export the UML model from your modelling tool in XMI format. Make sure that the XMI file conforms to the UML standard supported by model2owl (see Introduction). The file will be used as input for the model2owl transformation process. The source project with the UML model can be added to an asset folder for inclusion in the ReSpec documentation (see Input assets).

Generate model2owl artefacts

This step is optional and can be skipped if the editor prefers documentation without references to model2owl artefacts. See model2owl artefacts for more details on the artefacts.

If provided, the ReSpec documentation can include references to the model2owl artefacts generated from the input UML model (see model2owl artefacts). These files need to be generated prior to generating the ReSpec documentation. See Functional Commands for instructions on how to generate these artefacts using model2owl. The artefacts are not essential for generating the documentation; therefore, the generation process can be executed without them. In such cases, the documentation will not include references to these files.

Prepare input assets

This step is optional and can be skipped if the editor prefers documentation without static assets. See Supplementary assets for more details on input assets.

Depending on the needs, the documentation may include other static assets such as code examples, images, and additional files. These assets need to be prepared and stored in appropriate locations. The locations are typically subfolders of the ReSpec assets folder (see Supplementary assets).

Prepare metadata

ReSpec generation requires a JSON file containing metadata for the documentation. The metadata describes various aspects of the vocabulary and documentation. The metadata is used in Jinja templates and ultimately rendered in a ReSpec HTML document. See ReSpec metadata for a list of standard and custom metadata properties that can be set in the JSON file. The metadata.json file is typically stored in the same location as config-parameters.xsl and other model2owl configuration files.

Tweak or extend Jinja templates

This step is optional. If the default templates provided by model2owl are sufficient, this step can be skipped. See Template management for more details on template management and customization.

Model2owl provides a default Jinja2 template called the base template for ReSpec documentation generation. The base template is designed to allow fine-grained customization. This is done through a child template called the main template, which inherits from the base template. Model2owl comes with the base template and a slim main template. The main template can be further extended or modified through optional partial templates. See Template management for more details on template management and customization.

Run the generation process

If using model2owl locally, run the generate-respec command with appropriate parameters (see the command).

If using model2owl in an automated workflow (a project repository based on model2owl-boilerplate), the generation process is triggered automatically when a change in the repository is detected. The workflow executes the model2owl command, using configuration and data files present in the repository.

Output

The output will be a ReSpec package containing the HTML document and all provided resources. A documentation editor can publish it as a standalone static website using the technology of their choice. For development and testing purposes, the package can be hosted on a local web server.

The Documentation page structure section provides an overview of the structure of the generated documentation page.

Documentation page structure

The documentation page is built using ReSpec, which facilitates the creation of static documentation webpages and provides utilities for building the page. The page layout consists of:

  • the main content in the center,

  • table of content on the left side,

  • the header with title and optional logo,

  • metadata section at the top of the page, below the header,

  • sequence of sections making up the documentation content.

There are several standard sections that are present in the documentation by default (these can be overwritten in child templates):

  • Metadata: Displays document metadata such as contributors, links to sources and related resources, and custom metadata properties.

  • Abstract: Provides a concise summary of the vocabulary and its purpose.

  • Introduction: Explains the motivation, intended audience, and scope of the vocabulary.

  • Status: Indicates the current status of the specification, publication date, and approval information.

  • License: Details the licensing terms and usage restrictions for the vocabulary.

  • Conformance: Specifies normative and non-normative sections and outlines compliance requirements.

  • Terminology: Defines key terms and concepts used throughout the specification; includes an autogenerated list of used prefixes.

  • Overview: Presents a high-level summary of the vocabulary structure, including an optional diagram and autogenerated lists of classes and datatypes.

  • Main entities: Describes the primary terms (classes and properties) of the vocabulary (autogenerated).

  • Supportive entities: Covers additional reused terms that support the main entities (autogenerated).

  • Datatypes: Lists and describes the datatypes used in the vocabulary (autogenerated).

  • Governance: Provides information about the governance model, including how changes to the vocabulary are managed and who is responsible for its maintenance.

  • Quick reference of terms: Provides an interactive summary of all vocabulary terms (classes and properties) for easy lookup (autogenerated).

  • Project resources: Contains references to model2owl artefacts and other related resources.

An exemplary documentation webpage generated by model2owl can be found here.

The documentation can be customized in various ways, including adding new editorial content, new sections, as well as changing, extending, or removing sections. A comprehensive list of customization methods is provided in Customization.

Customization

Editors have multiple ways to customize the ReSpec generation process. Model2owl offers predefined properties to simplify configuration while also supporting custom properties and templates. This combination of flexibility and ease of use makes it suitable for both simple and complex scenarios.

The available customization options are:

  1. Standard metadata: Configure standard metadata in a ReSpec JSON file and provide editorial content for the default documentation sections in the main template (see Standard metadata and Base template blocks).

  2. Custom metadata: Everything in option 1, plus define custom metadata using the customMetadata.metadataSectionProperties property to extend the built-in ReSpec metadata section in a standardized way (see Metadata section properties).

  3. Extended editorial content: Any of the above, plus extend the documentation structure by adding new HTML sections directly in the main template or through partial templates (see Template types).

  4. Arbitrary metadata and template extension: Introduce arbitrary metadata via customMetadata and extend templates (see Template customization), using new property names to parameterize HTML content and optionally leveraging Jinja2 control structures (see Jinja2 documentation ). See Custom metadata for more details.

  5. Static assets: Any of the above, plus include static assets (code examples, images, additional files) and reference them in templates (see Input assets). See Supplementary assets for further details.

Input assets

All files needed for generating the ReSpec documentation must be prepared and stored in appropriate locations. The locations are typically subfolders of the ReSpec assets folder, however, the relevant model2owl command is configurable to allow using files from different locations.

The following structure for the ReSpec assets folder is used by default:

  • assets

    • model: contains model artefact files (OWL, SHACL, JSON-LD, XMI, and EAP files)

    • examples: contains code examples

    • img: contains images

    • shacl: contains SHACL shapes for validation purposes

    • sds: any additional files related to the model (Semantic Data Specifications)

    • js: contains JS scripts

The assets are copied to output ReSpec package (see Package management) and referenced in the HTML ReSpec document.

Model2owl artefacts

ReSpec documentation includes references to the following model2owl artefacts that are generated from the input UML model and belong to the vocabulary specification:

  1. OWL core ontology file

  2. OWL restrictions ontology file

  3. SHACL shapes file

  4. JSON-LD context file

Supplementary assets

Documentation generated by model2owl can include various static assets such as code examples, images, and additional files. These assets must be prepared and stored in appropriate locations. The locations are typically subfolders of the ReSpec assets folder.

The input assets folder can contain the following types of assets:

  1. Code examples: code snippets or files demonstrating the use of the vocabulary in different serializations (e.g., Turtle, JSON-LD, RDF/XML). These examples help users understand how to implement the vocabulary in their applications.

  2. Images: diagrams, charts, or other visual aids that help illustrate concepts or relationships within the vocabulary.

  3. Additional files: any other relevant documents or resources that support the vocabulary, such as supplementary documentation, project files, related standards, or reference materials.

In particular, the ReSpec template is configured to expect a standard asset named overview.png`, which is an image file containing a diagram illustrating the vocabulary structure and is referenced in the Overview section of the documentation.

The related HTML elements are rendered only if the corresponding files are present in the assets folder.

Template management

Model2owl provides a default Jinja2 template called the base template for ReSpec documentation generation. The editor is free to customize the base template as they see fit. However, the project promotes a specific way of organizing the templates.

Template types

The promoted organization of Jinja2 HTML templates is as follows:

  1. Generic base template stored in the model2owl repository: contains standard sections such as Abstract, Introduction, Status, License, Conformance, and Terminology.

  2. Customized main template stored in the model2owl-boilerplate repository: allows customization of the base template using the Jinja2 template inheritance mechanism (extends tag).

  3. Optional partial templates overriding or extending base sections are provided in the model2owl-boilerplate repository.

Base template

The base template is designed to allow fine-grained customization. Adjustable top-level sections are defined within the template as Jinja2 blocks, enabling redefinition in derived templates. The base template consists of blocks with HTML content for ReSpec sections making up a page, Jinja2 macros and control statements, as well as auxiliary JavaScript functions. The template assumes the predefined ReSpec package structure for resolving static assets (see Package management).

Template customization

The base template can be customized in the model2owl-boilerplate repository in several ways:

  1. No customization: an empty main template is used to render generic content from the base template.

  2. Direct modification of the main template: change, extend, or remove existing sections (using block redefinition with optional super() or by emptying a parent block) and add new sections.

  3. Modification via imported Jinja HTML partial templates: include statements in the derived template to incorporate partial templates.

A sample main template demonstrating different customization techniques is provided in the model2owl repository, available here.

Extension points

This section describes HTML sections defined as blocks in the base.j2 template that can be customized by a documentation editor. In addition, it covers macros and JS functions that are available for use in child templates.

Base template blocks

The list below shows the hierarchical structure of available blocks together with their descriptions.

  • respecConfig: contains ReSpec configuration parameters

    • respecConfigCustomParams: allows editors to add custom ReSpec configuration parameters without redefining the entire respecConfig block

  • pageContent: contains the main content of the ReSpec document

    • abstract: contains the abstract section of the document

    • introduction: provides context for the vocabulary, including the motivation for its creation, its intended audience, and the problems it aims to address

    • status: explains the current standing of the specification, including its level of formal recognition, publication date, and any relevant approval or recommendation information

    • license: details the licensing terms under which the vocabulary is made available, including any restrictions on use, distribution, or modification

    • conformance: outlines which parts of the specification are normative versus non-normative, and how compliance should be interpreted

    • terminology: defines key terms and concepts used throughout the specification to ensure clarity and consistency

      • usedPrefixesGen: an autogenerated section listing all the prefixes used in the vocabulary along with their corresponding namespaces

    • overview: provides a high-level summary of the vocabulary’s structure and terms

      • overviewClassesGen: an autogenerated section listing all the classes defined in the vocabulary

      • overviewDatatypesGen: an autogenerated section listing all the datatypes defined in the vocabulary

    • mainEntities: details the primary terms of the vocabulary, including their definitions and properties

      • mainEntitiesGen: an autogenerated section listing all the main entities (classes and properties) defined in the vocabulary

    • supportiveEntities: details additional terms (reused terms) that support the main entities, including their definitions and properties

      • supportiveEntitiesGen: an autogenerated section listing all the supportive entities (classes and properties) defined in the vocabulary

    • datatypes: details the datatypes used in the vocabulary, including their definitions

      • datatypesGen: an autogenerated section listing all the datatypes defined in the vocabulary

    • quickReference: a quick reference section providing an interactive summary of the vocabulary terms

      • quickReferenceGen: an autogenerated section listing all the terms (classes and properties) defined in the vocabulary

    • resources: contains references to model2owl artefacts and other related resources

Note that the pageContent block corresponds to the document structure as described in Documentation page structure.

Jinja utilities

This section lists Jinja2 macros defined in the base template that can be used in child templates.

Jinja2 variables The variables below reflect the structure of a ReSpec package and are used in the base template to reference static assets. They can be used in child templates as well:

  • docRoot: a path (URL) to the root of the ReSpec document

  • assetsRoot: a path (URL) to the assets directory

  • jsScriptsRoot: a path (URL) to JS scripts directory

  • examplesRoot: a path (URL) to the code examples directory

  • imgRoot: a path (URL) to the images directory

  • shaclRoot: a path (URL) to the SHACL files directory

Jinja2 macros:

  • renderFeedbackButton(entity, prop=None): Renders a feedback button for a given entity; if prop is provided, the button is associated with a specific property of the entity.

  • renderEntity(entity): Renders a detailed view of a given entity, including its properties.

ReSpec metadata

ReSpec generation feature uses metadata properties defined in the metadata JSON file. The Metadata parameters table lists standard metadata properties that are used during generation of model2owl artefacts, including the ReSpec documentation. A subset of the properties is used in the ReSpec base template. All the properties defined in the metadata file are available for use in child templates.

Standard metadata

Standard metadata properties are defined in the Metadata parameters table. Most of these properties are used in the ReSpec base template. The properties are defined in the top-level metadata JSON object. The properties are directly accessible in Jinja2 templates using the metadata variable, e.g., {{ metadata.title }}.

Custom metadata

customMetadata is a top-level property defined in metadata JSON that can contain arbitrary user-defined metadata. Each value may have any valid JSON structure. The property allows users to introduce custom metadata that can be referenced in templates. Model2owl does not manage such properties, so they must be explicitly introduced by the editor. They can be used in templates through Jinja2 syntax, e.g., {{ customMetadata.yourPropertyName }}.

customMetadata.metadataSectionProperties is a special property that can be used to introduce arbitrary user properties and make them render in the ReSpec built-in metadata section of the document. It is a list where each property is represented as an object with the following fields:

  • key: The name of the metadata property

  • data: List of values for the property; accepts one or many objects with the following fields:

    • value: The value of the metadata property

    • href: (optional) URL associated with the value; if provided, the value will be rendered as a hyperlink

Learn more about the format here.

Package management

Model2owl generates a self-contained folder with the documentation called a ReSpec package. ReSpec documentation consists of the HTML document itself, which is the core component, and a set of static assets (OWL, SHACL, XMI, and EAP distribution files, code snippets, images, etc.). Together, these form a ReSpec package. The assets are either embedded in the generated HTML page or distributed alongside it and referenced in the HTML document using ReSpec utilities.

ReSpec package structure

The following list presents the structure for the ReSpec package:

  • respec-package

    • index.html: the generated ReSpec documentation HTML file

    • assets: contains supplementary assets

      • overview.png: diagram illustrating the vocabulary structure

      • img: contains other images (e.g., callout.png)

    • sds: Semantic Data Specification artefacts for the vocabulary

      • model.qea: UML model file in a format of the modelling tool of choice

      • model.xmi: OWL core ontology file in XMI format exported from the modelling tool

      • model_core.rdf: OWL core ontology file generated by model2owl

      • model_restrictions.rdf: OWL restrictions ontology file generated by model2owl

      • model_shapes.ttl: SHACL shapes file generated by model2owl

      • model_context.jsonld: JSON-LD context file generated by model2owl

    • shacl: contains SHACL shapes for validation purposes

    • examples: contains code examples

Model2owl-boilerplate repository and GitHub automation

Model2owl-boilerplate serves as a blueprint for a project repository that can be cloned and used to set up a new project. The repository contains example project data and is preconfigured with a GitHub Actions workflow that automates the generation of ReSpec documentation. The workflow supports a multi-module structure and generates the ReSpec package for every input model module. The generated documentation includes a ReSpec website for each module, along with a landing page linking to all module websites.

When executed in an automated workflow, data stored in a respec-resources input folder is processed and the ReSpec package is saved in a respec subfolder of a module folder. Any modification in the project repository triggers the documentation to be regenerated and commits a new revision to the same branch. Each revision will include a reference to the source revision that triggered the documentation rebuild. The project repository can then be configured to publish the ReSpec documentation from that branch using the GitHub Pages feature. Details on how to set up the repository and configure the workflow for ReSpec generation can be found here.

Model2owl-boilerplate provides a straightforward way to publish documentation. The GitHub Pages setup in model2owl-boilerplate is for demonstration purposes only. The editor is ultimately responsible for publishing the documentation in the intended way.