frosting-spectral-jsonapi-ruleset

A Stoplight/Spectral linting ruleset for the Frosting API specification.

Overview

The Frosting API Specification is a JSON:API Profile. Essentially, it is a more restrictive, but wholly compatible version of the JSON:API specification.

Integration

Integrating this ruleset into your repository's CI checks can be done using the following steps:

1. Create a new workflow in your .github/workflows directory. Call it frosting-api-checks.yml
2. Provide the workflow with the permissions and git hooks

on:
  pull_request:

permissions:
  id-token: write
  contents: write
  checks: write
  pull-requests: write

3. (Optional) Auto-generate your applications OpenAPI3 Spec file. This is recommended, as non-autogenerated specs often become out-of-date.
4. Use the composite workflow provided in ci-tools as follows:

- name: run spectral
  uses: LeafLink/ci-tools/frosting-openapi-lint@main
  with:
    openapi-spec-path: ./path/to/your/openapi3spec.yaml

5. (Optional) Commit the verified OpenAPI3 spec to the pull request.

- name: commit oas
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    git config user.email "automation@leaflink.com"
    git config user.name "LeafLink Automation"
    if [[ `git status --porcelain | grep docs/auto-spec/frosting-oas.yaml` ]]; then
      git add ./docs/auto-spec/frosting-oas.yaml
      git commit -m "Automated: Updating validated OAS"
      git push
    fi
  shell: bash

Example

An example project is included in ./example. The example includes a Frosting/JSON:API compat OpenAPI specification called frosting-example.yaml. As well as an example Spectral config file called .spectral.yaml.

To use the example, cd into the example directory and run spectral lint frosting-example.yaml.

Organization

General Organization:

• Forked Ruleset
  • ./rules, root
  • We should not be altering these files.
• LeafLink Ruleset
  • ./rules/ll
  • Contains all custom rulesets added to this repo in addition to the original forked ruleset.

Compiling

Mutli-file rulesets can be compiled down to single yaml files. To do this, use the /bin/compile.js script. Standard compilation can be done with npm run compile. This command will generate a zipped artifact in the dist/ directory, which contains a single YAML file containing every rule specified in the ruleset, and a functions directory for any and all defined custom functions.

frosting-ruleset.compiled.zip
  functions/
    custom-function.js
    inflection-check.js
  frosting-ruleset.compiled.yaml

To use the artifact, unzip it and point spectral at the yaml file from the top level of the artifact structure. Ensure the functions directory and that top-level yaml file reside in the same directory.

Development

Naming Conventions

All new rulesets should be contained in ./rules/ll. When adding a new ruleset, there's some basic conventions for file naming:

• If the rule was directly derived from the Frosting API Specification document , then ruleset file names should begin with frosting-profile-.
• If the rule is directly derived from the JSON:API Specification or the Frosting API Specification references the JSON:API Specification, then ruleset file names should begin with jsonapi-.

These naming conventions exist to help us determine where a rule came from at a glance.

License

The original ruleset is based on and forked from GitHub user "jmule42", and license is linked below.

MIT License