@stoplight/spectral-core

What is @stoplight/spectral-core?

@stoplight/spectral-core is a powerful JSON/YAML linter that helps you enforce a set of rules on your JSON/YAML documents. It is commonly used for validating OpenAPI, AsyncAPI, and other API description formats. The package allows you to define custom rules, use built-in rulesets, and extend existing rulesets to ensure your documents adhere to specific standards.

What are @stoplight/spectral-core's main functionalities?

Linting JSON/YAML documents

This feature allows you to lint JSON/YAML documents against a set of predefined or custom rules. In this example, the document is validated against the OpenAPI v2 ruleset.

const { Spectral } = require('@stoplight/spectral-core');
const { isOpenApiv2 } = require('@stoplight/spectral-rulesets');

const spectral = new Spectral();
spectral.setRuleset(isOpenApiv2);

const document = {
  openapi: '2.0.0',
  info: {
    title: 'Sample API',
    version: '1.0.0'
  },
  paths: {}
};

spectral.run(document).then(results => {
  console.log(results);
});

Custom Rules

This feature allows you to define custom rules for your JSON/YAML documents. In this example, a custom rule is created to ensure that the 'info' object must have a 'contact' field.

const { Spectral, RuleType } = require('@stoplight/spectral-core');

const spectral = new Spectral();
spectral.setRules({
  'info-must-have-contact': {
    given: '$.info',
    then: {
      field: 'contact',
      function: 'truthy'
    },
    type: RuleType.STYLE,
    severity: 'error'
  }
});

const document = {
  openapi: '3.0.0',
  info: {
    title: 'Sample API',
    version: '1.0.0'
  },
  paths: {}
};

spectral.run(document).then(results => {
  console.log(results);
});

Extending Existing Rulesets

This feature allows you to extend existing rulesets with additional custom rules. In this example, the OpenAPI v3 ruleset is extended with a custom rule to ensure that the 'info' object must have a 'contact' field.

const { Spectral } = require('@stoplight/spectral-core');
const { isOpenApiv3 } = require('@stoplight/spectral-rulesets');

const spectral = new Spectral();
spectral.setRuleset(isOpenApiv3);

spectral.mergeRules({
  'info-must-have-contact': {
    given: '$.info',
    then: {
      field: 'contact',
      function: 'truthy'
    },
    severity: 'error'
  }
});

const document = {
  openapi: '3.0.0',
  info: {
    title: 'Sample API',
    version: '1.0.0'
  },
  paths: {}
};

spectral.run(document).then(results => {
  console.log(results);
});

Other packages similar to @stoplight/spectral-core

eslint

ESLint is a popular linting tool for JavaScript and TypeScript. It allows you to define and enforce coding standards and best practices in your codebase. While it is primarily focused on JavaScript, it can be extended to support other languages and formats through plugins. Unlike @stoplight/spectral-core, which is specialized for JSON/YAML and API specifications, ESLint is more general-purpose.

ajv

Ajv is a JSON schema validator that allows you to validate JSON data against JSON schemas. It is highly performant and supports JSON Schema draft-07 and later. While Ajv focuses on schema validation, @stoplight/spectral-core provides more comprehensive linting capabilities, including custom rules and built-in rulesets for API specifications.

swagger-parser

Swagger Parser is a powerful library for parsing, validating, and dereferencing Swagger and OpenAPI definitions. It ensures that your API definitions are valid and can be used to resolve $ref pointers. While Swagger Parser focuses on parsing and validation, @stoplight/spectral-core offers more extensive linting and custom rule capabilities.

README

The README file is missing