Concerto Linter Default Ruleset

A comprehensive set of linting rules designed to validate concerto models against industry best practices and consistent naming conventions. This default ruleset helps maintain high-quality, readable, and maintainable concerto models across your projects. It is fully configurable - you can extend it, add new rules, disable existing ones, or create an entirely new ruleset without extending this one.

This sub-package is part of the @accordproject/concerto-linter package. Read the concerto-linter README if you want to know how to use this ruleset with concerto models.

Table of Contents

• Concerto Linter Default Ruleset
  • Table of Contents
  • Key Benefits
  • Available Rules
  • Installation
  • Usage
  • Customization
    • Extending the Default Ruleset
    • Disabling Specific Rules
      • Available Rule IDs
    • Enabling Specific Rules
    • Adjusting Rule Severity
  • Creating Custom Rules
  • License

Key Benefits

• Consistent Code Style: Enforce uniform naming conventions across your concerto models
• Error Prevention: Catch common modeling mistakes before they cause issues
• Best Practices: Apply industry-standard modeling practices automatically
• Customizable: Easily extend or modify rules to match your project's specific needs
• Integration Ready: Works seamlessly with the concerto Linter and your development workflow

Available Rules

The following table provides an overview of the available linting rules in the default ruleset:

Installation

First, install the package as a development dependency:

npm install --save-dev @accordproject/concerto-linter-default-ruleset

Usage

Once installed, the default ruleset is automatically used by the concerto Linter when no custom ruleset is specified:

import { lintModel } from '@accordproject/concerto-linter';

// The default ruleset will be used automatically
const results = await lintModel(modelText);
console.log(results);

To explicitly specify the default ruleset:

const results = await lintModel(modelText, { ruleset: 'default' });

Customization

To create your own ruleset that fits your project needs, you can either extend the default ruleset, or create an entirely new ruleset from scratch.

Your ruleset should be defined in one of these file formats: .spectral.yaml, .spectral.yml, .spectral.json, or .spectral.js. The concerto Linter will automatically detect and use these files, or you can specify a custom path using the ruleset property: ruleset: "./path/to/my-ruleset.yaml".

Extending the Default Ruleset

You can extend the default ruleset in multiple formats:

YAML (.spectral.yaml)

extends: '@accordproject/concerto-linter-default-ruleset'

JSON (.spectral.json)

{
  "extends": "@accordproject/concerto-linter-default-ruleset"
}

JavaScript (.spectral.js)

const rules = require('@accordproject/concerto-linter-default-ruleset');
module.exports = {
  extends: rules
};

Disabling Specific Rules

You can disable specific rules that don't match your project's requirements by setting them to 'off'. The rule identifiers are defined in the ruleset-main.ts file located at concerto/packages/concerto-linter/default-ruleset/src.

Available Rule IDs

Here are all the rule IDs that can be disabled:

YAML (.spectral.yaml)

extends: '@accordproject/concerto-linter-default-ruleset'
rules:
  pascal-case-declarations: 'off'
  camel-case-properties: 'off'

JSON (.spectral.json)

{
  "extends": "@accordproject/concerto-linter-default-ruleset",
  "rules": {
    "pascal-case-declarations": "off",
    "camel-case-properties": "off"
  }
}

JavaScript (.spectral.js)

const rules = require('@accordproject/concerto-linter-default-ruleset');
module.exports = {
  extends: rules,
  rules: {
    'pascal-case-declarations': off,
    'namespace-version': off
  }
};

Enabling Specific Rules

You can selectively start with everything off and enable only specific rules:

YAML (.spectral.yaml)

extends: [['@accordproject/concerto-linter-default-ruleset', 'off']]
rules:
  pascal-case-declarations: true
  namespace-version: true

JSON (.spectral.json)

{
  "extends": [["@accordproject/concerto-linter-default-ruleset", "off"]],
  "rules": {
    "pascal-case-declarations": true,
    "namespace-version": true
  }
}

JavaScript (.spectral.js)

const rules = require('@accordproject/concerto-linter-default-ruleset');
module.exports = {
  extends: [[rules, 'off']],
  rules: {
    'pascal-case-declarations': true,
    'namespace-version': true
  }
};

Adjusting Rule Severity

You can customize the severity level of each rule to control how violations are reported.

• 0 = error (must be fixed)
• 1 = warn (should be addressed)
• 2 = info (useful information)
• 3 = hint (optional suggestion)

YAML (.spectral.yaml)

extends: '@accordproject/concerto-linter-default-ruleset'
rules:
  pascal-case-declarations: 'warn'  # Change from error to warning
  camel-case-properties: 'info'     # Change to informational

JSON (.spectral.json)

{
  "extends": "@accordproject/concerto-linter-default-ruleset",
  "rules": {
    "pascal-case-declarations": "warn",
    "camel-case-properties": "info"
  }
}

JavaScript (.spectral.js)

const rules = require('@accordproject/concerto-linter-default-ruleset');
module.exports = {
  extends: rules,
  rules: {
    'pascal-case-declarations': 'warn',
    'camel-case-properties': 'info'
  }
};

Creating Custom Rules

Whether you want to add new rules to the default ruleset or create an entirely new ruleset, you can follow the Spectral ruleset format. For comprehensive documentation, see the Spectral ruleset documentation.

Here's a simple example of what a custom rule looks like:

# description (optional): Explains what the ruleset is about.
description: "Declaration names (scalar, enum, concept, asset, participant, transaction, event) should be PascalCase."

# given (required): JSONPath expression that specifies where the rule applies.
given: "$.models[*].declarations[*].name"

# message (required): The error/warning message shown when the rule is violated.
message: "Declaration '{{value}}' should be PascalCase (e.g. 'MyDeclaration')"

# severity (optional): The level of violation.
# 0 = error, 1 = warning, 2 = info, 3 = hint
severity: 0

# then (required): Defines what function to apply and how.
then:
  # function (required): The function that validates the rule.
  function: casing

  # functionOptions (optional): Extra options for the function.
  functionOptions:
    type: pascal

For more complex rules, you can create custom JavaScript functions following Spectral ruleset documentation and import it into your rule, similar to how the built-in rules work.

License

Accord Project source code files are made available under the Apache License, Version 2.0 (Apache-2.0), located in the LICENSE file. Accord Project documentation files are made available under the Creative Commons Attribution 4.0 International License (CC-BY-4.0).