rules.md

Rules

Rules apply a schema fragment to a set of nodes selected from the original data.

This is a descriptive standard for rules. The enforced meta-rules for rules are located here.

• Rules
  • From File
    • YAML Schema
      • Env Type
      • Include Type
      • Regexp Type
      • Stream Type
    • File Name
    • Schema Definitions
    • Rule Definitions
      • Rule Name
      • Rule Description
      • Rule Level
      • Rule Tags
      • Rule Selector
      • Rule Filter
      • Rule Check
  • From Module
  • From Path

From File

Rules may be loaded from YAML or JSON files, using any extension.

YAML Schema

The default YAML schema has been extended with some custom types.

Env Type

An environment variable by name.

This can be used in CI environments to compare resources against the current job's branch, commit, or tag.

foo: !env CI_COMMIT_SHA

Include Type

Include another file as a child of this key. The file must be a single document.

Relative paths are resolved from __dirname, but no path sanitization is done to prevent ../. Include paths should not be taken from user input.

Regexp Type

A regular expression in a string.

Uses standard JS syntax. Flags are supported.

foo: !regexp /a.*b/gu

Stream Type

A process stream by name (key in process).

One of stderr, stdin, or stdout.

logger:
  streams:
    - level: error
      stream: !stream stderr

File Name

A unique name, used for logging and as the schema $id for definitions.

This should be truly unique, but must be unique within the set of --rules loaded.

name: foo-rules

Schema Definitions

A dict of schema definitions in objects with string keys.

These are added to the Ajv schema and may be referenced by the file name and key:

name: foo

definitions:
  bar:
    type: object

rules:
  - name: foobar
    check:
      type: object
      properties:
        bin:
          $ref: "foo#/definitions/bar"

Rule Definitions

A list of rules.

name: foo

rules:
  - name: foobar
    check:
      type: object

Rule Name

The rule name, used for logging and inclusion.

Must be unique within the file or module.

rules:
  - name: foo

Rule Description

The rule description, used for error messages.

Some descriptive string.

rules:
  - name: foo
    desc: foos must not overfoo

Rule Level

The rule's log level, used for inclusion.

TODO: use for log messages

One of debug, info, warn, or error in a string.

rules:
  - name: foo
    level: debug

Rule Tags

A list of tags for the rule, used for inclusion.

rules:
  - name: foo
    tags:
      - important
      - foo-related
      - definitely-not-bar

Rule Selector

JSON path used to select nodes from the data.

This selects a list of potential nodes to be filtered and checked. The default ($) selects the root of each document. Selecting a subset of children allows the check schema to cover a small fragment of the document.

Uses jsonpath-plus syntax in a string.

rules:
  - name: foo
    select: '$.spec.template.spec.containers[*]'

Rule Filter

Schema used to filter selected nodes.

If a node was selected but but does not match this schema, it will be skipped and the rule will move on to the next node.

Uses ajv syntax in an object.

rules:
  - name: foo
    filter:
      # only check objects with the property bar
      type: object
      required: [bar]

Rule Check

Schema used to check selected nodes.

This is the body of the rule. If a node does not match this schema, the rule will fail.

Uses ajv syntax in an object.

rules:
  - name: foo
    check:
      type: string

From Module

Rules may be loaded from an external module. Any module that can be required can be used by name, using normal Node require rules.

To load a module: --rule-module salty-dog-oot-example

The default export from a rule module must match the schema for rule files:

const { RuleOne, RuleTwo } = require('./rules');

module.exports = {
  name: 'module-name',
  definitions: {
    snippet: {},
  },
  rules: [
    new RuleOne(),
    new RuleTwo(),
  ],
};

An example rule module is available here.

From Path

Rules may be loaded from a directory. Files with .json and .yaml/.yml extensions will be loaded, with file names converted to lowercase before being checked.

To load a directory: --rule-path rules/

Each file will be loaded as an individual rule file. Schema definitions and rules will be loaded normally.