Spec-Toolkit CLI

This documentation explains how to use the Spec-Toolkit CLI tool. However, most will be done via the configuration file.

Prerequisite

1. You have installed Node v22 or higher and npm v10 or higher from: nodejs.

2. You have installed the CLI tool on your local machine.

   npm install -g @open-resource-discovery/spec-toolkit

3. You have prepared a local configuration file.

CLI signature

Use the CLI tool via npx.

# By default it will look for a `./spec-toolkit.config.json` config file in the CWD
npx @open-resource-discovery/spec-toolkit

# Possible to pass a configuration file by file path
npx @open-resource-discovery/spec-toolkit -c ./spec-toolkit.config.json

CLI options

Name	Value	Description
-c	<configFilePath>	Configuration file, containing a valid JSON document.

Configuration File Interface Documentation

Spec-Toolkit CLI root level configuration document (spec-toolkit.config.json), which contains:

• Global config
• Array of all specs JSON Schema files as input and their configuration
• Optional: Array of all spec extensions and their configuration
• Optional: Add plugin config for additional output formats (like diagrams, example files, typescript types).

Schema Definitions

• The root schema of the document is Spec-Toolkit Configuration Document
• The interface is available as JSON Schema: spec-toolkit-config.schema.json.

Spec-Toolkit Configuration Document

Type: Object($schema, $id, generalConfig, outputPath, docsConfig, plugins)

Property	Type	Description
$schema OPTIONAL	string	Link to JSON Schema for this spec-toolkit configuration document. Adding this helps with automatic validation and code intelligence in some editors / IDEs. See https://tour.json-schema.org/content/06-Combining-Subschemas/02-id-and-schema JSON Schema Format: uri-reference Recommended Values: "https://github.com/open-resource-discovery/spec-toolkit/spec-v1/spec-toolkit.schema.json#"
$id OPTIONAL	string	Optional URI for this document, that can acts as an ID or as location to retrieve the document. See https://tour.json-schema.org/content/06-Combining-Subschemas/02-id-and-schema JSON Schema Format: uri-reference
generalConfig OPTIONAL	GeneralConfig	General configuration for the spec-toolkit. This is optional and can be omitted if no general configuration is needed.
outputPath MANDATORY	string	The output path where the generated files will be written to. This is relative to the location of the configuration document.
docsConfig MANDATORY	Array<SpecConfig | SpecExtensionConfig>	Configuration for the documentation generation. Array Constraint: MUST have at least 1 items
plugins OPTIONAL	Array<PluginConfigData>	Array of optional plugins to be used for the generation. Each configured plugin will generate additional output files depending on his specific scope.

GeneralConfig

This is the general configuration for the spec-toolkit. This is optional and can be omitted if no general configuration is needed.

Type: Object(tsTypeExportExcludeJsFileExtension)

Property	Type	Description
tsTypeExportExcludeJsFileExtension OPTIONAL	boolean	If set to true, the generated TypeScript types will exclude the .js file extension in the export statements. The '.js' file extension is useful for compatibility with Node.js ESM modules but in Node.js commonjs modules it is not needed. Default Value: true

DocsConfigItem

Definition of a docsConfig item.

Type: SpecConfig | SpecExtensionConfig
Type: Object(type)

Property	Type	Description
type MANDATORY	string	The docsConfig item type. It's value is been used as a discriminator to distinguish the matching schema that should be further validated. Allowed Values: "spec" "specExtension"

SpecConfig

This is the configuration for a JSON Schema specification.

Type: Object(type, id, sourceFilePath, sourceIntroFilePath, sourceOutroFilePath, examplesFolderPath, mdFrontmatter)

Property	Type	Description
type MANDATORY	string	Type is used to identify the type of the configuration. Constant Value: spec
id MANDATORY	string	The ID of the specification. This is used to identify the specification in the generated documentation.
sourceFilePath MANDATORY	string	The path to the source file of the JSON Schema specification. This is used to generate the documentation for the specification. It can be a .yaml or .json file. The JSON Schema specification MUST NOT contain objects nested in objects. Example: type: object properties:   fullName:     type: object     properties:         firstName:             type: string         lastName:             type: string   age:     type: integer MUST be replaced by: type: object properties:   fullName:     $ref: "#/definitions/FullName"   age:     type: integer
sourceIntroFilePath OPTIONAL	string	The path to the source intro file of the specification. This is used to generate the documentation for the specification and will be appended at the beginning.
sourceOutroFilePath OPTIONAL	string	The path to the source outro file of the specification. This is used to generate the documentation for the specification and will be appended at the end.
examplesFolderPath OPTIONAL	string	The path to the folder containing the examples for the specification. This is used to generate the documentation for the specification. SHOULD contain specification compliant instance example files with extension .json or .jsonc.
mdFrontmatter OPTIONAL	MdFrontmatter	Frontmatter for the generated documentation. This is used to generate the markdown frontmatter for the documentation page.

SpecExtensionConfig

This is the configuration for a JSON Schema extension specification.

Type: Object(type, id, sourceFilePath, sourceIntroFilePath, sourceOutroFilePath, targetDocumentId, mdFrontmatter)

Property	Type	Description
type MANDATORY	string	Type is used to identify the type of the configuration. Constant Value: specExtension
id MANDATORY	string	The ID of the specification. This is used to identify the specification in the generated documentation.
sourceFilePath MANDATORY	string	The path to the source file of the specification. This is used to generate the documentation for the specification.
sourceIntroFilePath OPTIONAL	string	The path to the source intro file of the specification. This is used to generate the documentation for the specification and will be appended at the beginning.
sourceOutroFilePath OPTIONAL	string	The path to the source outro file of the specification. This is used to generate the documentation for the specification and will be appended at the end.
targetDocumentId MANDATORY	string	The ID of the target document. This is used to identify the target document in the generated documentation.
mdFrontmatter OPTIONAL	MdFrontmatter	Frontmatter for the generated documentation. This is used to generate the markdown frontmatter for the documentation page.

MdFrontmatter

Frontmatter for the generated documentation. This is used to generate the markdown frontmatter for the documentation page.

Property	Type	Description
Additional Properties ^[a-zA-Z0-9_]+$ OPTIONAL	string	The key of the frontmatter. This is used to generate the frontmatter for the documentation. Additional properties MUST follow key name regexp pattern: ^[a-zA-Z0-9_]+$

PluginConfigData

Configuration for a plugin to be used in the generation.

Type: Object(packageName, options)

Property	Type	Description
packageName MANDATORY	string	The package name or path to the plugin implementation. Plugins are implemented as Node.js modules and can be specified by their package name or by a relative path to the spec-toolkit CLI tool when the plugins are maintained in the core spec-toolkit repository.
options OPTIONAL	PluginOptions	Optional configuration for the plugin. This is used to pass additional options to the plugin.

Example Values:

{
  "packageName": "./node_modules/@open-resource-discovery/spec-toolkit/dist/plugin/tabular/index.js"
}

{
  "packageName": "./node_modules/@open-resource-discovery/spec-toolkit/dist/plugin/mermaidDiagram/index.js"
}

{
  "packageName": "./node_modules/@open-resource-discovery/spec-toolkit/dist/plugin/ums/index.js",
  "options": {
    "metadataPath": "/sap/core/ucl/metadata/ord/v1",
    "overrides": [
      "./document.ums.yaml"
    ]
  }
}

{
  "packageName": "@yourNamespace/yourNpmSpecToolkitPluginPackageName"
}

PluginOptions

Optional configuration for the plugin. This is used to pass additional options to the plugin.

Type: Object()

Property	Type	Description
*		Additional, unspecified properties MAY be added to the object.

Spec-Toolkit CLI configuration example

{
  "outputPath": "src/generated/spec-v1",
  "docsConfig": [
    {
      "type": "spec",
      "id": "csn-interop-effective",
      "sourceFilePath": "./spec/v1/CSN-Interop-Effective.schema.yaml",
      "sourceIntroFilePath": "./spec/v1/CSN-Interop-Effective.schema.md",
      "examplesFolderPath": "./spec/v1/examples",
      "mdFrontmatter": {
        "title": "Interface Documentation",
        "sidebar_position": "1",
        "description": "Describes the technical interface / schema for CSN Interop Effective.",
        "toc_max_heading_level": "4"
      }
    },
    {
      "type": "specExtension",
      "id": "aggregation",
      "sourceFilePath": "./spec/v1/annotations/aggregation.yaml",
      "sourceIntroFilePath": "./spec/v1/annotations/aggregation.md",
      "targetDocumentId": "csn-interop-effective",
      "mdFrontmatter": {
        "title": "@Aggregation",
        "sidebar_position": "2",
        "description": "@Aggregation annotations."
      }
    },
    {
      "type": "specExtension",
      "id": "analytics-details",
      "sourceFilePath": "./spec/v1/annotations/analytics-details.yaml",
      "sourceIntroFilePath": "./spec/v1/annotations/analytics-details.md",
      "targetDocumentId": "csn-interop-effective",
      "mdFrontmatter": {
        "title": "@AnalyticsDetails",
        "sidebar_position": "3",
        "description": "@AnalyticsDetails for data analytics use cases."
      }
    },
    {
      "type": "specExtension",
      "id": "consumption",
      "sourceFilePath": "./spec/v1/annotations/consumption.yaml",
      "sourceIntroFilePath": "./spec/v1/annotations/consumption.md",
      "targetDocumentId": "csn-interop-effective",
      "mdFrontmatter": {
        "title": "@Consumption",
        "sidebar_position": "4",
        "description": "@Consumption annotations."
      }
    },
    {
      "type": "specExtension",
      "id": "end-user-text",
      "sourceFilePath": "./spec/v1/annotations/end-user-text.yaml",
      "sourceIntroFilePath": "./spec/v1/annotations/end-user-text.md",
      "targetDocumentId": "csn-interop-effective",
      "mdFrontmatter": {
        "title": "@EndUserText",
        "sidebar_position": "5",
        "description": "@EndUserText annotations for end user UIs."
      }
    },
    {
      "type": "specExtension",
      "id": "entity-relationship",
      "sourceFilePath": "./spec/v1/annotations/entity-relationship.yaml",
      "sourceIntroFilePath": "./spec/v1/annotations/entity-relationship.md",
      "sourceOutroFilePath": "./spec/v1/annotations/entity-relationship.outro.md",
      "targetDocumentId": "csn-interop-effective",
      "mdFrontmatter": {
        "title": "@EntityRelationship",
        "sidebar_position": "6",
        "description": "@EntityRelationship annotations for cross boundary Entity-Relationship IDs and associations."
      }
    },
    {
      "type": "specExtension",
      "id": "object-model",
      "sourceFilePath": "./spec/v1/annotations/object-model.yaml",
      "sourceIntroFilePath": "./spec/v1/annotations/object-model.md",
      "targetDocumentId": "csn-interop-effective",
      "mdFrontmatter": {
        "title": "@ObjectModel",
        "sidebar_position": "7",
        "description": "@ObjectModel annotations."
      }
    },
    {
      "type": "specExtension",
      "id": "odm",
      "sourceFilePath": "./spec/v1/annotations/odm.yaml",
      "sourceIntroFilePath": "./spec/v1/annotations/odm.md",
      "targetDocumentId": "csn-interop-effective",
      "mdFrontmatter": {
        "title": "@ODM",
        "sidebar_position": "8",
        "description": "@ODM for One Domain Model (ODM) related annotations."
      }
    },
    {
      "type": "specExtension",
      "id": "personal-data",
      "sourceFilePath": "./spec/v1/annotations/personal-data.yaml",
      "sourceIntroFilePath": "./spec/v1/annotations/personal-data.md",
      "targetDocumentId": "csn-interop-effective",
      "mdFrontmatter": {
        "title": "@PersonalData",
        "sidebar_position": "9",
        "description": "@PersonalData to annotate DPP relevant information."
      }
    },
    {
      "type": "specExtension",
      "id": "semantics",
      "sourceFilePath": "./spec/v1/annotations/semantics.yaml",
      "sourceIntroFilePath": "./spec/v1/annotations/semantics.md",
      "targetDocumentId": "csn-interop-effective",
      "mdFrontmatter": {
        "title": "@Semantics",
        "sidebar_position": "10",
        "description": "@Semantics annotations."
      }
    }
  ]
}