zuplo 7.13.4 → 7.13.5

package/docs/articles/api-lint-configuration.mdx

@@ -0,0 +1,459 @@
+---
+title: Lint Configuration
+sidebar_label: Configuration
+description:
+  Configure `zuplo lint` with zuplo.lint.jsonc to pick rulesets, scope rule
+  severities, override rules per route, require policies, and detect breaking
+  changes.
+applies_to:
+  product: gateway
+  hosting: all
+---
+
+`zuplo lint` reads its settings from a `zuplo.lint.jsonc` file in the root of
+your project. The file is optional: without it, the linter runs the
+`zuplo:recommended` preset and fails only on errors.
+
+Start the file with `$schema` and `version`:
+
+```jsonc title="zuplo.lint.jsonc"
+{
+  "$schema": "https://cdn.zuplo.com/schemas/zuplo-lint.json",
+  "version": 2,
+  "extends": ["zuplo:recommended"],
+}
+```
+
+`$schema` gives your editor completion and inline errors for every setting on
+this page. `"version"` is the version of the configuration format; set it to
+`2`.
+
+The linter looks for `zuplo.lint.jsonc` first, then `zuplo.lint.json`. To use a
+file somewhere else, pass its path with `--config`. The path is relative to the
+directory you run the command from, not to `--dir`:
+
+```bash
+npx zuplo lint --config ./lint/strict.jsonc
+```
+
+The file is JSON with comments (JSONC), so you can annotate why a rule is off or
+a path is skipped. Trailing commas are allowed.
+
+## Full example
+
+```jsonc title="zuplo.lint.jsonc"
+{
+  "$schema": "https://cdn.zuplo.com/schemas/zuplo-lint.json",
+  "version": 2,
+
+  // Rulesets to start from, applied in order
+  "extends": [
+    "zuplo:strict",
+    ["spectral:owasp", "recommended"],
+    "./lint/team-ruleset.json",
+  ],
+
+  "rules": {
+    // A severity: "error", "warn", "info", "hint", or "off"
+    "info-contact": "off",
+
+    // A severity scoped to some routes
+    "operation-description": {
+      "severity": "error",
+      "paths": ["/v1/**"],
+      "excludePaths": ["/v1/internal/**"],
+    },
+
+    // A custom rule: require an API key policy on /v1 routes
+    "require-api-key-v1": {
+      "message": "v1 routes need an API key",
+      "severity": "error",
+      "paths": ["/v1/**"],
+      "given": "$",
+      "then": {
+        "function": "zuplo:requirePolicy",
+        "functionOptions": { "policyTypes": ["api-key"] },
+      },
+    },
+  },
+
+  // Change rules for some routes or files; later entries win
+  "overrides": [
+    {
+      "paths": ["/health"],
+      "rules": { "zuplo/require-policy": "off", "operation-tags": "off" },
+    },
+    {
+      "files": ["config/legacy.oas.json"],
+      "rules": { "operation-description": "warn" },
+    },
+  ],
+
+  // The lowest severity that fails the run
+  "failOn": "error",
+
+  // Compare the OpenAPI files with a Git branch
+  "breakingChanges": { "enabled": true, "baseline": "origin/main" },
+}
+```
+
+## How settings combine
+
+```txt
+extends (left to right) → rules → overrides (in order) → --fail-on flag
+```
+
+1. `extends` builds the starting set of rules. When two rulesets define the same
+   rule, the later one wins.
+2. `rules` changes the severity of those rules, limits them to some routes, or
+   adds new ones.
+3. `overrides` changes severities for the routes or files they match. When
+   several overrides match a result, the last one wins.
+4. `--fail-on` on the command line replaces [`failOn`](#failon) for one run.
+
+## Severities
+
+Every rule reports at one severity:
+
+| Severity  | Meaning                                                                    |
+| --------- | -------------------------------------------------------------------------- |
+| `"error"` | A defect. Fails the run under the default `failOn`.                        |
+| `"warn"`  | A likely problem. Fails the run only when `failOn` is `"warn"`.            |
+| `"info"`  | Worth knowing. Reported, counted under `info` in the summary, never fails. |
+| `"hint"`  | A suggestion. Reported like `info`, never fails.                           |
+| `"off"`   | The rule doesn't run, or doesn't report on the routes it's off for.        |
+
+## Options
+
+### `extends`
+
+The rulesets to start from. The default is `["zuplo:recommended"]`. An entry is
+one of these:
+
+**A Zuplo preset.** Each preset combines Zuplo's own checks with a reviewed set
+of OpenAPI rules that catch real defects without flooding a typical project.
+
+| Preset              | Adds                                                                                                                                                                    |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `zuplo:recommended` | The core checks: `operationId`, descriptions, tags, path parameters, undefined policies, route labels, policy schemas, duplicate operations, unsafe Markdown, and more. |
+| `zuplo:strict`      | Everything in recommended, plus required authentication and rate limiting, CORS on every route, API info, error responses, and documentation completeness.              |
+| `zuplo:security`    | Everything in recommended, plus required authentication and rate limiting, both as errors.                                                                              |
+
+**A vacuum or Spectral built-in ruleset.** These bring in the full catalog of
+general OpenAPI rules:
+
+| Ruleset                            | Contains                  |
+| ---------------------------------- | ------------------------- |
+| `vacuum:oas` or `spectral:oas`     | General OpenAPI rules.    |
+| `vacuum:owasp` or `spectral:owasp` | OWASP API security rules. |
+
+On their own, these sets turn on that set's recommended rules. Write the entry
+as a pair to pick a mode instead, as in Spectral:
+
+```jsonc
+{
+  "version": 2,
+  "extends": [
+    "zuplo:recommended",
+    ["spectral:owasp", "all"], // every OWASP rule
+  ],
+}
+```
+
+| Mode            | Effect                                               |
+| --------------- | ---------------------------------------------------- |
+| `"recommended"` | The set's recommended rules. The default.            |
+| `"all"`         | Every rule in the set.                               |
+| `"off"`         | Removes the set's rules that an earlier entry added. |
+
+Some general OpenAPI rules don't fit Zuplo projects. For example,
+`oas3-api-servers` reports every spec because Zuplo supplies the servers, and
+`paths-kebab-case` reports URLPattern paths such as `/users/:id`. Turn those off
+in `rules` when you extend `vacuum:oas`, or start from a Zuplo preset, which
+leaves them out.
+
+**A local ruleset file.** A `.json` or `.jsonc` file in the Spectral ruleset
+format, with a path relative to `zuplo.lint.jsonc`. Use it to share rules
+between projects. See
+[Custom lint rules](./api-lint-custom-rules.mdx#share-rules-with-a-ruleset-file).
+
+Run `npx zuplo lint --list-rules` to see every rule and which rulesets include
+it. The [rules reference](./api-lint-rules.mdx) describes the rules in the Zuplo
+presets.
+
+### `rules`
+
+Rule settings, keyed by rule ID. A value is either a severity or an object.
+
+A severity changes the rule everywhere:
+
+```jsonc
+{
+  "version": 2,
+  "rules": {
+    "operation-tags": "off",
+    "operation-description": "error",
+  },
+}
+```
+
+An object changes the severity and limits which routes the rule reports on:
+
+```jsonc
+{
+  "version": 2,
+  "rules": {
+    "operation-description": {
+      "severity": "error",
+      "paths": ["/v1/**"],
+      "excludePaths": ["/v1/internal/**"],
+    },
+  },
+}
+```
+
+| Field          | Description                                                                  |
+| -------------- | ---------------------------------------------------------------------------- |
+| `severity`     | The rule's severity. Leave it out to keep the severity the rule already has. |
+| `paths`        | Report the rule only on these API paths.                                     |
+| `excludePaths` | Don't report the rule on these API paths.                                    |
+
+Path patterns work the same everywhere in this file:
+
+- A plain path matches that route exactly, as written in the OpenAPI file:
+  `"/users/{userId}"`.
+- A path ending in `/**` matches that path and every path beneath it.
+  `"/internal/**"` matches `/internal` and `/internal/jobs`, but not
+  `/internal2`.
+
+A rule with `paths` doesn't report results that aren't tied to a route, such as
+a missing `info.description` or a `policies.json` schema error.
+
+An object with `given` and `then` defines a new rule. See
+[Custom lint rules](./api-lint-custom-rules.mdx).
+
+A rule ID that no ruleset in `extends` defines stops the run with exit code `2`,
+and the error suggests the closest ID. To configure a rule, extend a ruleset
+that includes it: `"zuplo/require-cors-policy"` is only available when you
+extend `zuplo:strict`.
+
+`zuplo/require-policy` is the rule that enforces
+[`requiredPolicies`](#requiredpolicies). Setting it applies the severity to
+every required policy, and `"off"` turns all of them off. Use the base ID here;
+`zuplo/require-policy-warn`, which appears in results, isn't a rule you
+configure.
+
+### `overrides`
+
+Change rule severities for some routes or OpenAPI files. Use an override when a
+group of routes is deliberately different from the rest of the API: public
+endpoints, a health check, a legacy spec you can't change yet.
+
+```jsonc
+{
+  "version": 2,
+  "overrides": [
+    {
+      "paths": ["/health", "/status"],
+      "rules": { "zuplo/require-policy": "off" },
+    },
+    {
+      "files": ["config/legacy.oas.json"],
+      "rules": {
+        "operation-description": "off",
+        "operation-tags": "off",
+      },
+    },
+  ],
+}
+```
+
+| Field   | Description                                                                                                                   |
+| ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `paths` | API paths the override applies to.                                                                                            |
+| `files` | OpenAPI files the override applies to, relative to the project directory. `*` matches within one folder: `config/*.oas.json`. |
+| `rules` | Severities to apply, keyed by rule ID.                                                                                        |
+
+An override needs `paths`, `files`, or both. With both, a result must match
+both.
+
+An override can also turn a rule on. With `"operation-tags": "off"` in `rules`
+and `{ "paths": ["/v1/**"], "rules": { "operation-tags": "warn" } }` in
+`overrides`, the rule reports only on `/v1` routes. An override works within a
+rule's own `paths` and `excludePaths`, and can't turn a rule on for a path in
+`ignorePaths`.
+
+### `failOn`
+
+The lowest severity that fails the run with exit code `1`.
+
+| Value     | The run fails when                                                      |
+| --------- | ----------------------------------------------------------------------- |
+| `"error"` | There is at least one error, or a breaking change reported as an error. |
+| `"warn"`  | There is at least one error, warning, or breaking change.               |
+| `"none"`  | Never. The linter reports results and exits with `0`.                   |
+
+The default is `"error"`. `info` and `hint` results never fail a run. Any other
+value stops the run with exit code `2`. The `--fail-on` flag overrides this
+value for a single run.
+
+### `ignorePaths`
+
+API paths whose route results the linter drops for every rule. An override can't
+turn a rule back on for an ignored path.
+
+```jsonc
+{
+  "version": 2,
+  "ignorePaths": ["/health", "/internal/**"],
+}
+```
+
+`ignorePaths` also applies to
+[automatic fixes](./api-lint.mdx#fix-problems-automatically). Results that
+aren't tied to a route still appear: `policies.json` schema results, `info`
+rules, and [breaking changes](./api-lint-breaking-changes.mdx). To turn off only
+some rules for a route, use [`overrides`](#overrides).
+
+### `include`
+
+The OpenAPI files to lint, relative to the project directory. By default, the
+linter lints every file directly in `config/` that ends in `.oas.json`; it
+doesn't look in subdirectories.
+
+```jsonc
+{
+  "version": 2,
+  "include": ["config/public-api.oas.json"],
+}
+```
+
+Every entry must end in `.oas.json`, must be a relative path, and must stay
+inside the project directory. Glob patterns aren't supported, so list each file.
+A file that doesn't exist fails the run with exit code `2`.
+
+The CLI still requires at least one `.oas.json` file directly in `config/`, so
+use `include` to narrow the files that are linted, not to point at files
+elsewhere.
+
+`include` controls which OpenAPI files are linted. The linter always validates
+`config/policies.json` when it exists.
+
+### `requiredPolicies`
+
+Policies that every route must include. The `zuplo:strict` and `zuplo:security`
+presets each define a default set; `requiredPolicies` replaces those defaults
+with your own list.
+
+```jsonc
+{
+  "version": 2,
+  "extends": ["zuplo:recommended"],
+  "requiredPolicies": [
+    {
+      "id": "require-auth",
+      "policyTypes": ["api-key", "open-id-jwt-auth"],
+      "direction": "inbound",
+      "severity": "error",
+      "message": "Routes must have an authentication policy",
+    },
+    {
+      "id": "require-rate-limit",
+      "policyTypes": ["rate-limit"],
+      "severity": "warn",
+      "message": "Routes should have a rate limiting policy",
+    },
+  ],
+}
+```
+
+Unlike other rules, `requiredPolicies` works with any preset, including
+`zuplo:recommended`. Each requirement applies to every route; to require a
+policy on only some routes, use [`overrides`](#overrides) or a
+[custom rule with `paths`](./api-lint-custom-rules.mdx#require-a-policy-on-some-routes).
+
+Each entry has these fields:
+
+| Field         | Description                                                                                               |
+| ------------- | --------------------------------------------------------------------------------------------------------- |
+| `id`          | A name for the requirement. Use it to keep track of entries; results report under `zuplo/require-policy`. |
+| `policyTypes` | Policy types that satisfy the requirement. A route needs at least one policy whose type matches.          |
+| `direction`   | `"inbound"` or `"outbound"`. Defaults to `"inbound"`.                                                     |
+| `severity`    | `"error"` or `"warn"`. Defaults to `"error"`.                                                             |
+| `message`     | The message to report. The linter appends the method and path of the route, for example `: get /todos`.   |
+
+The linter matches each policy name in the route's `x-zuplo-route.policies` list
+to its `policyType` in `config/policies.json`. An entry in `policyTypes` matches
+that exact type and any type that starts with it followed by a dash, so
+`"api-key"` matches `api-key-inbound`, and `"rate-limit"` matches
+`rate-limit-inbound`. Matching starts at the beginning of the type, so
+`"rate-limit"` doesn't match `complex-rate-limit-inbound`; list
+`"complex-rate-limit"` separately if you use it.
+
+Requirements with `"severity": "error"` report under the rule ID
+`zuplo/require-policy`. Requirements with `"severity": "warn"` report under
+`zuplo/require-policy-warn`.
+
+To turn off the preset defaults without adding your own requirements, set an
+empty list:
+
+```jsonc
+{
+  "version": 2,
+  "extends": ["zuplo:strict"],
+  "requiredPolicies": [],
+}
+```
+
+The defaults in `zuplo:strict` and `zuplo:security` accept these policy types:
+
+- **Authentication:** `api-key`, `auth0-jwt-auth`, `clerk-jwt-auth`,
+  `cognito-jwt-auth`, `curity-phantom-token`, `firebase-jwt-auth`, `jwt-auth`,
+  `oauth2-pkce-auth`, `okta-jwt-auth`, `open-id-jwt-auth`, `propel-auth`,
+  `stytch-jwt-auth`, `supabase-jwt-auth`
+- **Rate limiting:** `rate-limit`, `complex-rate-limit`
+
+### `breakingChanges`
+
+Compares each OpenAPI file with the same file on a Git branch, tag, or commit,
+and reports changes that can break existing API consumers, such as a removed
+endpoint or a changed type.
+
+```jsonc
+{
+  "version": 2,
+  "breakingChanges": {
+    "enabled": true,
+    "baseline": "origin/main",
+    "severity": "error",
+  },
+}
+```
+
+| Field      | Description                                                              |
+| ---------- | ------------------------------------------------------------------------ |
+| `enabled`  | Turns detection on. Defaults to `false`.                                 |
+| `baseline` | The branch, tag, or commit SHA to compare against. Defaults to `"main"`. |
+| `severity` | `"error"` or `"warn"`. Defaults to `"error"`.                            |
+
+See [Breaking change detection](./api-lint-breaking-changes.mdx) for how to
+choose a baseline, what counts as a breaking change, and how to run it in CI.
+
+## Command-line flags and the configuration file
+
+Flags take precedence over the configuration file for a single run:
+
+| Flag        | Overrides                         |
+| ----------- | --------------------------------- |
+| `--config`  | Which configuration file to read. |
+| `--fail-on` | [`failOn`](#failon).              |
+
+All other settings come only from the configuration file. See the
+[`zuplo lint` CLI reference](../cli/lint.mdx) for every flag.
+
+## Next steps
+
+- [Custom lint rules](./api-lint-custom-rules.mdx) — write your own rules and
+  share them with a ruleset file.
+- [Lint rules reference](./api-lint-rules.mdx) — what each rule checks.
+- [Lint in CI/CD](./api-lint-ci-cd.mdx) — run the linter on every pull request.

package/docs/articles/api-lint-custom-rules.mdx

@@ -0,0 +1,222 @@
+---
+title: Custom Lint Rules
+sidebar_label: Custom rules
+description:
+  Write your own `zuplo lint` rules in the Spectral format, check Zuplo routes
+  and policies with Zuplo functions, and share the rules with a ruleset file.
+applies_to:
+  product: gateway
+  hosting: all
+---
+
+When the built-in rules don't cover a convention your team follows, add your own
+in `zuplo.lint.jsonc`. Custom rules use the
+[Spectral](https://docs.stoplight.io/docs/spectral/e5b9616d6d50c-rulesets)
+ruleset format, so a rule written for Spectral or vacuum works here unchanged.
+
+## Write a rule
+
+A rule selects parts of your OpenAPI document with `given` and checks each one
+with a function in `then`:
+
+```jsonc title="zuplo.lint.jsonc"
+{
+  "$schema": "https://cdn.zuplo.com/schemas/zuplo-lint.json",
+  "version": 2,
+  "extends": ["zuplo:recommended"],
+  "rules": {
+    "operation-summary-length": {
+      "description": "Summaries must fit in the developer portal sidebar",
+      "message": "Keep summaries to 60 characters or fewer",
+      "severity": "warn",
+      "given": "$.paths[*][*].summary",
+      "then": { "function": "length", "functionOptions": { "max": 60 } },
+    },
+  },
+}
+```
+
+```txt
+  config/routes.oas.json
+    45:20      warn      Keep summaries to 60 characters or fewer: 'List every todo item that belongs to the current user, sorted by the date it was created' must not be longer/greater than '60'  operation-summary-length  $.paths['/v1/todos'].get.summary
+```
+
+The key, `operation-summary-length`, is the rule ID. It appears in results, and
+you use it to change the rule's severity in
+[`overrides`](./api-lint-configuration.mdx#overrides). IDs starting with
+`zuplo/` are reserved for Zuplo's rules.
+
+| Field          | Description                                                                                                                            |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `given`        | A [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) expression, or a list of them, selecting the values to check.              |
+| `then`         | The function to run on each selected value, or a list of functions. Each has `function`, and optionally `field` and `functionOptions`. |
+| `severity`     | `"error"`, `"warn"`, `"info"`, `"hint"`, or `"off"`. Defaults to `"warn"`.                                                             |
+| `message`      | The text each result starts with. Defaults to `description`, then to the rule ID.                                                      |
+| `description`  | What the rule checks. Used as the message when `message` isn't set.                                                                    |
+| `paths`        | Report the rule only on these API paths, such as `["/v1/**"]`.                                                                         |
+| `excludePaths` | Don't report the rule on these API paths.                                                                                              |
+| `formats`      | Document formats the rule applies to, such as `["oas3"]`.                                                                              |
+
+`then.field` checks a property of each selected value instead of the value
+itself, so this rule reports every operation without a `summary`:
+
+```jsonc
+{
+  "version": 2,
+  "rules": {
+    "operation-summary": {
+      "description": "Operations need a summary",
+      "given": "$.paths[*][*]",
+      "then": { "field": "summary", "function": "truthy" },
+    },
+  },
+}
+```
+
+## Functions
+
+These are the general-purpose functions, the same as Spectral's core functions:
+
+| Function       | Reports when the value...                                               | Options                                                               |
+| -------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `truthy`       | is missing, empty, `false`, or `0`                                      |                                                                       |
+| `falsy`        | is set to a truthy value                                                |                                                                       |
+| `defined`      | is missing                                                              |                                                                       |
+| `undefined`    | is set                                                                  |                                                                       |
+| `pattern`      | doesn't match `match`, or matches `notMatch`                            | `match`, `notMatch` (regular expressions)                             |
+| `casing`       | isn't in the given case                                                 | `type`: `camel`, `pascal`, `kebab`, `snake`, `cobol`, `flat`, `macro` |
+| `length`       | is shorter than `min` or longer than `max` (characters, items, or keys) | `min`, `max`                                                          |
+| `enumeration`  | isn't one of `values`                                                   | `values`                                                              |
+| `alphabetical` | isn't sorted                                                            | `keyedBy` for lists of objects                                        |
+| `schema`       | doesn't match a JSON schema                                             | `schema`                                                              |
+| `xor`          | has more or fewer than one of `properties`                              | `properties`                                                          |
+
+A Zuplo route has settings, such as its policies, that the OpenAPI document
+alone can't explain, because policies are defined in `config/policies.json`.
+These Zuplo functions read both files:
+
+| Function                       | Reports a route that...                                  | Options                                                         |
+| ------------------------------ | -------------------------------------------------------- | --------------------------------------------------------------- |
+| `zuplo:requirePolicy`          | doesn't have a policy of one of the given types          | `policyTypes` (required), `direction` (`inbound` or `outbound`) |
+| `zuplo:noUndefinedPolicies`    | references a policy that isn't in `config/policies.json` |                                                                 |
+| `zuplo:noEmptyInboundPolicies` | has an empty `policies.inbound` list                     |                                                                 |
+| `zuplo:requireRouteLabel`      | has no `label` in `x-zuplo-route`                        |                                                                 |
+| `zuplo:requireCorsPolicy`      | has no `corsPolicy` in `x-zuplo-route`                   |                                                                 |
+
+A Zuplo function checks every route itself, so set `"given": "$"` and choose the
+routes with `paths` and `excludePaths`. Only `zuplo:requirePolicy` uses your
+`message`; the other Zuplo functions write their own.
+
+Run `npx zuplo lint --list-rules` to see every function and rule available.
+
+## Examples
+
+### Require a policy on some routes
+
+[`requiredPolicies`](./api-lint-configuration.mdx#requiredpolicies) applies to
+every route. A custom rule with `zuplo:requirePolicy` applies to the routes you
+choose:
+
+```jsonc
+{
+  "version": 2,
+  "rules": {
+    "require-api-key-v1": {
+      "message": "v1 routes need an API key",
+      "severity": "error",
+      "paths": ["/v1/**"],
+      "given": "$",
+      "then": {
+        "function": "zuplo:requirePolicy",
+        "functionOptions": { "policyTypes": ["api-key"] },
+      },
+    },
+  },
+}
+```
+
+```txt
+    16:14      error     v1 routes need an API key: get /v1/admin  require-api-key-v1  paths./v1/admin.get.x-zuplo-route.policies.inbound
+```
+
+`policyTypes` matches the same way as in `requiredPolicies`: `"api-key"` matches
+the `api-key-inbound` policy type. Add one rule per requirement, each with its
+own ID and `paths`.
+
+### Enforce a naming convention
+
+```jsonc
+{
+  "version": 2,
+  "rules": {
+    "operation-id-camel-case": {
+      "description": "operationIds use camelCase",
+      "severity": "error",
+      "given": "$.paths[*][*].operationId",
+      "then": { "function": "casing", "functionOptions": { "type": "camel" } },
+    },
+  },
+}
+```
+
+### Keep internal headers out of the public API
+
+```jsonc
+{
+  "version": 2,
+  "rules": {
+    "no-x-internal-headers": {
+      "description": "Don't expose X-Internal-* headers",
+      "severity": "warn",
+      "given": "$.paths[*][*].parameters[?(@.in == 'header')].name",
+      "then": {
+        "function": "pattern",
+        "functionOptions": { "notMatch": "^X-Internal-" },
+      },
+    },
+  },
+}
+```
+
+## Share rules with a ruleset file
+
+To use the same rules in several projects, put them in a ruleset file and extend
+it. A ruleset file is a `.json` or `.jsonc` file in the Spectral ruleset format:
+
+```jsonc title="lint/team-ruleset.jsonc"
+{
+  // Rules shared by every API team
+  "rules": {
+    "operation-id-camel-case": {
+      "description": "operationIds use camelCase",
+      "severity": "error",
+      "given": "$.paths[*][*].operationId",
+      "then": { "function": "casing", "functionOptions": { "type": "camel" } },
+    },
+  },
+}
+```
+
+```jsonc title="zuplo.lint.jsonc"
+{
+  "$schema": "https://cdn.zuplo.com/schemas/zuplo-lint.json",
+  "version": 2,
+  "extends": ["zuplo:recommended", "./lint/team-ruleset.jsonc"],
+}
+```
+
+The path is relative to `zuplo.lint.jsonc`. A ruleset file can extend the
+built-in rulesets (`vacuum:oas`, `spectral:oas`, `vacuum:owasp`,
+`spectral:owasp`) but not other files. Rulesets must be local files: the linter
+doesn't download rulesets from a URL, so copy a shared ruleset into your
+repository, or add it as a package, and reference that path. YAML rulesets
+aren't supported; convert them to JSON.
+
+`zuplo.lint.jsonc` can still change the severity or scope of a rule from a
+ruleset file, the same as any other rule.
+
+## Next steps
+
+- [Lint configuration](./api-lint-configuration.mdx) — rulesets, severities, and
+  overrides.
+- [Lint rules reference](./api-lint-rules.mdx) — the rules in the Zuplo presets.