Validation Tools

@openretailing.org/openretailing-spec-validator

This is a simple npm project which consumes a .yaml API specification (and loads its references, assuming they are available) and compares them to the OpenRetailing design rules.

Using the npm package

• Prerequisites:
  • Ensure you have npm installed.
• Installing:
  • Via command line, install the package globally using npm install -g @openretailing.org/openretailing-spec-validator
• Usage:
  • Via command line, type in open-retailing-spec-validator -f path/to/your/api/spec.yaml
  • The path to the YAML spec can be absolute or relative.
• Version Checking:
  • To check the latest version on the registry, type npm view @openretailing.org/openretailing-spec-validator version
  • To check the local version on your machine, type npm list -g @openretailing.org/openretailing-spec-validator
  • To update to the latest version, type npm update -g @openretailing.org/openretailing-spec-validator

Using the GitLab repo

• Prerequisites:
  • Ensure you have npm and node.js installed.
  • Last tested on node version 10.16.0 (Windows) and 12.18.0 (Mac OS)
    • This may not be compatible with tools such as homebrew; if in doubt, check your versions
  • These are not OpenRetailing-owned, and are documented elsewhere. See https://www.npmjs.com/get-npm
• Downloading: download this repository at gitlab.openretailing.org, or if you are a git user, use git to clone the repository
• Installing:
  • Ensure you are in the application's folder (where package.json and validator.js are)
  • run npm install which will download the required additional components
• Usage: npm start -- -f path/to/your/api/spec.yaml -v
  • The -- is necessary
  • To simplify the output, omit -v
  • To output to a file, use a command supported by your operating system e.g. npm start -- -f path/to/your/api/spec.yaml > report.csv
  • If you get an error Error: Cannot find module 'something' the previous step has not been done or has not worked
• To self-test the application: npm start -- -f deliberate_mistakes/forecourt-api-collections/api/fdc.yaml

The output of this application is currently a semicolon-delimited list of results, suitable for importing into a spreadsheet application.

Rule specifications included

| Rule | Summary | Validator | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 2.1 | Overall API Design: Use Open API Specification (OAS) 3.0 as an Interface Definition Language (IDL). [v1.5.1] | Validator should error if it cannot parse the file as an OAS specification. | | 3 | Versioning: API versioning should be in 3 parts: major (breaking change), minor (new functionality), revision/patch (fixes, minor extensions, documentation changes etc.). [v1.5.1] | Validator should error if the info.version element is not in the format of v{n}.{n}.{n}, where {n} are true integers. | | 4.1.1.2 | Resource Domain Objects: Response messages should contain an object graph coded in JSON, either defined in the main API definition file itself (e.g. short or repeated responses like errors) or a separate JSON schema referenced from the main file. [v1.5.1] | Validator should warn if any response element does not contain content.application/json.schema. | | 4.1.1.4 | HTTP Methods: GET uses a QueryString to retrieve data, POST uses body info to identify a new resource (NOT a QueryString), PUT is used on both individual or collected resources, DELETE uses QueryString as well to delete an individual resource, collection, or part of a collection. [v1.5.1] | Validator should error if POST methods have query strings. GET and DELETE are valid with or without query strings, so no validation is required. PUT is standard HTTP usage and is not automatable. | | 4.1.1.5 | URI Construction: Path components should be (i) nouns; (ii) LCC or all lowercase; and (iii) alphanumeric only. [v1.5.1] | Validator is unable to check for nouns vs verbs. However, it should error if a path includes any characters that aren't alphanumeric and warn if a path is not all lower case (because the validator cannot reliably identify the starts of individual words) must be only lowercase, using alphanumeric characters. | | 4.1.1.5 | URI Construction: Paths should be used to indicate version number (i.e. should not be included in Content-Type headers) and only the major version number should be included. [v1.5.1] | Validator should error if there are no Content-Type headers defined and set to application/json. | | 4.1.1.5 | URI Construction: Suggestion is: {APIName} / v{APIVersionNumber} / {resource} ? {parameters} # {fragment-identifier} where parameters are a name/value pair separated with '&' and {APIVersionNumber} is the major API version number. [v1.5.1] | {APIName} / v{APIVersionNumber} are defined in server basepaths, rather than in the API's paths, therefore Validator should error if server base paths do not end in /v{n}, where {n} is a true integer. | | 4.1.1.6 | HTTP Headers: Custom headers may be permitted but generally should use Accept (how a resource is represented), Accept-language (language of the representation, for internationalisation), Authorization (for security), Accept-encoding (to compress server response), Cache-control (to direct proxy servers NOT to cache responses), and Content-type (info about the type of query or response). [v1.6] | Validator should warn if any HTTP headers are of a type not in the adjacent list. | | 4.1.1.9 | Return Codes: 200 OK, 201 Created, 202 Accepted (for async), 204 No Content (no body in return message), 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 405 Method Not Allowed (for resource), 408 Request Timeout (server state expired), 426 Upgrade Required, 500 Internal Server Error. [v1.5.1] | Validator should error if any responses use an HTTP status that is not in the adjacent list. | | 4.1.1.10 | Content Type: Should use MIME-type application/json. If Accept header is being used, it should always indicate this type. [v1.5.1] | Validator should error if any HTTP headers of type Accept have a value other than application/json. | | 4.1.1.11 | Space-Saving Encoding: gzip is an acceptable format if it's the client's choice, server support is optional. [v1.5.1] | Validator should warn if there is a Content-Encoding header with any value other than gzip. | | 4.1.1.14 | Server-Sent Events: The top-level call to open the events stream must have a description field. Individual events within the SSE Events stream must have the fields eventID (unique id in the event stream), event (string defining the kind of event), and a description field that matches one of the enums listed under the oneOf field. [v2.0] | Validator should error if any of the fields are missing or if the description does not match an enum. | | 4.1.1.14 | Server-Sent Events: The number of enums in each event must match the number of actual objects under the SSE Events object. [v2.0] | Validator should error if the number of enums does not match the number of actual objects present in the spec's top-level EventObject object. | | 4.4 | The dependencies.txt File: Each line of the file should be of the form {project-name} / {label} / {branch}, where one of “label” or “branch” must be populated; {project-name} must not have whitespace, {label} must be of form "vX" or "vX.X" and {branch} must be of form "X-dev", where X is an integer. [v1.6] | Validator should error if any line in the file does not match one of the three allowed formats or does not conform to the specified naming conventions. | | 5 | Security Inclusion The API must include the security arrays and the securitySchemes definitions. [v2.0] | Validator should error if either the security section or securitySchemes section does not exist. | | 6.1 | Boolean Enumeration All boolean properties should be defined as an enumeration. [v2.0] | Validator should warn if there is a boolean field defined in the properties of an API call. | | 6.2 | Number Bounds All integer and number properties should have a minimum and maximum constraints defined. [v2.0] | Validator should warn if there is a number or an integer field defined in the properties of an API call. | | 6.3 | Array Bounds All array properties must have a maximum limit of the form maxItems for the number of properties in the array defined. [v2.0] | Validator should error if there is no maxItems property defined for an array within an API call. | | 6.4 | Time Format All properties denoting time should be defined with a format of date, time, or date-time. [v2.0] | Validator should warn if there is a time property field defined that the property should have its format defined as either date, time, or date-time. |

Rules intentionally omitted

| Rule | Summary | Validator | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | 4.1.1.9.1 | Return Code 2XX vs 4XX/5XX There is an option for errors to be returned nonetheless with a 200 code but with the error in the return status message instead. [v1.6] | Not implemented because the choice of which return code/status to use is optional. |