npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@baloise/spectral-rules

v1.4.1

Published

Custom Spectral API Linter ruleset for Baloise API Guidelines based on Zalando API guidelines.

Downloads

10,540

Readme

Gitpod

spectral-ruleset

👷🚧🛠️ in development 👷🚧🛠️

Custom Spectral API Linter ruleset for Zalando RESTful API Guidelines.

There are two flavors of the ruleset:

Please refer to the table below for details.

The ruleset spectral:oas is disabled by default. If you like to enable these rules again use

echo "extends: [https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/zalando.yml, spectral:oas]" \
    > .spectral.yml

Use it

Possibility A: Reference via Github URL

# zalando flavor:
npx @stoplight/spectral-cli lint \
    --ruleset https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/zalando.yml \
    example/example-openapi.yml

# baloise flavor:
npx @stoplight/spectral-cli lint \
    --ruleset https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/baloise.yml \
    example/example-openapi.yml

Or just create a .spectral.yml extending it

echo "extends: [https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/baloise.yml]" \
    > .spectral.yml
npx @stoplight/spectral-cli lint example/example-openapi.yml

If you're behind a proxy you can pass it via PROXY environment variable:

PROXY=<PROXY URL> npx @stoplight/spectral lint <...>

Possibility B: Install via npm

npm i @baloise/spectral-rules

# zalando flavor:
npx @stoplight/spectral-cli lint \
    --ruleset ./node_modules/@baloise/spectral-rules/zalando.yml \
    example/example-openapi.yml

# baloise flavor:
npx @stoplight/spectral-cli lint \
    --ruleset ./node_modules/@baloise/spectral-rules/baloise.yml \
    example/example-openapi.yml

Or just create a .spectral.yml extending it

echo "extends: [./node_modules/@baloise/spectral-rules/baloise.yml]" > .spectral.yml
npx @stoplight/spectral-cli lint example/example-openapi.yml

Development

Adding a new Rule

  1. Choose a new, unsupported rule from the table below. For example #151 MUST specify success and error responses.
  2. Make sure tests/fixtures/base-openapi.yml satisfies the rule.
  3. Add a test tests/151-MUST-specify-success-and-error-responses.test.ts that
    1. Takes the base-openapi.yaml as input
    2. Modifies it to break the new rule
    3. Expect that spectral finds the error (this will fail for now)
  4. Extend zalando.yml with the new rule, so that the previously added test succeeds. See https://meta.stoplight.io/docs/spectral/docs/guides/4-custom-rulesets.md on how to define custom rules.
  5. Add a :heavy_check_mark: to the table below.
  6. Create a PR

Alternative baloise rules are marked by appending the rule number with an a. For example zalando rule #115 versus baloise rule #115a. The zalando rule #115 is defined in zalando.yml. The baloise rule #115a is defined in baloise.yml while deactivating the original zalando rule #115a.

Setup

npm install
npm run test
npm run lint
npm run lint-fix # format source files

Currently supported rules from the zalando restful-api-guidelines

:heavy_check_mark: = rule implemented
:grey_exclamation: = rule implementation not possible or to complex

| id | title | zalando.yml | baloise.yml | prio (A, B, C)| |----------------|------------------------------------------------------------------------------------------------------| -- | --- | --- | | #100 | MUST follow API first principle | :grey_exclamation: | :grey_exclamation: | B | | #101 | MUST provide API specification using OpenAPI | :grey_exclamation: | :grey_exclamation: | A | | #102 | SHOULD provide API user manual | - | - | C | | #103 | MUST write APIs using U.S. English | :grey_exclamation: | :grey_exclamation: | A | | #104 | MUST secure endpoints with OAuth 2.0 | - | - | B | | #105 | MUST define and assign permissions (scopes) | - | - | B | | #106 | MUST not break backward compatibility | - | - | B | | #107 | SHOULD prefer compatible extensions | :grey_exclamation: | :grey_exclamation: | - | | #108 | MUST prepare clients accept compatible API extensions | :grey_exclamation: | :grey_exclamation: | C | | #109 | SHOULD design APIs conservatively | :grey_exclamation: | :grey_exclamation: | - | | #110 | MUST always return JSON objects as top-level data structures | :heavy_check_mark: | :heavy_check_mark: | A | | #111 | MUST treat Open API specification as open for extension by default | :grey_exclamation: | :grey_exclamation: | - | | #112 | SHOULD used open-ended list of values (x-extensible-enum) for enumerations | :heavy_check_mark: | :heavy_check_mark: | - | - | | #113 | SHOULD avoid versioning | :grey_exclamation: | :grey_exclamation: | B | | #114 | MUST use media type versioning | :grey_exclamation: | :grey_exclamation: | - | | #115 | MUST not use URI versioning | :heavy_check_mark: | - | A | | #115a | CAN use correct URI versioning: ^((?!.*\/v\d+(\/.*)?\/v\d+)\/.*)$ | - | :heavy_check_mark: | A | | #116 | MUST use semantic versioning | :heavy_check_mark: | :heavy_check_mark: | B | | #118 | MUST property names must be ASCII snake_case (and never camelCase): ^[a-z_][a-z_0-9]*$ | :heavy_check_mark: | - | A | | #118a | MUST property names must be ASCII camelCase: ^[a-z]+((\d)([A-Z0-9][a-z0-9]+))*([A-Z])?$ | - | :heavy_check_mark: | A | | #120 | SHOULD pluralize array names | - | - | B | | #122 | MUST not use null for boolean properties | :grey_exclamation: | :grey_exclamation: | - | | #123 | MUST use same semantics for null and absent properties | :grey_exclamation: | :grey_exclamation: | - | | #124 | SHOULD not use null for empty arrays | :grey_exclamation: | :grey_exclamation: | - | | #125 | SHOULD represent enumerations as strings | - | - | ? | | #126 | SHOULD define dates properties compliant with RFC 3339 | - | - | ? | | #127 | SHOULD define time durations and intervals properties conform to ISO 8601 | :grey_exclamation: | :grey_exclamation: | - | | #128 | SHOULD use standards for country, language and currency codes | - | - | ? | | #129 | MUST use lowercase separate words with hyphens for path segments | :heavy_check_mark: | :heavy_check_mark: | A | | #130 | MUST use snake_case (never camelCase) for query parameters | :heavy_check_mark: | - | B | | #130a | MUST use camelCase (never snake_case) for query parameters | - | :heavy_check_mark: | B | | #132 | SHOULD prefer hyphenated-pascal-case for HTTP header fields | :heavy_check_mark: | :heavy_check_mark: | B | | #133 | MAY use standardized headers | - | - | - | | #134 | MUST pluralize resource names | - | - | A | | #135 | SHOULD not use /api as base path | :heavy_check_mark: | :heavy_check_mark: | A | | #136 | MUST use normalized paths without empty path segments and trailing slashes | :heavy_check_mark: | :heavy_check_mark: | B | | #137 | MUST stick to conventional query parameters | :grey_exclamation: | :grey_exclamation: | - | | #138 | MUST avoid actions — think about resources | :grey_exclamation: | :grey_exclamation: | A | | #139 | SHOULD model complete business processes | :grey_exclamation: | :grey_exclamation: | - | | #140 | SHOULD define useful resources | :grey_exclamation: | :grey_exclamation: | - | | #141 | MUST keep URLs verb-free | :grey_exclamation: | :grey_exclamation: | A | | #142 | MUST use domain-specific resource names | :grey_exclamation: | :grey_exclamation: | - | | #143 | MUST identify resources and sub-resources via path segments | - | - | - | | #144 | SHOULD only use UUIDs if necessary | :grey_exclamation: | :grey_exclamation: | - | | #145 | MAY consider using (non-)nested URLs | :grey_exclamation: | :grey_exclamation: | - | | #146 | SHOULD limit number of resource types | :heavy_check_mark: | :heavy_check_mark: | B | | #147 | SHOULD limit number of sub-resource levels | :heavy_check_mark: | :heavy_check_mark: | B | | #148 | MUST use HTTP methods correctly | :grey_exclamation: | :grey_exclamation: | A | | #149 | MUST fulfill common method properties | :grey_exclamation: | :grey_exclamation: | - | | #150 | MUST use standard HTTP status codes | :heavy_check_mark: | | - | | #150a | MUST use additional standard HTTP status codes | - | :heavy_check_mark: | - | | #151 | MUST specify success and error responses | :heavy_check_mark: | :heavy_check_mark: | B | | #152 | MUST use code 207 for batch or bulk requests | :grey_exclamation: | :grey_exclamation: | C | | #153 | MUST use code 429 with headers for rate limits | :grey_exclamation: | :grey_exclamation: | C | | #154 | MUST define collection format of header and query parameters | :grey_exclamation: | :grey_exclamation: | - | | #155 | SHOULD reduce bandwidth needs and improve responsiveness | :grey_exclamation: | :grey_exclamation: | - | | #156 | SHOULD use gzip compression | :grey_exclamation: | :grey_exclamation: | - | | #157 | SHOULD support partial responses via filtering | :grey_exclamation: | :grey_exclamation: | - | | #158 | SHOULD allow optional embedding of sub-resources | :grey_exclamation: | :grey_exclamation: | - | | #159 | MUST support pagination | - | - | - | | #160 | SHOULD prefer cursor-based pagination, avoid offset-based pagination | - | - | - | | #161 | SHOULD use pagination links where applicable | - | - | - | | #162 | MUST use REST maturity level 2 | - | - | - | | #163 | MAY use REST maturity level 3 - HATEOAS | - | - | - | | #164 | MUST use common hypertext controls | - | - | - | | #165 | SHOULD use simple hypertext controls for pagination and self-references | - | - | - | | #166 | MUST not use link headers with JSON entities | - | - | - | | #167 | MUST use JSON to encode structured data | - | - | - | | #168 | MAY use non JSON media types for binary data or alternative content representations | :grey_exclamation: | :grey_exclamation: | - | | #169 | MUST use standard date and time formats | :heavy_check_mark: | - | A | | #170 | SHOULD use standards for country, language and currency codes | - | - | B | | #171 | MUST define format for number and integer types | :heavy_check_mark: | - | - | | #172 | SHOULD prefer standard media type name application/json | :heavy_check_mark: | :heavy_check_mark: | B | | #173 | MUST use the common money object | :grey_exclamation: | :grey_exclamation: | - | | #174 | MUST use common field names and semantics | :grey_exclamation: | :grey_exclamation: | - | | #176 | MUST support problem JSON | :heavy_check_mark: | :heavy_check_mark: | - | | #177 | MUST not expose stack traces | :grey_exclamation: | :grey_exclamation: | - | | #178 | MUST use Content-* headers correctly | :grey_exclamation: | :grey_exclamation: | - | | #179 | MAY use Content-Location header | :grey_exclamation: | :grey_exclamation: | - | | #180 | SHOULD use Location header instead of Content-Location header | - | - | - | | #181 | MAY consider to support Prefer header to handle processing preferences | :grey_exclamation: | :grey_exclamation: | - | | #182 | MAY consider to support ETag together with If-Match/If-None-Match header | :grey_exclamation: | :grey_exclamation: | - | | #183 | SHOULD use only the specified proprietary Zalando headers | - | - | - | | #184 | MUST propagate proprietary headers | - | - | - | | #185 | MUST obtain approval of clients before API shut down | :grey_exclamation: | :grey_exclamation: | - | | #186 | MUST collect external partner consent on deprecation time span | :grey_exclamation: | :grey_exclamation: | - | | #187 | MUST reflect deprecation in API specifications | :grey_exclamation: | :grey_exclamation: | - | | #188 | MUST monitor usage of deprecated API scheduled for sunset | :grey_exclamation: | :grey_exclamation: | - | | #189 | SHOULD add Deprecation and Sunset header to responses | :grey_exclamation: | :grey_exclamation: | - | | #190 | SHOULD add monitoring for Deprecation and Sunset header | :grey_exclamation: | :grey_exclamation: | - | | #191 | MUST not start using deprecated APIs | :grey_exclamation: | :grey_exclamation: | B | | #192 | MUST publish Open API specification | :grey_exclamation: | :grey_exclamation: | A | | #193 | SHOULD monitor API usage | :grey_exclamation: | :grey_exclamation: | - | | #194 | MUST treat events as part of the service interface | - | - | - | | #195 | MUST make event schema available for review | - | - | - | | #196 | MUST ensure event schema conforms to Open API schema object | - | - | - | | #197 | MUST ensure that events are registered as event types | - | - | - | | #198 | MUST ensure that events conform to a well-known event category | - | - | - | | #199 | MUST ensure that events define useful business resources | - | - | - | | #200 | MUST ensure that events do not provide sensitive data | - | - | - | | #201 | MUST use the general event category to signal steps and arrival points in business processes | - | - | - | | #202 | MUST use data change events to signal mutations | - | - | - | | #203 | SHOULD provide means for explicit event ordering | - | - | - | | #204 | SHOULD use the hash partition strategy for data change events | - | - | - | | #205 | SHOULD ensure that data change events match the APIs resources | - | - | - | | #207 | MUST indicate ownership of event types | - | - | - | | #208 | MUST define event payloads compliant with overall API guidelines | - | - | - | | #209 | MUST maintain backwards compatibility for events | - | - | - | | #210 | SHOULD avoid additionalProperties in event type definitions | - | - | - | | #211 | MUST use unique event identifiers | - | - | - | | #212 | SHOULD design for idempotent out-of-order processing | - | - | - | | #213 | MUST follow naming convention for event type names | - | - | - | | #214 | MUST prepare event consumers for duplicate events | - | - | - | | #215 | MUST provide API identifiers | :heavy_check_mark: | :heavy_check_mark: | - | - | | #216 | SHOULD define maps using additionalProperties | - | - | - | | #217 | MUST use full, absolute URI | - | - | - | | #218 | MUST contain API meta information | :heavy_check_mark: | :heavy_check_mark: | - | - | | #219 | MUST provide API audience | :heavy_check_mark: | - | - | - | | #219a | MUST provide baloise API audience | - | :heavy_check_mark: | - | - | | #220 | MUST use most specific HTTP status codes | :grey_exclamation: | :grey_exclamation: | - | | #223 | MUST-SHOULD use functional naming schema | :grey_exclamation: | :grey_exclamation: | - | | #224 | MUST follow naming convention for hostnames | :grey_exclamation: | :grey_exclamation: | - | | #225 | MUST follow naming convention for permissions (scopes) | :grey_exclamation: | :grey_exclamation: | - | | #226 | MUST document implicit filtering | :grey_exclamation: | :grey_exclamation: | - | | #227 | MUST document cachable GET, HEAD, and POST endpoints | :grey_exclamation: | :grey_exclamation: | - | | #228 | MUST use URL-friendly resource identifiers: [a-zA-Z0-9:._-/]* | :grey_exclamation: | :grey_exclamation: | A | | #229 | SHOULD consider to design POST and PATCH idempotent | :grey_exclamation: | :grey_exclamation: | - | | #230 | MAY consider to support Idempotency-Key header | :grey_exclamation: | :grey_exclamation: | - | | #231 | Should use secondary key for idempotent POST design | :grey_exclamation: | :grey_exclamation: | - | | #233a | MUST request must use tracing headers | - | :heavy_check_mark: | - | | #234 | MUST only use durable and immutable remote references | :grey_exclamation: | :grey_exclamation: | - | | #235 | SHOULD name date/time properties with _at suffix | - | - | - | | #236 | SHOULD design simple query languages using query parameters | :grey_exclamation: | :grey_exclamation: | - | | #237 | SHOULD design complex query languages using JSON | :grey_exclamation: | :grey_exclamation: | - | | #238 | SHOULD use standardized property formats | :grey_exclamation: | :grey_exclamation: | - | | #239 | SHOULD encode embedded binary data in base64url | :grey_exclamation: | :grey_exclamation: | - | | #240 | SHOULD declare enum values using UPPER_SNAKE_CASE format | :heavy_check_mark: | :heavy_check_mark: | - | - | | #241 | MAY expose compound keys as resource identifiers | :grey_exclamation: | :grey_exclamation: | - |