OpenRPC Linter

The OpenRPC Linter is a fast, extensible command-line tool for checking the quality and consistency of OpenRPC documents. It complements specification validation with rules for documentation completeness, schema quality, usability, and uniqueness.

Installation

npm

For JavaScript and TypeScript projects, install the linter as a development dependency:


npm install --save-dev @open-rpc/openrpc-linter

The npm package installs a native binary for supported macOS, Linux, and Windows systems on ARM64 and x64.

Go

Install the latest release with Go:


go install github.com/open-rpc/openrpc-linter@latest

Prebuilt binaries are also available from the GitHub releases page .

Quick start

The linter requires a rules file. Create one that extends the bundled recommended ruleset:


openrpc-linter init

This creates rules.yml:


extends:
  - recommended

Lint an OpenRPC document:


openrpc-linter lint openrpc.json --rules rules.yml

If you installed the npm package locally, run the same command with npx:


npx openrpc-linter lint openrpc.json --rules rules.yml

The linter defaults to openrpc.json when the document path is omitted, but it does not automatically discover rules.yml. Always pass the rules file with --rules or -r.

Linting and validation

Linting and validation answer different questions:

Command	Purpose
`openrpc-linter lint openrpc.json -r rules.yml`	Applies quality and style rules from a ruleset.
`openrpc-linter validate openrpc.json`	Checks the document against the OpenRPC meta-schema.

Use validation to check specification conformance. Use linting to enforce the documentation and design conventions expected by your project.

The recommended ruleset

The bundled recommended ruleset checks common documentation and API design issues, using errors for stricter requirements and warnings for suggested improvements. Its rules fall into four broad groups:

Group	Examples
Documentation completeness	Descriptions, summaries, license information, errors, and examples
Schema quality	Schema titles, descriptions, and explicit types or composition keywords
Usability	Non-empty methods and examples, concise summaries, and parameter-count guidance
Uniqueness	Method names, summaries, parameter names, error codes, and example names

The source of truth is the recommended ruleset .

Understanding the results

Text output groups violations by method, schema, descriptor, tag, or top-level section. Each result includes a document path, severity, message, and rule ID.

Severity	Behavior
`error`	Reports the violation and makes `lint` exit non-zero.
`warn`	Reports the violation without independently failing the command.
`info`	Reports informational guidance.
`ignore`	Disables the rule.

For automation, request a flat JSON result:


openrpc-linter lint openrpc.json -r rules.yml --format json

Try a document with known issues

The linter repository includes a fixture with intentional duplicate values . From a clone of that repository, run:


openrpc-linter lint \
  e2e/fixtures/unique/bad-document.json \
  --rules rules/defaults/recommended.yaml

With release v0.0.17, the command exits non-zero and reports:


e2e/fixtures/unique/bad-document.json

4 errors, 10 warnings found in 8 rules

  path                                     level    message                                      rule

getBalance
  methods[0].errors[0].description         warning  missing field 'description'                  error-description
  methods[0].errors[1].code                error    Duplicate value 1001                         unique-error-codes-per-method
  methods[0].errors[1].description         warning  missing field 'description'                  error-description
  methods[0].examples[1].name              error    Duplicate value "basic-request"              unique-example-names-per-method
  methods[0].params[0].schema.description  warning  missing field 'description'                  schema-description
    param: "accountId"
    schema: "Account ID"
  methods[0].params[1].name                error    Duplicate value "accountId"                  unique-param-names-per-method
    param: "accountId"
  methods[0].params[1].schema.description  warning  missing field 'description'                  schema-description
    param: "accountId"
    schema: "Account ID (optional)"
  methods[0].result.schema.description     warning  missing field 'description'                  schema-description
    schema: "Balance"
  methods[1].errors[0].description         warning  missing field 'description'                  error-description
  methods[1].name                          error    Duplicate value "getBalance"                  unique-method-names
  methods[1].params[0].schema.description  warning  missing field 'description'                  schema-description
    param: "accountId"
    schema: "Account ID"
  methods[1].result.schema.description     warning  missing field 'description'                  schema-description
    schema: "Balance"
  methods[1].summary                       warning  Duplicate value "Fetch account balance"      unique-method-summary

info
  info.license                             warning  missing field 'license'                      info-license

4 errors, 10 warnings found in 8 rules

This run demonstrates that a fixture designed for uniqueness failures can also reveal documentation-quality issues when checked against the complete recommended ruleset. Exact findings can change as that ruleset evolves.

Customize the recommended rules

Extend recommended, override rules by ID, and add project-specific rules in the same file:


extends:
  - recommended
 
rules:
  info-license:
    severity: ignore
 
  method-summary:
    severity: error
 
  method-name-prefix:
    description: Method names must begin with rpc_
    given: $.methods[*].name
    severity: error
    then:
      function: schema
      functionOptions:
        type: string
        pattern: "^rpc_"

See Writing Rules and Functions for the rule format, selector behavior, built-in functions, and the contributor path for adding a new function.

Add the linter to CI

Add a script to package.json:


{
  "scripts": {
    "lint:openrpc": "openrpc-linter lint openrpc.json -r rules.yml"
  }
}

Then run it in CI after installing dependencies:


- run: npm ci
- run: npm run lint:openrpc

GitHub Actions

Commit openrpc.json, rules.yml, package.json, and package-lock.json to your repository. The package files should include the linter development dependency and the lint:openrpc script shown above.

Create .github/workflows/lint-openrpc.yml:


name: Lint OpenRPC
 
on:
  push:
  pull_request:
 
permissions:
  contents: read
 
jobs:
  lint-openrpc:
    name: Lint OpenRPC
    runs-on: ubuntu-latest
    steps:
      - name: Check out the repository
        uses: actions/checkout@v7
 
      - name: Set up Node.js
        uses: actions/setup-node@v7
        with:
          node-version: "24"
          cache: npm
 
      - name: Install dependencies
        run: npm ci
 
      - name: Lint the OpenRPC document
        run: npm run lint:openrpc

The workflow runs on pushes and pull requests. Lint errors fail the job; warnings and informational findings appear in the logs without failing it. If your document or rules file lives elsewhere, update the paths in the lint:openrpc script.

This example uses GitHub’s checkout and setup-node actions to prepare the runner before installing and running the linter.

Current boundaries

OpenRPC documents must be JSON.
lint currently resolves internal $ref references. External references remain unresolved.
A rules file must define extends, rules, or both.
recommended is currently the only bundled ruleset extension.
New executable rule functions must be compiled into the linter; YAML rules can only use registered functions.

The linter is currently pre-1.0. Pin a release in CI when reproducible behavior is important.