Define custom governance rules using Spectral

Spectral is a linting engine that helps you define custom rules and enforce them on JSON and YAML files. Postman supports Spectral v6 rules for the configurable API Governance and Security rules for your team. Postman also supports ES6 syntax and CommonJS syntax for custom functions configurable in custom governance rules.

How Spectral works

Spectral checks that the APIs defined in OpenAPI documents conform to API design guidelines using a specific set of rules. For example, you can use Spectral to check that all properties of all data models are in camel case, or that all operations have a summary.

A Spectral rule targets a given location using a JSON Path Plus expression, then tests the values it finds with a function. It returns an error if the values don’t conform to the rule.

This example shows how to check that the name of an API doesn’t contain the word “API,” regardless of case (for instance, “api” or “Api”):

1
rules:
2
  api-name-doesnt-contain-api:
3
    given: $.info.title
4
    then:
5
      function: pattern
6
      functionOptions:
7
          notMatch: /\b(api)\b/i

First, the rule targets the title property of the info object located at the root ($) of the document with the JSON Path Plus expression $.info.title. In then, the function named pattern checks whether the value of the title property doesn’t match (functionOptions.notMatch) the regular expression looking for the word api in any case (/\b(api)\b/i).

Rulesets in Spectral documents

A Spectral document (often called a ruleset) has a rules property that can have one or more rules. Spectral identifies each rule with a key, which can be any JSON-compatible string.

1
rules:
2
    api-name-doesnt-contain-api:
3
    # ...
4
    api-name-length:
5
    # ...

Spectral support in Postman

Postman supports many of Spectral’s features, though not all.

Whether it’s created within Postman or imported from another source, a Spectral document needs to contain the properties shown in this example:

1
rules:
2
  api-name-doesnt-contain-api:
3
    description: The API name must not contain the word API
4
    message: The info.title value "{{value}}" contains the forbidden word API
5
    severity: error
6
    formats:
7
      - oas2
8
      - oas3
9
    given:
10
      - $.info
11
    then:
12
      - field: title
13
        function: pattern
14
        functionOptions:
15
          notMatch: /\b(api)\b/i

To be valid in Postman, your Spectral document can’t contain any properties beyond those listed here. For the full list of rules and their descriptions, see Spectral rule properties.

You’ll find each rule defined in rules in the Custom Rules section in the configurable API Governance page.

Spectral rule properties

JSON Path and JSON Path Plus

A JSON Path (or JSON Path Plus) expression aims to represent the path to some elements in a JSON or YAML document. For example, $.info.title represents the title property of the info object located at the document’s root ($).

Initially, JSON Path was created to be XPath for JSON and aimed to represent the path to some element in an XML document. JSON Path Plus is an extension of JSON Path. It adds more operators and makes some behaviors of the original specification explicit.

Building and testing JSON Path Plus expressions

You can use the official JSON Path Plus documentation to build and test your rules’ given paths. Syntax Through Examples and the JSON Path Plus demo are both useful.

JSON Path Plus examples

These examples show the typical JSON Path Plus features you’ll need to create rules in Postman:

• $.info.title - The title property inside the info object, which is located at the document’s root ($).
• $.paths.*.*.responses - All responses of all operations of all paths. * gets all elements inside an object or an array.
• $.paths.*[post,patch,put] - All POST, PATCH, and PUT operations across all paths. [ ] can be used to filter elements.
• $..properties - All properties of all schema objects wherever they’re located (for example, in parameters, responses, or reusable components). .. gets all elements in the path tree.

Check for the presence of a property

In the following example, the rule is supposed to check that there’s a description of the API. The way it’s written, though, it will never return a rule violation when the description isn’t present in the info object.

1
# this approach won't work!
2
3
rules:
4
  info-description:
5
    given: $.info.description
6
    then:
7
      function: truthy

If the given path doesn’t find any value, the then checks won’t run. This means you can’t use the path $.info.description to check that the API description is defined in the OpenAPI document. This verification must be done using the path $.info, which will return the info object and the field value set with the name of the field you’re looking for (in this example, description).

1
# this approach will work
2
3
rules:
4
  info-description:
5
    given: $.info
6
    then:
7
      field: description
8
      function: truthy

Spectral custom functions

You can add custom governance functions to your custom governance rules that Postman applies to your API specifications in Spec Hub. You can use these guidelines to write custom functions in JavaScript and add them to your custom governance rules. Postman supports ES6 syntax and CommonJS syntax for custom functions.

Your custom function must have the targetVal parameter, the message property in your return statement, and either the export default declaration (ES6) or module.exports object property (CommonJS) exporting your function.

To add a custom function to a rule, your rule must have the then.function property whose value is the name of the file containing the custom function. The filename is defined using the Name field when you create a custom function.

Spectral function parameters

Use the following parameters in your custom functions depending on your use case. You must add parameters to your custom function in the following order: targetVal, options, then context.

1
function myCustomFunction(targetVal, options, context) { ... }

Spectral function return statement properties

Use the following properties to write the return statement in your custom functions depending on your use case.

1
return [
2
  // Rule violation with the default targetVal path
3
  {
4
    message: `Value must be different from "${values.join(',')}".`,
5
  },
6
  // Rule violation with a custom path leveraging the default targetVal path
7
  {
8
    message: `Value must be different from "${values.join(',')}".`,
9
    path: [...context.path, "a", "custom", "path"]
10
  },
11
];

Export your custom function

Required. Export your custom function. This enables you to add the custom function’s filename to your custom rule using the then.function property. The custom function name you export must match the name in the function declaration.

• For ES6 format, use the following syntax: export default function-name.
• For CommonJS format, use the following syntax: module.exports = function-name.

1
function myCustomFunction(targetVal, options, context) { ... }
2
3
// ES6 syntax
4
export default myCustomFunction;
5
// CommonJS syntax
6
// module.exports = myCustomFunction;

Supported Spectral functions

You can import the following Spectral functions into your custom function file in Postman.

createRulesetFunction

The createRulesetFunction function is an optional Spectral function you can import from the @stoplight/spectral-core module.

Use a JSON Schema to define your custom function’s options, enabling you to validate whether the options provided in your rule using then.functionOptions match specific criteria. The JSON Schema must be nested inside of a JSON object. If the provided options don’t match the JSON Schema, an error message will explain the issue when editing your rule.

Add a JSON Schema for each of the following to your JSON object:

1
  {
2
    // JSON Schema of the targetVal parameter
3
    input: {
4
      type: "string"
5
    },
6
    // JSON Schema of the options parameter
7
    options: {
8
      type: "object",
9
      additionalProperties: false,
10
      properties: {
11
        values: {
12
          type: "array"
13
        }
14
      },
15
      required: ["values"],
16
    },
17
  },

When you export your custom function, call the createRulesetFunction Spectral function and include a JSON object containing JSON Schemas and the custom function’s name as arguments. For a complete example of using a JSON Schema with a custom function, see Check that a value isn’t in a list (JSON Schema).

• ES6 format:
  • To import, use the following syntax: import { createRulesetFunction } from "@stoplight/spectral-core";.
  • To export, use the following syntax: export default createRulesetFunction(json-object, function-name);.
• CommonJS format:
  • To import, use the following syntax: const { createRulesetFunction } = require("@stoplight/spectral-core");.
  • To export, use the following syntax: module.exports = createRulesetFunction(json-object, function-name);.

1
// ES6 syntax
2
import { createRulesetFunction } from "@stoplight/spectral-core";
3
// CommonJS syntax
4
// const { createRulesetFunction } = require("@stoplight/spectral-core");
5
6
function myCustomFunction(targetVal, options, context) { ... }
7
8
// ES6 Syntax
9
export default createRulesetFunction(
10
// CommonJS Syntax
11
// module.exports = createRulesetFunction(
12
  {
13
    // JSON Schema of the targetVal parameter
14
    input: {
15
      type: "string"
16
    },
17
    // JSON Schema of the options parameter
18
    options: {
19
      type: "object",
20
      additionalProperties: false,
21
      properties: {
22
        values: {
23
          type: "array"
24
        }
25
      },
26
      required: ["values"],
27
    },
28
  },
29
30
  myCustomFunction,
31
);

JSON Schema

JSON Schema specification enables you to describe a JSON document using a standard format.

You can add a JSON Schema that defines and validates your custom function’s options. To learn about adding a JSON Schema to your custom function, see the createRulesetFunction Spectral function.

You can use the official JSON Schema documentation to learn more about describing a JSON document using this format.

JSON Schema examples

The following examples show JSON Schema key-value pairs you can use to validate your custom function’s options:

• $.options - The root object that contains the JSON Schema of the options parameter, which is your custom function’s options.
• $.options.type - A validation keyword that defines a constraint on the JSON data. In this example, the value is object, meaning the data must be a JSON object.
• $.options.properties - An object whose values define the parameter used to pass options to your custom function. In this example, values is a variable that stores the value of the options parameter.
• $.options.required - A validation keyword that’s an array of strings containing keys from $.options.properties. Add properties to the array if they must be defined in the JSON Schema. In this example, values must be defined in the JSON Schema.

1
  {
2
    input: {
3
      type: "string"
4
    },
5
    options: {
6
      type: "object",
7
      additionalProperties: false,
8
      properties: {
9
        values: {
10
          type: "array"
11
        }
12
      },
13
      required: ["values"],
14
    },
15
  },

Check that a value isn’t in a list

In the following example, the custom function named notInEnumeration is in a file named not_in_enumeration. The filename is defined using the Name field when you create a custom function.

The custom function checks the value of the option values, which is defined in the Spectral document (or ruleset) using the then.functionOptions property. The value of values is a list of numeric strings. If targetVal is a value already in the list, the rule violation is triggered.

After the custom function, export default or module.exports references the custom function’s name. This exports the custom function, enabling you to add its filename to your rule using the then.function property.

1
// filename: not_in_enumeration
2
3
function notInEnumeration(targetVal, options, context) {
4
  const { values } = options;
5
  if (values.includes(targetVal)) {
6
    return [
7
      {
8
        message: `Value must be different from "${values.join(',')}".`,
9
      },
10
    ];
11
  }
12
}
13
14
// ES6 syntax
15
export default notInEnumeration;
16
// CommonJS syntax
17
// module.exports = notInEnumeration;

Check that a value isn’t in a list (JSON Schema)

In the following example, the custom function named notInEnumeration is in a file named not_in_enumeration. The filename is defined using the Name field when you create a custom function.

Before the custom function, the createRulesetFunction Spectral function is imported into the file. This enables you to define the expected options in a JSON Schema to validate whether the provided options in your rule match specific criteria.

The custom function checks the value of the option values, which is defined in the Spectral document (or ruleset) using the then.functionOptions property. The value of values is a list of numeric strings. If targetVal is a value already in the list, the rule violation is triggered.

After the custom function, export default or module.exports calls the createRulesetFunction Spectral function and includes the following arguments: a JSON object containing JSON Schemas of the targetVal parameter and options parameter, and the custom function’s name. This exports the custom function, enabling you to add its filename to your rule using the then.function property.

1
// filename: not_in_enumeration
2
3
// ES6 Syntax
4
import { createRulesetFunction } from "@stoplight/spectral-core";
5
// CommonJS Syntax
6
// const { createRulesetFunction } = require("@stoplight/spectral-core");
7
8
function notInEnumeration(targetVal, options, context) {
9
  const { values } = options;
10
  if (values.includes(targetVal)) {
11
    return [
12
      {
13
        message: `Value must be different from "${values.join(',')}".`,
14
      },
15
    ];
16
  }
17
}
18
19
// ES6 Syntax
20
export default createRulesetFunction(
21
// CommonJS Syntax
22
// module.exports = createRulesetFunction(
23
  {
24
    // JSON Schema of the targetVal parameter
25
    input: {
26
      type: "string"
27
    },
28
    // JSON Schema of the options parameter
29
    options: {
30
      type: "object",
31
      additionalProperties: false,
32
      properties: {
33
        values: {
34
          type: "array"
35
        }
36
      },
37
      required: ["values"],
38
    },
39
  },
40
41
  notInEnumeration,
42
);

Rule that uses a custom function

In the following example, the Spectral document has a rule named http-status-obsolete that uses a custom function file named not_in_enumeration, which is defined using the Name field when you create a custom function. The custom function file has a custom function named notInEnumeration. The custom function filename is added to the rule using the then.function property.

The custom function accepts options using the then.functionOptions property, defining a property named values that’s a list of numeric strings. The value of then.functionOptions.values is passed to the custom function notInEnumeration. The custom function then checks whether a rule violation occurred at the given path appended with the value of the then.field property.

1
rules:
2
  http-status-obsolete:
3
    formats: [oas2, oas3]
4
    severity: warn
5
    message: "{{property}} is an obsolete or unused HTTP status code"
6
    given: $.paths.*.*.responses
7
    then:
8
      field: "@key"
9
      function: not_in_enumeration
10
      functionOptions:
11
        values: ["306","418","510"]