OpenLint Ruleset Specification

1. Introduction

A ruleset is a set of rules for checking JSON and YAML documents. Each rule selects nodes in a document and checks each selected node with a function. A ruleset records the conventions a group of documents has to follow, so that the documents are checked the same way wherever they are written or reviewed. Nothing in the format depends on what the documents describe.

This specification defines the format apart from any one linter, so that several linters can implement it and agree on what a ruleset means.

1.1. How to read this document

The normative content of this document is its requirements, together with the definitions in § 3 Terminology, the conformance classes in § 2.2 Conformance classes, the tables that requirements refer to, and the ruleset schema that /req/ruleset/schema refers to. Everything else, including this introduction, examples, notes, and issues, is informative.

A requirement looks like this:

Each requirement carries:

• a requirement identifier, such as /req/given/no-match. It is permanent (see § 2.3 Requirement identifiers), and #/req/given/no-match links to it in every version of this document that contains it;

• the conformance class it belongs to, which fixes whether it applies to a ruleset or to a linter;

• the version it first appeared in;

• the conformance tests that check it, listed below it.

A sentence without a keyword inside a requirement defines a term the keyword sentence uses, and binds with it.

The example above only shows the shape. Its status, example, marks that it is not a requirement of this specification. Recommendations (/rec/, written with should) and permissions (/per/, written with may) look the same and belong to a class too.

Every requirement is listed by class in Appendix A: Requirements index, and every test with its fixtures in Appendix B: Conformance tests. Open questions appear as issue blocks where they arise, and the Issues Index at the end of the document collects them. A release carries no issues.

1.2. Versions of this document

Releases are numbered as Semantic Versioning 2.0.0 [SEMVER] prescribes. A patch release corrects the text or the tests without changing what conforms, a minor release adds requirements that every ruleset conforming to the previous release still satisfies, which can include new requirements for linters, and a major release is anything else. Each release has its own URL and never changes once published.

What counts as a change that breaks conformance, and what is promised to whom, is discussed in discussion #12.

Each version publishes its own copy of the ruleset schema next to the document, as ruleset.schema.json. That copy is the one /req/ruleset/schema refers to, and its $id is its own URL. Editors and validators that follow the newest release can use https://spec.openlint.org/v<major>/ruleset.schema.json.

2. Conformance

2.1. Requirement keywords

These keywords appear only inside identified requirements. Text outside a requirement carries no normative force, whatever words it uses.

2.2. Conformance classes

A conformance target is the kind of thing a requirement applies to, either a ruleset or a linter.

ruleset

A ruleset document. A ruleset conforms when it satisfies every requirement whose target is ruleset.

linter

A linter. A linter conforms when it satisfies every requirement whose target is linter.

A conformance class is a set of requirements for one conformance target. An implementation claims conformance to a class as a whole. Each class below names the classes it depends on. When it depends on a class of the same target, conforming to it includes conforming to that class.

A conformance claim names a release of this specification and the classes claimed, as https://spec.openlint.org/<version>/#/conf/<name>. A later release can add requirements to a class, so a claim holds for the release it names.

2.3. Requirement identifiers

A requirement identifier has the form /req/<topic>/<name>. The topic is what the requirement is about, such as a ruleset key (given, overrides) or a step of linting (resolution, result), not a section of this document, so a requirement keeps its identifier when the document is reorganized. The name describes the requirement. Both are lowercase words joined by hyphens.

Identifiers are permanent:

• An identifier is never reused for a different requirement.

• When a requirement’s text changes in a way that changes what conforms, it gets a new identifier and the old one is marked removed.

• A removed requirement stays listed in Appendix A: Requirements index as removed, with the version in which it was removed.

Whether path-style identifiers work for everyone is an open question in discussion #13. Alternatives such as numeric identifiers (REQ-042) or dotted names (given.no-match) have not been raised there yet.

2.4. Conformance tests

Every requirement has at least one conformance test, identified as /conf/<topic>/<name> in the same way. A test is data: a ruleset fixture, for linter tests a document fixture, and the expected outcome. Appendix B: Conformance tests renders every test from that data, and a linter is checked against the same data. A test covers one or more requirements of one class.

A test for a ruleset requirement expects a linter to load or to reject the fixture. A test for a linter requirement expects the results of linting the document fixture with the ruleset fixture, compared on the fields it names.

The tests follow these rules:

• A ruleset requirement has an invalid test, whose fixture violates it and is rejected, and a valid test, whose fixture uses the same property and is loaded. The second shows that a linter does not reject more than the requirement says.

• A linter requirement has a test that expects results, because a linter that does nothing passes a test that expects none.

• A permission has a test in which what is permitted is accepted.

• An invalid fixture violates one requirement only, so that its rejection proves that requirement and not another.

• A recommendation has no test, because ignoring it still conforms.

Whether these tests become a published conformance suite, where its runner would live, and how a linter would publish its results against it, is not decided.

3. Terminology

document

A JSON [RFC8259] or YAML [YAML-1.2.2] document that a linter lints. After parsing, both are the same tree of objects, arrays, strings, numbers, booleans, and null.

ruleset

A JSON or YAML document in the format defined by this specification: a set of rules, the rulesets it extends, and adjustments to both.

rule

A named unit of a ruleset that selects nodes in a document with given and asserts something about each of them with then.

rule name

The key under which a rule appears in rules. The name identifies the rule. It appears in results, and an extending ruleset uses it to adjust the rule.

path expression

A string in given that selects nodes: a JSONPath expression beginning with $, or an alias reference beginning with #.

alias

A named, reusable set of path expressions, declared under aliases.

alias reference

A path expression of the form #<name> followed by an optional JSONPath remainder, such as #Info.description.

matched node

A node of the document selected by one of a rule’s path expressions.

function

A named assertion applied to a matched node by then. A function is either one of the core functions or a custom function.

custom function

A function whose implementation a ruleset supplies as code, named under functions.

result

What a linter reports about a document: a problem a function found in a matched node, or a problem the linter found itself, such as a syntax error. A result has a code, a message, a severity, and a location in the document. See § 6.8 Results.

severity

How a rule’s results are reported: error, warn, info, or hint. The severity off disables the rule.

effective severity

The severity a rule has after every ruleset in the chain of extends and every override has adjusted it.

enabled

The state of a rule that a linter evaluates. A rule is either enabled or not, independently of its severity. A rule with effective severity off is not enabled.

format

A named kind of document, such as oas3_1 for an OpenAPI 3.1 description. A rule scoped to formats runs only against documents of those kinds.

override

An entry of overrides: adjustments that apply to the subset of documents matched by its files globs.

resolved document

The document after every $ref has been replaced by the value it points to, including references into other files. See § 5.3 Reference resolution.

extension property

A property whose name begins with x-, carried by the format for the author’s own tooling and ignored by a linter.

linter

Software that takes a ruleset and one or more documents and produces results.

shorthand

A value in rules that is not a Rule Object: a severity name or a boolean, which adjusts a rule the ruleset inherits instead of defining one.

mode

The second element of an extends entry, recommended, all, or off, which decides which of the inherited rules start out enabled.

file-scoped override

An override whose files globs do not all carry a JSON Pointer fragment. It can change anything a ruleset declares, for the documents it matches.

pointer-scoped override

An override whose files globs all carry a JSON Pointer fragment. It can only change severities, at the locations the pointers name.

core function

A function this specification defines, which every conforming linter provides under its name.

function invocation

One entry of a rule’s then: the function to apply, the field to apply it to, and its functionOptions.

problem

What a function returns for a value that fails: a message, and optionally the path of the offending value. A linter reports each problem as a result.

requirement

An identified statement of this specification that one conformance target has to satisfy to conform. Recommendations and permissions are identified the same way but are not requirements.

4. The ruleset format

This part defines what a ruleset document looks like, in the order of the document itself: the document, the Ruleset Object at its root and each of its properties, the Rule Object and each of its properties.

4.1. The ruleset document

A ruleset is one file, written in JSON or YAML.

/req/ruleset/single-document is proposed, because it changes current behavior. Spectral and OpenLint accept a YAML file with several documents separated by ---, read the first, and drop the others without reporting them; neither documents this. A ruleset split by a stray --- therefore loses rules silently, and rejecting the file catches that. Until both linters change, /conf/ruleset/document-two-yaml-documents fails against them. Whether this counts as a breaking change for 1.x is part of discussion #12.

The ruleset schema is written in JSON Schema 2020-12 and published with each version of this specification, next to this document as ruleset.schema.json. It validates the value at the root of the document.

documentationUrl takes only an absolute http, https, or ftp URL with a public host, which is how the url format of OpenLint’s validator reads a URL. The schema spells that out as a pattern. It rejects mailto: and urn: URIs, localhost, single-label intranet hosts such as http://wiki/docs, private and loopback addresses, and punycode host names; see /conf/ruleset/documentation-url-intranet. Accepting any absolute URI [RFC3986] would let a ruleset link to internal documentation.

4.2. The Ruleset Object

The Ruleset Object is the root of a ruleset. It holds the rules the ruleset defines, the rulesets it extends, and the adjustments it makes to them, and it can have a description and a documentationUrl.

At least one of extends, rules, or overrides is required. No other properties are allowed.

description: Acme API style guide
documentationUrl: https://engineering.acme.com/api/governance
extends: [[spectral:oas, recommended]]
formats: [oas3]
rules:
  acme-operation-summary:
    description: Every operation needs a summary.
    severity: error
    given: "$.paths[*]['get','put','post','delete','options','head','patch','trace']"
    then:
      field: summary
      function: truthy

4.2.1. extends

extends inherits from one or more other rulesets. Its value is a string that identifies a ruleset, or an array. Each element of the array is such a string, or an array of the string and a mode. Elements after the mode are ignored.

Elements after the mode are accepted and ignored, so [./base.yaml, all, extra] reads as [./base.yaml, all]. OpenLint accepts them although its own validation schema forbids them for this array. Rejecting them would catch a misplaced bracket.

The string identifies a ruleset as a built-in identifier (spectral:oas, spectral:asyncapi, spectral:arazzo), a file path, an npm module specifier, or a URL. The mode decides which of the inherited rules start out enabled:

extends:
  - [spectral:oas, all]
  - [./team-baseline.yaml, "off"]
  - https://example.com/rulesets/security.yaml

With off, a ruleset can extend a large ruleset and enable only the rules it names. § 6.2 Loading a ruleset defines loading, and § 6.4 Rule state: enabled and severity the effect of the modes.

4.2.2. rules

rules maps a rule name to either a Rule Object, which defines a rule or redefines an inherited one, or a shorthand, which adjusts a rule inherited through § 4.2.1 extends. Other rulesets refer to a rule by its name to disable it or change its severity, so renaming a rule breaks them.

A linter also reports problems of its own, such as a syntax error in the document, under fixed codes listed in § 6.8 Results. A rule with one of those names is accepted, but its results cannot be told apart from the linter’s own by their code.

4.2.2.1. Shorthands

A value in rules that is not an object is a shorthand: one of the severity names error, warn, info, hint, off, or one of the booleans true and false. It adjusts a rule instead of defining one.

A shorthand in the rules of a file-scoped override names a rule the ruleset defines or inherits. That is checked when the override applies to a document; see /req/overrides/checked-when-applied.

Note: Severities are not written the same way everywhere. A rule’s severity takes a name or a number. A shorthand, in the root rules or in a file-scoped override, takes a name or a boolean but not a number. The rules of a pointer-scoped override take a name or a number but not a boolean.

A numeric shorthand such as r: 0 is rejected only by OpenLint’s validation schema. Its type definitions and its merge code accept a number and would apply it as the severity. Accepting numbers in shorthands would remove the difference with severity without making any ruleset invalid.

extends: spectral:oas
rules:
  operation-tags: error       # raise it
  info-contact: false         # switch it off
  oas3-schema: true           # switch it back on, at its current severity

What each shorthand does is defined in § 6.4 Rule state: enabled and severity.

4.2.3. aliases

An alias names a list of path expressions, so that several rules can share it. A rule references an alias from given with a leading #. Aliases are also under discussion in discussion #2.

An alias name starts with a letter, followed by letters, digits, _, and -. A simple alias is a non-empty array of path expressions.

aliases:
  Info:
    - $..info
  InfoDescription:
    - "#Info.description"
  PathItemObject:
    - $.paths[*]
  OperationObject:
    - "#PathItemObject['get','put','post','delete','options','head','patch','trace']"

A scoped alias resolves to different expressions depending on the format of the document being linted. One rule can then select, for example, the parameters of both OpenAPI 2 and OpenAPI 3 documents. A scoped alias is an object:

Each of its targets is an object:

aliases:
  ParameterObject:
    description: Every Parameter Object, wherever this spec version keeps them.
    targets:
      - formats: [oas2]
        given:
          - $.parameters[*]
      - formats: [oas3]
        given:
          - $.components.parameters[*]

Aliases are declared at the root of the ruleset or within a file-scoped override. How they expand is defined in § 6.6 Selecting nodes, and which rules an override’s aliases reach in § 6.3 Applying overrides.

4.2.4. overrides

Overrides apply adjustments to a subset of the documents being linted, matched by glob. overrides is a non-empty array of objects, each with a non-empty array files of glob patterns.

files entries are glob patterns, matched as minimatch 3.1.5 [MINIMATCH] matches them, against the path of the document relative to the directory of the ruleset file, with / as the separator. minimatch has no specification of its own, so the glob dialect is what that version accepts.

A glob dialect with a specification of its own, or a written subset of minimatch’s, would let a linter in another language match files without reproducing minimatch.

There are two forms, distinguished by whether every glob in files carries a JSON Pointer [RFC6901] fragment. An override that mixes the two kinds of glob is file-scoped.

An override whose files do not all carry a # fragment is a file-scoped override. It has at least one of extends and rules, and it can also have formats, parserOptions, and aliases.

Note: The schema accepts other properties on a file-scoped override. When the override applies to a document, a property the Ruleset Object does not have makes a linter reject the ruleset, while one it does have, such as description, is accepted; see /req/overrides/checked-when-applied.

overrides:
  - files: ["legacy/**/*.yaml"]
    rules:
      acme-operation-summary: warn
  - files: ["v3/**/*.yaml"]
    formats: [oas3_1]
    extends: [[./strict.yaml, all]]

An override whose files all carry a # fragment is a pointer-scoped override. It has rules, whose every value is a severity name or number, and no other property than files.

overrides:
  - files: ["api.yaml#/paths/~1legacy~1users"]
    rules:
      acme-operation-summary: "off"

A pointer-scoped override can change a rule’s severity at one location in one file, or switch the rule off there. It cannot change what the rule checks. § 6.3 Applying overrides defines how overrides are applied.

4.2.5. parserOptions

Severities for problems found while parsing the document, before any rule runs; see § 5.2 Parsing.

No other properties are allowed.

4.2.6. functions and functionsDir

A serialized ruleset names the custom functions it uses in functions, and can name the directory they load from in functionsDir; see § 7.2 Custom functions.

functions:
  - dictionary
functionsDir: ./my-functions   # optional; defaults to "functions"
rules:
  no-evil-words:
    message: "{{error}}"
    given:
      - $.info.title
      - $.info.description
    then:
      function: dictionary

OpenLint runs custom functions without isolation. Whether a conforming linter has to sandbox them, or refuse functions that come from a remote ruleset, is open.

4.3. The Rule Object

A rule selects nodes in a document with given and checks each selected node with then.

No other properties are allowed.

What message and description contribute to a result is defined in § 6.8 Results, how recommended combines with extends in § 6.4 Rule state: enabled and severity, and what resolved changes in § 6.6 Selecting nodes.

Note: tags, type, and extensions carry no behavior in this specification. They exist for tooling built around rulesets.

4.3.1. given

given says where in the document a rule looks. It is a JSONPath expression, such as $.paths[*]['get','put','post','delete','options','head','patch','trace'] for every operation of an OpenAPI description, or a reference to an alias that names one, such as #Operation. JSONPath-Plus has no grammar document, so the dialect is what that implementation accepts; § 6.6 Selecting nodes pins it. then checks each node the expression selects on its own. § 6.6 Selecting nodes defines how the expression is evaluated.

The value of given is a path expression or a non-empty array of them. A path expression that begins with $ is a JSONPath expression, and one that begins with # is an alias reference.

A redefined rule keeps resolving its alias references against the ruleset that first defined it, so redefining an inherited rule with an alias reference works only when both rulesets declare the alias, and then uses the inherited ruleset’s. Resolving against the redefining ruleset’s aliases would let an extending ruleset retarget a rule with aliases of its own.

A bare property name such as paths is not a path expression. It begins with neither $ nor #, so the ruleset schema rejects it, and so does a conforming linter.

given:
  - $.info
  - "#OperationObject"

4.3.2. then

then is one function invocation, or an array of them. A linter applies each of them to every node given matched, as § 6.7 Applying functions defines. A function invocation is an object:

then: [] is accepted, and the rule then asserts nothing and never reports a result. Rejecting an empty array would catch a rule left unfinished.

An unknown property inside an invocation, such as functionOption without the s, is ignored. When the function has no required option it runs with its defaults; when it has one, the ruleset is rejected for the missing functionOptions with a message that does not point at the misspelling. Rejecting the unknown property would catch the misspelling in both cases.

then:
  - field: summary
    function: truthy
  - field: summary
    function: length
    functionOptions:
      max: 120

4.3.3. severity

severity says how serious a result from this rule is, and whether the rule runs at all. A ruleset can write either; results carry the numbers.

A rule’s severity is one of the names or one of the numbers.

What a severity means for a rule, and how it combines with extends, shorthands, and overrides, is defined in § 6.4 Rule state: enabled and severity.

4.3.4. formats

formats limits a rule to documents of certain kinds, so that a rule about OpenAPI paths does not run on an AsyncAPI document linted with the same ruleset.

formats is an array of format identifiers. It can appear on a ruleset, a rule, a file-scoped override, and an alias target.

The identifiers are listed in § 5.4 Formats; which rules run against which documents is defined in § 6.5 Selecting documents.

4.4. Extension properties

Use them to carry ownership, tickets, review dates, or anything else your own tooling needs. Rules also have an extensions object for the same purpose. A linter ignores both. Elsewhere they are not part of the format. The ruleset schema rejects them in parserOptions and in a pointer-scoped override. A file-scoped override, a scoped alias, and an invocation under then accept them, and a linter ignores them there too.

x-owner: platform-team
rules:
  acme-operation-summary:
    x-jira: GOV-142
    given: $.paths[*]['get','put','post','delete','options','head','patch','trace']
    then:
      field: summary
      function: truthy

5. Documents

A linter lints documents with the rulesets of § 4 The ruleset format. This section says what a document is to a linter, what happens to it before any rule runs, and how its formats are found.

5.1. The document model

A document is written in JSON [RFC8259] or YAML [YAML-1.2.2]. After parsing, both are the same tree of objects, arrays, strings, numbers, booleans, and null, and that tree is what path expressions select from and what functions see. A linter keeps the mapping from every node back to its position in the source text, because a result reports that position.

Note: Rulesets authored in JavaScript can inline function implementations and whole ruleset objects, which have no JSON representation and are out of scope. Only serialized documents and rulesets are specified.

The root of a document can be any value, including an array, a scalar, or null, which is what an empty file parses to. $ selects it whatever it is.

A UTF-8 byte order mark is accepted, but OpenLint then reports range columns on every line after the first one too far to the left. A UTF-16 document is not rejected; it parses as garbage and produces parser results. Ignoring a byte order mark and rejecting other encodings would make both deterministic.

5.2. Parsing

Problems in a document’s syntax are reported as results with the code parser. A problem that leaves the document with a JSON reading, such as a key that appears twice, still lets the document be linted; parserOptions sets its severity.

Whether rules run against the part of a document before a syntax error is not stated. OpenLint runs them against whatever tree its parser recovers, which for an unterminated flow collection can be nothing.

Non-string scalar keys are the one construct OpenLint reports under incompatibleValues. A mapping key that is itself a sequence or a mapping is reported as a warning by the YAML parser, with no option controlling it, and a !!binary or !!set tag ends the run with an error before any result. Whether those constructs belong under incompatibleValues, and whether a tag the linter cannot represent is a parser result, is open.

5.3. Reference resolution

The resolved document is the document after every $ref has been replaced by the value it points to, including references into other files. By default a rule sees the resolved document; a rule that sets resolved: false sees the document as written.

A reference is an object with a $ref property whose value is a URI reference [RFC3986]: a fragment that is a JSON Pointer [RFC6901] into the same document, or a relative or absolute reference to another document, with an optional fragment into it.

What a rule sees at the position of a reference in a cycle, and whether resolution follows $ref in every position or only where the document’s format expects one, is not stated.

5.4. Formats

A format names a kind of document, and a linter decides from the document whether it is of that kind, by the condition the table gives. A condition reads the document’s root object; a document whose root is not an object has no format. The string form of a value is the value as JSON writes it, without quotes for a string, so an unquoted 3.0 in YAML is the number 3. A rule scoped to a format runs only against documents of that format, so one ruleset can hold rules for OpenAPI 3.1 and for AsyncAPI 2.6 without either set running on the other kind of document. The table lists the identifiers a ruleset can use, which are the ones the ruleset schema accepts, and how each is detected.

Any other identifier, such as the typo oas31, makes the ruleset invalid, wherever formats appears. How a rule names formats is defined in § 4.3.4 formats; how a linter detects them and which rules run is defined in § 6.5 Selecting documents.

The set of identifiers is closed, because OpenLint rejects an identifier it does not register. The previous document and schema accepted any string, so that formats added later, or registered by a host application, would stay valid. Which of the two this specification wants is open.

6. Linting

This part defines what a linter does with a ruleset and a document, in the order it happens:

1. Load the ruleset: check it and load what it extends.

2. Read the document: parse it, resolve its references, and detect its formats.

3. Apply the overrides whose globs match the document.

4. Work out the rule state: which rules are enabled, and at what severity.

5. Select documents: decide, by format, which rules apply to the document.

6. Select nodes: evaluate each rule’s given.

7. Apply functions: run each rule’s then on every node it matched.

8. Report the results.

6.1. A running example

The sections of this part follow one scenario through the pipeline. A team keeps its shared rules in a base ruleset:

rules:
  operation-summary:
    description: Every operation needs a summary.
    severity: warn
    given: $.paths[*]['get','put','post','delete','options','head','patch','trace']
    then:
      field: summary
      function: truthy
  operation-id-camel-case:
    description: operationId is written in camelCase.
    recommended: false
    given: $.paths[*]['get','put','post','delete','options','head','patch','trace'].operationId
    then:
      function: casing
      functionOptions:
        type: camel

A project extends it. It switches on the rule the base leaves off, adds a rule of its own through an alias, scopes its own rules to OpenAPI 3, and raises one severity for the documents under legacy/:

extends: ./acme-base.yaml
formats: [oas3]
aliases:
  Operation:
    - "$.paths[*]['get','put','post','delete']"
rules:
  operation-id-camel-case: true
  operation-has-tags:
    description: Every operation is tagged.
    severity: hint
    given: "#Operation"
    then:
      field: tags
      function: defined
overrides:
  - files: ["legacy/**"]
    rules:
      operation-summary: error

The document being linted is legacy/petstore.yaml. Its get operation has no summary, no tags, and a snake_case operationId; its post operation has all three:

openapi: 3.1.0
info:
  title: Petstore
  version: 1.0.0
paths:
  /pets:
    get:
      operationId: list_pets
      responses:
        "200":
          description: OK
    post:
      summary: Add a pet
      operationId: addPet
      tags: [pets]
      responses:
        "201":
          description: Created

The scenario is also the conformance test /conf/linter/walkthrough, which checks the outcome this part describes.

6.2. Loading a ruleset

Loading turns the ruleset file into the set of rules that will run. A linter first checks the ruleset against § 4 The ruleset format. It then loads the rulesets it extends, recursively, so that their rules are available under their names. Overrides are applied next, per document; see § 6.3 Applying overrides.

How a linter resolves file paths, npm module specifiers, and URLs, and what each is relative to, is implementation-defined and has to be specified. So is whether every conforming linter has to recognize the built-in identifiers, which name rulesets shipped with OpenLint; discussion #6 uses openlint:openapi as the name of a new core OpenAPI ruleset. Resolving an npm module specifier also ties linter-core to the JavaScript package ecosystem, so it could move to a class of its own, as custom functions have.

In OpenLint, a cycle through extends between ruleset files is neither detected nor reported: the loader follows it until the process runs out of memory, so the ruleset never loads. Its core skips a definition it is already loading, but only for definitions held in memory. A conforming linter has to reject cycles, or the ruleset has to be invalid; which is open.

6.3. Applying overrides

An override changes the ruleset for the documents its files globs match, so a linter applies overrides per document, after loading and before working out the rule state. A file-scoped override can add rulesets, rules, aliases, and formats; a pointer-scoped override only changes severities at the locations its pointers name.

An override with extends and no rules drops, for the documents it matches, every rule the ruleset inherits through its own extends, while its own rules stay. With rules, it adds to them. Adding in both cases would make the two forms consistent.

An alias declared in an override does not reach the rules the ruleset defines, so overriding an alias by name changes nothing for them. The previous document said an override’s aliases merge by name with the ruleset’s. Applying them to every rule, for the documents the override matches, would make that true.

These three checks run only when the override applies to a document, as they do in OpenLint. Whether a Rule Object in an override’s rules merges with the rule it redefines, as /req/rules/redefinition-merge says for extends, or replaces it, is not tested. A ruleset with such an error loads without error until the first document the override matches. Everything else in an override is checked when the ruleset loads. Checking these three at load time too would report the error before any document matches.

6.4. Rule state: enabled and severity

Every rule in the loaded ruleset ends up with two things: whether it is enabled, and its effective severity. Four mechanisms set them, in this order: the rule’s own definition, the mode its ruleset was extended with, the shorthands of each ruleset in the chain, and the overrides that match the document.

A redefinition keeps every property it does not set, so the base’s message or severity survives a redefinition that changes given and then, and can stop matching what the rule now checks. Replacing the whole rule would make a redefinition independent of the rule it replaces.

6.5. Selecting documents

Not every rule applies to every document. A linter detects the formats of the document and keeps the rules that have no formats or whose formats include one of them, so that one ruleset can hold rules for several kinds of document. § 5.4 Formats says what a format is and which identifiers exist.

Because detection is limited to the identifiers a ruleset names, a scoped alias whose target names a format no rule names never uses that target, even for a document of that format. Detecting every identifier in the table would make scoped aliases independent of the rules that use them.

The conditions in the table are the ones OpenLint applies. They read the string form of a version value, so openapi: 3.0 written as a YAML number is OpenAPI 3 but not 3.0, and they accept openapi: 3abc. Conditions on the typed value would be stricter. Which document types the format supports is discussed in discussion #5.

6.6. Selecting nodes

For each rule that applies, the linter evaluates every path expression in given against the document and collects the nodes they select, the matched nodes. An alias reference is expanded first. A rule looks through $ref as if the referenced content were inline, unless it sets resolved: false.

JSONPath-Plus has no specification of its own, and its filter expressions are JavaScript. OpenLint evaluates most expressions with Nimma and falls back to JSONPath-Plus for the rest; a filter in the syntax of JSONPath [RFC9535], ?@.in == 'header', matches nothing in it. Making RFC 9535 normative would give the dialect a specification, at the cost of the rulesets that use JavaScript filters.

Note: Aliases are resolved against the ruleset that defines the rule, not the ruleset that extends it. A rule inherited through extends keeps the aliases of the ruleset it came from.

Only the last matching target counts, so a document with two formats, such as oas3 and oas3_1, uses one target even when two match. Using every matching target, or the first, would read more naturally as a list.

6.7. Applying functions

A function is applied to one value: the matched node, or each value field selects in it, or each of its keys for @key. It receives that value and the invocation’s functionOptions, and it returns the problems it found, each with a message. Every problem becomes a result of the rule. A function that returns no problems passes. § 7.1 Core functions specifies each core function by what it asserts. A custom function has only this contract; see § 7.2 Custom functions.

Note: @key goes with a given that selects the parent. With given: $.paths and field: "@key", the function checks every path. With given: $.paths[*], it would check the keys inside each path item.

6.8. Results

A linter reports what it found as results. This section defines the result model that discussion #13 asked for.

Indices in path are strings, ["names", "1"], as OpenLint reports them. Numbers would tell an index apart from a key that happens to be numeric.

6.8.1. The message

message takes five placeholders:

{{value}} substitutes a string as it is and an object as [object Object], which no ruleset wants. A JSON serialization of the value would be useful, and is a change in output.

message: "{{description}}: `{{property}}` was {{value}}"

[
  {
    "code": "operation-has-tags",
    "path": ["paths", "/pets", "get"],
    "message": "Every operation is tagged.",
    "severity": 3,
    "range": {
      "start": { "line": 6, "character": 8 },
      "end": { "line": 10, "character": 25 }
    },
    "source": "legacy/petstore.yaml"
  },
  {
    "code": "operation-summary",
    "path": ["paths", "/pets", "get"],
    "message": "Every operation needs a summary.",
    "severity": 0,
    "range": {
      "start": { "line": 6, "character": 8 },
      "end": { "line": 10, "character": 25 }
    },
    "source": "legacy/petstore.yaml"
  },
  {
    "code": "operation-id-camel-case",
    "path": ["paths", "/pets", "get", "operationId"],
    "message": "operationId is written in camelCase.",
    "severity": 1,
    "range": {
      "start": { "line": 7, "character": 19 },
      "end": { "line": 7, "character": 28 }
    },
    "source": "legacy/petstore.yaml"
  }
]

7. Functions

A rule names a function in then. It is either a core function, which every conforming linter provides, or a custom function, which a ruleset supplies as code. § 6.7 Applying functions defines how a function is applied.

7.1. Core functions

A conforming linter provides these functions under these names. Each function has a purpose, the values it applies to, its options, and one requirement that states what it asserts. The options tables are normative through /req/then/function-options-valid.

7.1.1. truthy

The value is present and is not false, "", 0, or null. Use it for required fields such as a summary or a contact.

It applies to any value, and to an absent one.

This function takes no options.

operation-summary:
  given: $.paths[*]['get','put','post','delete','options','head','patch','trace']
  then:
    field: summary
    function: truthy

7.1.2. falsy

The value is absent, false, "", 0, or null, so falsy passes where truthy fails. Use it to forbid a field, or to require that a flag is off.

It applies to any value, and to an absent one.

This function takes no options.

Note: truthy and falsy follow ECMAScript truthiness [ECMA-262-2025]. Their requirements list the values in full because languages differ on whether an empty array or object is truthy.

no-deprecated-operations:
  given: $.paths[*]['get','put','post','delete','options','head','patch','trace']
  then:
    field: deprecated
    function: falsy

7.1.3. defined

The value is present, whatever it is. Unlike truthy, an empty string or false passes.

It applies to any value, and to an absent one.

This function takes no options.

servers-declared:
  given: $
  then:
    field: servers
    function: defined

7.1.4. undefined

The value is absent. Use it to forbid a property.

It applies to any value, and to an absent one.

This function takes no options.

no-host:
  given: $
  then:
    field: host
    function: undefined

7.1.5. pattern

The value is a string that matches, or does not match, a regular expression.

It applies to strings.

A regular expression is written bare, ^[a-z-]+$, or between slashes with flags, /^[a-z-]+$/i, with the flags of ECMAScript.

pattern takes the regular expressions and flags of ECMAScript, so a linter written in another language has to reproduce ECMAScript’s semantics. I-Regexp [RFC9485] is a dialect meant to behave the same in every language, but it has no lookaround or backreferences, so rulesets that use them would break. Which dialect a later version adopts is open.

paths-kebab-case:
  given: $.paths
  then:
    field: "@key"
    function: pattern
    functionOptions:
      match: "^/[a-z-]+(/[a-z-{}]+)*$"

7.1.6. casing

The value is a string written in a named case convention.

It applies to non-empty strings.

The exact character classes of each case have to be stated before this requirement is complete.

operation-id-camel-case:
  given: $.paths[*]['get','put','post','delete','options','head','patch','trace'].operationId
  then:
    function: casing
    functionOptions:
      type: camel

7.1.7. length

The size of the value is within bounds: the number of characters of a string, of elements of an array, of properties of an object, or the value of a number.

It applies to strings, arrays, objects, and numbers.

short-summary:
  given: $.paths[*]['get','put','post','delete','options','head','patch','trace'].summary
  then:
    function: length
    functionOptions:
      max: 120

7.1.8. alphabetical

The elements of an array, or the keys of an object, are in ascending order.

It applies to arrays and objects.

localeCompare without a locale uses the locale of the environment, so the order of strings such as ä and z can differ between machines. A fixed collation, such as code point order, would make the function portable at the cost of changing the order of mixed-case names.

tags-alphabetical:
  given: $.tags
  then:
    function: alphabetical
    functionOptions:
      keyedBy: name

7.1.9. enumeration

The value is one of a fixed set.

It applies to strings, numbers, booleans, and null.

audience-known:
  given: $.info.x-audience
  then:
    function: enumeration
    functionOptions:
      values: [internal, partner, public]

7.1.10. schema

The value validates against a JSON Schema. Use it when the shape to assert is more than one property deep.

It applies to any present value, and fails on an absent one.

The drafts dialect accepts, and the specification of each:

contact-shape:
  given: $.info.contact
  then:
    function: schema
    functionOptions:
      schema:
        type: object
        required: [name, email]
        properties:
          email:
            type: string
            format: email

7.1.11. xor

Exactly one of a set of properties is present.

It applies to objects.

example-or-examples:
  given: $.paths[*]['get','put','post','delete','options','head','patch','trace'].responses[*].content[*]
  then:
    function: xor
    functionOptions:
      properties: [example, examples]

7.1.12. or

At least one of a set of properties is present.

It applies to objects.

operation-documented:
  given: $.paths[*]['get','put','post','delete','options','head','patch','trace']
  then:
    function: or
    functionOptions:
      properties: [summary, description]

7.1.13. unreferencedReusableObject

Every member of a container of reusable definitions is referenced somewhere. Use it to find unused schemas, parameters, or responses.

It applies to objects.

Note: The function counts references, which no longer exist in the resolved document, so the rule in the example sets resolved: false. Members referenced only by documents outside the lint run count as unreferenced.

no-unused-schemas:
  resolved: false
  given: $.components.schemas
  then:
    function: unreferencedReusableObject
    functionOptions:
      reusableObjectsLocation: "#/components/schemas"

7.2. Custom functions

A ruleset declares the custom functions it uses as described in § 4.2.6 functions and functionsDir.

Custom functions are specified in two parts. The contract, the class /conf/linter-custom-functions, says how a linter resolves a function a ruleset names, calls it, and reports what it returns, whatever language the function is written in. A binding says how a function is written and found in one language. This version defines one binding, for JavaScript, the class /conf/linter-custom-functions-javascript. A linter claims the contract together with a binding, and can decline both.

A linter written in Go needs a Go binding, and this version defines none. vacuum, a linter written in Go, loads custom functions as Go plugins from a directory named on its command line, registered under the name each function reports, and does not read functions or functionsDir. A Go binding would have to say where a linter finds a function, which symbol it loads, and the function’s signature in types this specification owns. Go plugins also load only into a binary built with the same Go version and package versions, so a plugin built for one linter does not load into another.

A binding ties a function to one language, so a ruleset whose functions are written in that language runs only on linters that bind it. A binding to WebAssembly, or to a function that runs as a separate process, would let any linter run functions written in any language that targets it. Whether a later version defines such a binding is open.

7.2.1. The contract

A function that throws, or returns something that is not a list of problems, ends the run with no results and an error. Reporting it as a result for the rule, with the error as its message, would keep the results of the other rules.

Note: The contract is tested through the JavaScript binding, the only binding this version defines, so the fixtures of its tests are JavaScript functions.

7.2.2. JavaScript binding

A custom function is a JavaScript module whose export is the function. It receives the value and the options, and returns an array of problems, each an object with a message; an empty array means the value passes.

// functions/forbiddenWords.js
module.exports = (value, options) => {
  const problems = [];
  for (const word of options.forbidden) {
    if (String(value).includes(word)) {
      problems.push({ message: `Contains "${word}".` });
    }
  }
  return problems;
};

A function module in CommonJS and one in ES module syntax both load in OpenLint, and the function receives a third argument with the document, the rule, and the path. Neither is stated normatively.

8. Security and privacy considerations

A ruleset is configuration, but loading one can read files, fetch URLs, and run code. Anyone who lints with a ruleset they did not write, or extends one, trusts its author with all of that. This section collects what a linter and its users have to be aware of. It states no requirements.

Custom functions run code. A ruleset that names custom functions depends on code, and its document alone does not say what those rules check. This specification does not require a linter to isolate that code, so extending an untrusted ruleset that has custom functions runs that code with the linter’s privileges, and functionsDir resolved relative to a remote ruleset loads code from that remote location.

extends fetches rulesets. An extends entry that is a URL makes the linter fetch it, and an npm module specifier makes it load a package. Nothing in the format pins what is fetched, so a ruleset fetched twice can differ, and a compromised host or package changes what every document is checked against. A ruleset that is extended by file path is read from wherever the path leads.

Path expressions and regular expressions evaluate input. A JSONPath-Plus filter expression in given is JavaScript evaluated by the linter, and a pattern option is an ECMAScript regular expression, which can take exponential time on crafted input. Both come from the ruleset, so a ruleset is as trusted as code even without custom functions.

References read other documents. Resolving a $ref to an external file or URL reads it, so linting an untrusted document can make the linter read any file it has access to and fetch from any host it can reach. The schema function’s option can carry $ref too.

Results carry locations. source is the location of the document, which can be an absolute path or a URL, and results are often written to logs and CI output that others can read.

Appendix A: Requirements index

4 conformance classes, 93 requirements, 3 recommendations, 1 permission, and 238 conformance tests. The same data is available as requirements.json, and the tests with their fixtures under conformance/.

/conf/ruleset-core

The ruleset format: what a ruleset document has to look like to be loaded by any conforming linter. Most of it is one requirement, validity against the ruleset schema. The other requirements are constraints a schema cannot express. Target: ruleset Depends on: none.

/conf/linter-core

Everything a linter does with a ruleset and a document: loading, parsing and resolution, rule state, selecting documents and nodes, applying functions, and the results and messages it reports. It depends on ruleset-core because a linter rejects a ruleset that does not conform to that class. #loading says how. Target: linter Depends on: ruleset-core.

/conf/linter-custom-functions

The contract of custom functions, in any language: how a linter resolves a function a ruleset names, calls it, and reports what it returns. A linter claims it together with a binding. Target: linter Depends on: linter-core.

/conf/linter-custom-functions-javascript

The JavaScript binding of custom functions: how a custom function is written as a JavaScript module, and where a linter finds it. Target: linter Depends on: linter-custom-functions.

Appendix B: Conformance tests

Tests are grouped under the requirement they cover. Open a test to see its fixtures and expected outcome.

Expand all Collapse all

Conformance class /conf/ruleset-core

{
  "rules": {
    "acme-operation-summary": {
      "given": "$.paths[*][*]",
      "then": {
        "field": "summary",
        "function": "truthy"
      }
    }
  }
}

rules:
  acme-operation-summary:
    description: Every operation needs a summary.
    given: $.paths[*]['get','put','post','delete','options','head','patch','trace']
    then:
      field: summary
      function: truthy

rules:
  r: [

---
rules:
  r:
    given: $.info
    then:
      field: title
      function: truthy

rules: {}
---
rules: {}

aliases:
  Info_v2-x:
    - $.info
rules:
  r:
    given: "#Info_v2-x"
    then:
      function: truthy

aliases:
  ParameterObject:
    targets:
      - formats: [oas2]
        given:
          - $.parameters[*]
      - formats: [oas3]
        given:
          - $.components.parameters[*]
rules:
  parameter-name:
    formats: [oas2, oas3]
    given: "#ParameterObject"
    then:
      field: name
      function: truthy

aliases:
  Info:
    - $.info
    - $.externalDocs
rules:
  r:
    given: "#Info"
    then:
      function: truthy

aliases:
  1bad:
    - $.info
rules:
  r:
    given: "#1bad"
    then:
      function: truthy

aliases:
  Info:
    targets:
      - given:
          - $.info
rules:
  r:
    given: "#Info"
    then:
      function: truthy

aliases:
  Info: $.info
rules:
  r:
    given: "#Info"
    then:
      function: truthy

functions:
  - isEmptyTitle
functionsDir: ./checks
rules:
  r:
    given: $.info.title
    then:
      function: isEmptyTitle

module.exports = (v) => (typeof v === 'string' && v.trim() !== '' ? [] : [{ message: 'Title is empty.' }]);

functions: isEmptyTitle
rules:
  r:
    given: $.info.title
    then:
      function: isEmptyTitle

module.exports = (targetVal) => {
  if (typeof targetVal !== 'string' || targetVal.trim() === '') {
    return [{ message: 'Title is empty.' }];
  }
  return [];
};

extends:
  - ./base.yaml
  - [./a.yaml, recommended]
  - [./b.yaml, all]
  - [./c.yaml, "off"]

rules:
  base-rule:
    given: $
    then:
      function: falsy

rules:
  a-rule:
    given: $
    then:
      function: falsy

rules:
  b-rule:
    given: $
    then:
      function: falsy

rules:
  c-rule:
    given: $
    then:
      function: falsy

extends:
  - [./base.yaml, all, extra]

rules:
  base-rule:
    given: $
    then:
      function: truthy

extends:
  - ./base.yaml
  - [./other.yaml, all]

rules:
  base-rule:
    given: $
    then:
      function: truthy

rules:
  other-rule:
    given: $
    then:
      function: truthy