Custom Rules for API Standardization

Custom standardization rules have the same limitations as the built-in rules:

To create rules, you must be an organization owner.

Name

Required. A unique name for this rule, up to 35 characters. The name is also used as a prefix for the rule’s error message.

Specification

Select whether the rule applies to All API definitions, OpenAPI (all), OpenAPI 3.0, OpenAPI 2.0 or AsyncAPI. OpenAPI 2.0 and 3.0 definitions use a slightly different structure and keywords, so some validations may need separate rules for different OpenAPI versions.

Rule Severity

Error or Warning. Errors will prevent the API from being published if the Require API to pass Standardization to be publishable option is selected in the Standardization settings.

Error Message

An optional additional error message displayed in the API Hub for Design editor, up to 130 chars. If omitted, the rule name is used as the error message. If both the name and the error message are specified, the name will prefix the error message. For example, given:

the full error message in the editor will be:

Version -> `info.version` must be major.minor.patch 

Description

Optional. It is a short description of the rule.

Path Required

A JSONPath expression that specifies the target node or nodes to check. For example, $.info.version. Case-sensitive.

We use the jsonpath-plus library that supports some extra selectors in addition to the standard JSONPath syntax. See the jsonpath-plus documentation for the supported syntax.

Test For

Specify pattern to search for the regular expression specified in the Pattern field (below).

Alternately, you can choose defined to to check that the node is present, regardless of the value. For example, check that tag objects have a description specified. See also How "defined" rules work below.

Field

Field to be tested. Set this to @key if you want to test against a field name rather than a value.

Pattern

A regular expression to test against the result of the specified JSONPath. For example, ^\d+\.\d+\.\d+$.

Notes:

Must Match

Regular expression match type: "must match" (check box is selected) or "must not match" (unselected).

Try It Out

Use this section to test the rule against an existing API. You can either paste the API definition into the Try It Out field or use the IMPORT API button to import an API into the Try It Out field for testing purposes.

Save

Save the rule.

If you specify "defined" in the Test For field, then your custom rule verifies the presence of a specific node or nodes in YAML. The specified JSONPath expression is first split into two components: the last component (the target key name) and everything that precedes it (let's call this "base path"). API Hub for Design then finds all the nodes with the "base path" and checks whether each of them contains the target key. The nodes that do not contain this key will fail the validation.

Sample rule: "201 responses to POST requests must include the Location header"

$.paths.*.post.responses.201.headers.Location
\__________________________________/ \______/
 find all the nodes at this path     and check whether
                                     they have this key

Keep in mind that the presence of intermediate nodes is not enforced. For example, the rule above will not flag 201 responses without headers – because these responses will not be found by the "base path" expression ….201.headers.

# Rule will flag this response
responses:
  201:
    description: Created
    headers:
      X-RateLimit-Remaining:
        type: string

# but not this response
responses:
  201:
    description: Created

In this example, the "Location header exists" rule needs to be implemented as two "defined" rules in order to verify that: a) 201 responses have headers; and b) headers include the Location header:

Defined:  $.paths.*.post.responses.201.headers

Defined:  $.paths.*.post.responses.201.headers.Location

You can quickly test custom rules against existing APIs directly in the rule editor. To do that:

The Try It Out section displays YAML nodes found by the specified JSONPath. Leading dashes (-) indicate individual matches. Note that a match can be a standalone value, a simple key: value node, an array, or a multi-property object (including nested objects). The error and warning icons in the gutter indicate the nodes that failed the validation.

The results may look differently depending on whether you test a "defined" rule or a pattern-based rule. For example, when testing the existence of tag descriptions ($.tags[*].description), the results would show all the tag objects ("base" nodes) and indicate those without the description property. However, when testing the values of tag descriptions against a regular expression, the results will show the descriptions themselves.

Note: In API Hub for Design On-Premise, this is supported since v. 1.27.