# Migrate from Spectral

Source: https://apigenie.pl/docs/guides/migrate-from-spectral

This guide moves a repository that lints its API descriptions with Spectral to `apigenie lint`:
the built-in rules, your own rules and functions, the report in CI, and what has no counterpart.
It starts from Spectral 6.17 with its `spectral:oas` and `spectral:asyncapi` rulesets and an
OpenAPI file, `openapi.yaml`.

You need the CLI installed; the [Quickstart](/docs/quickstart) shows how. Keep Spectral installed
until the last step, so you can compare the two reports on the same files.

## What changes and what stays

| | Spectral | API Genie |
| --- | --- | --- |
| Command | `spectral lint openapi.yaml` | `apigenie lint openapi.yaml` |
| Configuration | `.spectral.yaml`, `.spectral.json` or `.spectral.js` | `apigenie.yaml`, section `commands.lint` ([Configuration](/docs/reference/cli/configuration)) |
| Built-in rules | `spectral:oas` (57 rules), `spectral:asyncapi` (55) | rulesets per standard: `recommended`, `strict`, `all`; 67 rules for [OpenAPI](/docs/linter/openapi) (64 before 0.12.0), 48 for [Swagger 2.0](/docs/linter/swagger), 39 for [AsyncAPI](/docs/linter/asyncapi) (34 before 0.12.0) |
| Severities | `error`, `warn`, `info`, `hint`, `off` | `error`, `warning`, `hint` (or `info`), `off`; a custom rule writes `warn` |
| Custom rules | `given`, `then`, functions | the same format, under `commands.lint.rules` |
| Custom functions | JavaScript, `functionsDir` | JavaScript in `functions/`, listed under `functions` |
| Disabling a rule in one place | `overrides` by file in the ruleset | `x-apigenie-lint-disable` in the document |
| Report formats | `-f json`, `junit`, `sarif`, `html`, ... | `--formatter json`, `junit`, `sarif`, `html`, ... |
| Exit status | 1 at `--fail-severity` and above, `error` by default | 1 on an error, 0 on warnings only, 2 on a file it cannot read |
| Fixes | none | `--fix` for the issues that have one |

## Run both on the same file

```sh
spectral lint openapi.yaml
apigenie lint openapi.yaml
```

```text
  764:6   warning  Unused shared component                                 unused-shared-component
  781:8   error    Schema with integer type does not define proper format  schema-format-defined

  2 issues (1 error, 1 warning)
  0 errors, 1 warning are potentially auto-fixable
```

Each line gives the position, the severity, the message and the rule; every rule has a page in the
[linter rules](/docs/linter) that says what it checks and why. The two reports differ, and not
only in the names: without configuration API Genie applies the
[recommended ruleset](/docs/linter/openapi/rulesets/recommended), 46 rules (43 before 0.12.0) of which some have no
Spectral counterpart, and leaves out some of what `spectral:oas` reports. The next two sections
say which.

## Replace the ruleset

A `.spectral.yaml` that extends the built-in ruleset and adjusts a few rules:

```yaml
extends: spectral:oas
rules:
  operation-description: error
  info-contact: off
  oas3-server-not-example.com: warn
```

becomes, in `apigenie.yaml` at the root of the repository:

```yaml
version: '1.0'
commands:
  lint:
    extends: [recommended]
    rules:
      operation-description-defined: error
      contact-defined: off
```

- `extends` names API Genie's rulesets, not Spectral's: `spectral:oas` there is an error, with
  exit status 2. A Spectral ruleset file is named by its path
  ([Keep a shared ruleset file](#keep-a-shared-ruleset-file)). `recommended` is the default; `strict`
  turns on more rules with higher severities, `all` every rule. The rulesets of each standard are
  listed in the [linter rules](/docs/linter).
- A rule takes its name from the table below. Spectral's `warn` is `warning` for a built-in rule;
  `hint` and `off` stay.
- A rule with no counterpart, such as `oas3-server-not-example.com`, has no line.
- An OpenAPI 3.x file, a Swagger 2.0 file and an AsyncAPI file are linted by three linters with
  rules of their own, so one configuration covers a repository that mixes them; Spectral picks the
  ruleset by the document's format.

## The rules of spectral:oas, by name

The rules Spectral turns on by default, and their counterparts in the OpenAPI linter. A rule
marked *not checked* has no counterpart today: drop its line from the configuration.

| Spectral | API Genie | Note |
| --- | --- | --- |
| `operation-success-response` | [operation-success-response](/docs/linter/openapi/rules/operation-success-response) | |
| `operation-operationId` | [operation-id-defined](/docs/linter/openapi/rules/operation-id-defined) | |
| `operation-operationId-unique` | [operation-id-unique](/docs/linter/openapi/rules/operation-id-unique) | |
| `operation-operationId-valid-in-url` | not checked | |
| `operation-parameters` | [parameters-unique](/docs/linter/openapi/rules/parameters-unique) | |
| `operation-tags` | [operation-tags-defined](/docs/linter/openapi/rules/operation-tags-defined) | |
| `operation-tag-defined` | [operation-tags-declared](/docs/linter/openapi/rules/operation-tags-declared) | since 0.12.0 |
| `operation-description` | [operation-description-defined](/docs/linter/openapi/rules/operation-description-defined) | also rejects descriptions under 10 characters |
| `path-params` | [path-parameters-defined](/docs/linter/openapi/rules/path-parameters-defined) | [path-parameters-on-items](/docs/linter/openapi/rules/path-parameters-on-items) asks for them on the path item |
| `path-declarations-must-exist`, `path-keys-no-trailing-slash` | [paths-well-formed](/docs/linter/openapi/rules/paths-well-formed) | |
| `path-not-include-query` | not checked | |
| `duplicated-entry-in-enum` | [schema-enum-no-duplicates](/docs/linter/openapi/rules/schema-enum-no-duplicates) | |
| `typed-enum` | [schema-enum-types](/docs/linter/openapi/rules/schema-enum-types) | |
| `array-items` | not checked | |
| `no-$ref-siblings` | [ref-no-siblings](/docs/linter/openapi/rules/ref-no-siblings) | since 0.12.0; extensions, a Path Item's fields and a `$ref` key inside data (examples, defaults, Link values) are not reported |
| `info-contact` | [contact-defined](/docs/linter/openapi/rules/contact-defined) | asks for `name`, and `url` or `email`, as Spectral's `contact-properties` does |
| `info-description` | [info-defined](/docs/linter/openapi/rules/info-defined) | asks for `summary`, `description` and `version` |
| `no-eval-in-markdown`, `no-script-tags-in-markdown` | [safe-markdown](/docs/linter/openapi/rules/safe-markdown) | |
| `openapi-tags-uniqueness` | [tags-unique](/docs/linter/openapi/rules/tags-unique) | |
| `oas3-api-servers` | [servers-defined](/docs/linter/openapi/rules/servers-defined) | |
| `oas3-server-trailing-slash` | [server-urls-no-trailing-slash](/docs/linter/openapi/rules/server-urls-no-trailing-slash) | since 0.12.0 |
| `oas3-server-variables` | not checked | |
| `oas3-operation-security-defined` | [operation-security-defined](/docs/linter/openapi/rules/operation-security-defined) | a different check: every operation has a security requirement; Spectral checks that the named schemes exist |
| `oas3-schema` | [openapi-json-schema-validation](/docs/linter/openapi/rules/openapi-json-schema-validation) | |
| `oas3-unused-component` | [unused-shared-component](/docs/linter/openapi/rules/unused-shared-component) | follows references transitively, so a component used only by an unused one is reported too |
| `oas3-examples-value-or-externalValue`, `oas3-valid-media-example`, `oas3-valid-schema-example` | not checked | examples are not validated against their schema |
| `oas3-callbacks-in-callbacks`, `oas3_1-servers-in-webhook`, `oas3_1-callbacks-in-webhook`, `oas3_2-no-deprecated-xml-attribute` | not checked | |

The rules Spectral leaves off by default:

| Spectral | API Genie |
| --- | --- |
| `contact-properties` | [contact-defined](/docs/linter/openapi/rules/contact-defined) |
| `info-license` | [license-defined](/docs/linter/openapi/rules/license-defined) |
| `license-url` | not checked |
| `openapi-tags` | not checked |
| `openapi-tags-alphabetical` | [tags-sorted](/docs/linter/openapi/rules/tags-sorted) |
| `operation-singular-tag` | not checked |
| `tag-description` | [tag-description-defined](/docs/linter/openapi/rules/tag-description-defined) |
| `oas3-parameter-description` | [parameter-description-defined](/docs/linter/openapi/rules/parameter-description-defined) |
| `oas3-server-not-example.com` | not checked |

The `oas2-*` rules apply to Swagger 2.0 files, which API Genie lints with the
[Swagger 2.0 linter](/docs/linter/swagger): `oas2-schema` is
[swagger-validation](/docs/linter/swagger/rules/swagger-validation), `oas2-api-host` is
[host-defined](/docs/linter/swagger/rules/host-defined), `oas2-unused-definition` is
[unused-shared-component](/docs/linter/swagger/rules/unused-shared-component), and the rules that
share a name with an OpenAPI rule check the same thing. `operation-tag-defined` and
`no-$ref-siblings` have no counterpart for Swagger 2.0 files. The AsyncAPI rules of `spectral:asyncapi`
map onto the [AsyncAPI linter](/docs/linter/asyncapi) the same way: `asyncapi-info-contact` is
[contact-defined](/docs/linter/asyncapi/rules/contact-defined), `asyncapi-channel-parameters` is
[channel-parameters-defined](/docs/linter/asyncapi/rules/channel-parameters-defined),
`asyncapi-unused-components-schema` is
[unused-shared-component](/docs/linter/asyncapi/rules/unused-shared-component).

## What the recommended ruleset adds

Rules of `recommended` that `spectral:oas` has nothing for; each has a page that says what it
checks and why:

- [schema-format-defined](/docs/linter/openapi/rules/schema-format-defined),
  [schema-format-type-mismatch](/docs/linter/openapi/rules/schema-format-type-mismatch) and
  [schema-format-deprecated](/docs/linter/openapi/rules/schema-format-deprecated): numbers and
  strings say their format, and the format fits the type.
- [schema-constraints](/docs/linter/openapi/rules/schema-constraints) and
  [schema-no-additional-properties](/docs/linter/openapi/rules/schema-no-additional-properties):
  strings, numbers, arrays and objects have bounds.
- [schema-no-contradictions](/docs/linter/openapi/rules/schema-no-contradictions),
  [schema-oneof-no-overlap](/docs/linter/openapi/rules/schema-oneof-no-overlap) and
  [schema-conditional-effective](/docs/linter/openapi/rules/schema-conditional-effective): schemas
  that reject every value, `oneOf` branches a value matches twice, `if` without effect.
- [standard-response-codes](/docs/linter/openapi/rules/standard-response-codes),
  [unambiguous-response-codes](/docs/linter/openapi/rules/unambiguous-response-codes) and
  [no-content-response-defined](/docs/linter/openapi/rules/no-content-response-defined): the
  responses an operation declares.
- [paths-max-depth](/docs/linter/openapi/rules/paths-max-depth),
  [paths-max-count](/docs/linter/openapi/rules/paths-max-count),
  [parameter-naming](/docs/linter/openapi/rules/parameter-naming) and
  [schema-datetime-suffix](/docs/linter/openapi/rules/schema-datetime-suffix): the shape of the
  URLs and the names.

Outside `recommended`: [spell-check](/docs/linter/openapi/rules/spell-check) for the texts written
for humans, [schema-keyword-support](/docs/linter/openapi/rules/schema-keyword-support) for the
JSON Schema keywords the tools around the document ignore, and the
[privacy ruleset](/docs/linter/openapi/rulesets/privacy) for credentials and personal data in
URLs. `extends: [recommended, privacy]` adds the last one.

## Carry your custom rules over

A custom rule keeps its definition. This rule of `.spectral.yaml`:

```yaml
rules:
  operation-summary:
    description: Operations must have a summary
    message: "{{property}} is missing at {{path}}"
    severity: error
    given: "$.paths[*][get,put,post,delete,patch]"
    then:
      field: summary
      function: truthy
```

goes under `commands.lint.rules` of `apigenie.yaml` as it is:

```yaml
version: '1.0'
commands:
  lint:
    extends: [recommended]
    rules:
      operation-summary:
        description: Operations must have a summary
        message: "{{property}} is missing at {{path}}"
        severity: error
        given: "$.paths[*][get,put,post,delete,patch]"
        then:
          field: summary
          function: truthy
```

What carries over, as [custom rules](/docs/reference/cli/lint#custom-rules) documents it:

- `given`, `then` with `field`, `function` and `functionOptions`, `message` with `{{error}}`,
  `{{description}}`, `{{path}}`, `{{property}}` and `{{value}}`, `description`, `severity`,
  `resolved` and `formats` (`oas2`, `oas3`, `oas3_0`, `oas3_1`, `oas3_2`, `aas3`, ...).
- The core functions: `truthy`, `falsy`, `defined`, `undefined`, `enumeration`, `length`,
  `pattern`, `casing`, `alphabetical`, `or`, `xor`, `schema`, `typedEnum` and
  `unreferencedReusableObject`, with their options.
- JSONPath as Spectral rulesets write it: member unions without quotes, `~` for member names, `^`
  for the parent, and filters written as JavaScript expressions with `@property`, `@parent`,
  `@path`, the string methods and `constructor.name`
  ([JSONPath](/docs/reference/cli/lint#jsonpath)).

What does not:

- `aliases` and the `#Name` references to them: write the path out.
- Script expressions such as `[(@.length-1)]`.
- `extends` with a URL or an npm package: copy the ruleset file into the repository and extend it by
  its path (see [Keep a shared ruleset file](#keep-a-shared-ruleset-file)). The one exception is
  `@stoplight/spectral-owasp-ruleset`, which API Genie ships: write
  [`owasp`](/docs/reference/cli/lint#the-owasp-ruleset) in `apigenie.yaml`, and a ruleset file you
  keep can extend the package by its name.
- `overrides`, `parserOptions`, `documentationUrl` and `except`.
- A custom rule named like a built-in rule: rename it.

## Keep a shared ruleset file

Extend a ruleset file that several repositories share by its path, relative to `apigenie.yaml`,
next to API Genie's rulesets:

```yaml
version: '1.0'
commands:
  lint:
    extends: [recommended, ./lint/team.spectral.yaml]
    rules:
      team-path-casing: warn
```

Say the shared file is this one:

```yaml
# lint/team.spectral.yaml
extends: [spectral:oas]
rules:
  operation-tags: off
  info-contact: warn
  team-path-casing:
    given: "$.paths[*]~"
    then: { function: pattern, functionOptions: { match: "^(/[a-z-]+)+$" } }
```

Run `apigenie lint openapi.yaml`. The file's own `extends`, `functions` and `functionsDir` resolve
against the file, and `apigenie.yaml` re-tunes its rules like any other. The warnings on the
standard error name what was skipped:

```text
warning: /work/api/lint/team.spectral.yaml: skipped "spectral:oas" in 'extends', which API Genie cannot load (only built-in and bundled rulesets and local ruleset files)
warning: /work/api/lint/team.spectral.yaml: skipped the settings of rules API Genie does not have (2): operation-tags, info-contact
```

The counterparts of the skipped rules come from `recommended` and
[the rules of spectral:oas](#the-rules-of-spectraloas-by-name). Files are read from the disk only,
never from a URL. To lint with the file alone, run
`apigenie lint --no-config --ruleset lint/team.spectral.yaml openapi.yaml`.

A repository of the CAMARA project doesn't need its ruleset file: API Genie ships it, functions
included, as [`camara`](/docs/reference/cli/lint#the-camara-ruleset). Start
with `extends: [camara]`, which reports what CAMARA's Spectral run reports. Add `recommended` for the
counterparts of the `spectral:oas` rules the file extends upstream. `camara` extends [`owasp`](/docs/reference/cli/lint#the-owasp-ruleset),
the OWASP ruleset the file extends upstream, with CAMARA's settings of its rules.
[Lint CAMARA APIs](/docs/guides/industry/lint-camara-apis) sets up a CAMARA repository step by step.

## Carry your functions over

A JavaScript function written for Spectral works unchanged in most cases: it is an ES module whose
default export receives the value, the options and a context, and
`@stoplight/spectral-core` and `@stoplight/spectral-functions` are built in. Put the files in
`functions/` next to `apigenie.yaml` (`functionsDir` changes the directory) and list them:

```yaml
commands:
  lint:
    functions: [operationIdPrefix]
    rules:
      operation-id-prefix:
        given: "$.paths[*][*].operationId"
        then:
          function: operationIdPrefix
          functionOptions: { prefix: api }
```

Functions run in a sandbox with no file system, network, processes or timers, and a call must
finish within 5 seconds. A function that reads a file or fetches a URL has to go; one that needs
another module imports it from the functions directory.
[JavaScript functions](/docs/reference/cli/lint#javascript-functions) has the contract.

## Disable a rule in one place

Spectral turns a rule off for some files with `overrides` in the ruleset. API Genie turns it off
where the issue is, in the document, with `x-apigenie-lint-disable` on the object and its
descendants:

```yaml
paths:
  /legacy/export:
    x-apigenie-lint-disable:
      - operation-id-defined
    get:
      summary: Export, as it was
```

Disable a rule as close to the issue as possible; [disabling rules](/docs/reference/cli/lint#disabling-rules-in-a-document)
says more.

## The report in CI

The formats that keep their name: `-f json`, `junit`, `sarif`, `html` and `stylish` become
`--formatter json`, `junit`, `sarif`, `html` and `stylish`. API Genie adds `checkstyle`, `compact`,
`tap`, `unix` and `visualstudio`; Spectral's `text`, `pretty`, `teamcity`, `github-actions`,
`code-climate`, `gitlab` and `markdown` have no counterpart. For GitLab, `junit` is what the
merge request reads; for GitHub code scanning, `sarif`
([formatting results](/docs/reference/cli/lint#formatters)).

`--fail-severity` has no counterpart: the command exits with 1 when an error is reported and with
0 on warnings alone ([exit status](/docs/reference/cli/lint#exit-status)). To fail the build on a
rule, give it `error` in the configuration. `-r .spectral.yaml` is `--ruleset .spectral.yaml`;
without `apigenie.yaml` that runs only the rules the file defines, because `spectral:oas` is
skipped and the file replaces `recommended`. Once its rules have moved, it is
`--config apigenie.yaml`.

On GitHub Actions, `stoplightio/spectral-action` becomes the
[GitHub Action](/docs/ci/github-action), which installs the CLI and shows the issues on the lines
of the pull request:

```yaml
on: pull_request
jobs:
  api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mykulyak/api-genie-action@v0
        with:
          command: lint
          files: openapi.yaml
```

## Remove Spectral

When the two reports agree on what matters to you: delete `.spectral.yaml`, remove
`@stoplight/spectral-cli` from the development dependencies, and replace the Spectral step of the
pipeline with the one above. The fixes the linter offers are a `--fix` away:

```sh
apigenie lint --fix openapi.yaml
```
