Migration-Guide.md

Migration Guide

This migration guide is intended to help users migrate from the version 0.x pre-release of the IBM OpenAPI Validator to the new version 1.0 official release.

Minimum Node version

The minimum supported version of Node.js is now version 16.x (formerly 14.x).

Supported OpenAPI versions

The old v0.x pre-release validator supported both Swagger 2.x and OpenAPI 3.0.x documents. The new v1.x validator supports only OpenAPI 3.0.x documents.

CLI Changes

Changes were made to the command-line options supported by the validator:

1. In the v0.x pre-release validator, the -c/--config option was used to specify the name of the user's configuration file to use instead of .validaterc. In the new v1.x validator, this same option is now used to specify the name of your validator configuration file, which now has a completely different structure (see below).
2. In the v0.x pre-release validator, the -s/--report_statistics option was used to include the summary section in the validator output. In the new v1.x validator, the output will always include the summary section and you can now use the -s/--summary-only option to cause the validator to include only the summary section in the output and avoid logging individual validation messages.
3. The -d/--default_mode option is no longer supported. To achieve "default mode" with the new 1.x validator, simply avoid specifying any options (other than the files to be validated, perhaps), and the validator will revert to default behavior with respect to each of the options (e.g. validator output is colorized by default).
4. The -p/--print_validator_modules option is no longer supported.
5. The --debug option is no longer supported. In the new v1.x validator, you can achieve something similar by simply setting the log-level of the "root" logger to "debug" (e.g. --log-level debug).
6. The new v1.x validator will consider it an error if you request JSON output (e.g. --json) and specify more than one file to be validated on the command line. The v0.x pre-release validator did not detect this and would simply display each JSON results object one after another on the console, which would technically not be valid JSON. The JSON output mode is intended to be used with a single file argument so that only one JSON results object is displayed on the console. Therefore, the new v1.x validator will enforce that restriction.
7. In the v0.x pre-release validator, multi-word options (e.g. --report_statistics) would include _ (underscore) as the word delimiter, but the new v1.x validator uses - (dash) as the word delimiter (e.g. --errors_only is now --errors-only).

More details about the command-line options supported by the new v1.x validator can be found here.

New Validator Configuration File

The v0.x pre-release validator supported two different configuration files:

• .thresholdrc: this is where the warnings limit could be defined
• .validaterc: this is where you could configure rules, etc.

These files are no longer supported, but the new v1.x validator supports a more consistent interface in which each of the command-line options is also supported as a field within the new configuration file. This gives users the freedom to specify input options on the command-line, within a configuration file, or even a combination of the two (options specified on the command-line will take precedence over options defined in a configuration file). In addition, the new 1.x validator supports JSON, YAML and Javascript formats.

More details regarding the new v1.x validator's configuration file can be found here.

Validator Output

Text

The text output produced by the new v1.x validator is largely the same as that produced by the v0.x pre-release validator. One main difference is that the v1.x validator will now always include the summary section in the output and the -s/--summary-only option can be used to include only the summary section in the output.

JSON

The structure of the JSON output produced by the new 1.x validator is slightly different, and is now described by this schema. Also, the new 1.x validator will honor the --errors-only and --summary-only options when producing JSON output, whereas the v0.x pre-release validator did not. More details related to validator output can be found here.

API

The v0.x pre-release validator supported an API to enable users to invoke the validator programmatically from a javascript application. This API is no longer supported in the v1.x validator; however, the Spectral validator (on which the IBM OpenAPI Validator is based) provides a programmatic API for invoking Spectral from your javascript application code.

Ruleset Changes

This section contains information about changes that were made to the rules contained in the IBM Cloud Validation Ruleset.

Rule Id Changes

In the new v1.x validator, the rule id's were changed so that they now follow a more consistent naming convention. The following table provides a detailed mapping of old vs new rule id, along with any other change-related notes:

Previous Rule Id	New Rule Id	Notes
array-boundary, array-items	ibm-array-attributes	rules 'array-boundary' and 'array-items' were combined into the new 'ibm-array-attributes' rule
inline-property-schema, inline-request-schema, inline-response-schema	ibm-avoid-inline-schemas	rules 'inline-property-schema', 'inline-request-schema' and 'inline-response-schema' were combined into the new 'ibm-avoid-inline-schemas' rule
property-case-collision	ibm-avoid-property-name-collision
duplicate-path-parameter	ibm-avoid-repeating-path-parameters
binary-schemas	ibm-binary-schemas
collection-array-property	ibm-collection-array-property
content-entry-contains-schema	ibm-content-contains-schema
ibm-content-type-is-specific	ibm-content-type-is-specific
missing-required-property	ibm-define-required-properties
discriminator	ibm-discriminator-property
merge-patch-optional-properties	ibm-dont-require-merge-patch-properties
enum-case-convention	ibm-enum-casing-convention
ibm-error-content-type-is-json	ibm-error-content-type-is-json
response-error-response-schema	ibm-error-response-schemas
no-etag-header	ibm-etag-header
major-version-in-path	ibm-major-version-in-path
accept-parameter	ibm-no-accept-header
array-of-arrays	ibm-no-array-of-arrays
array-responses	ibm-no-array-responses
authorization-parameter	ibm-no-authorization-header
delete-body	ibm-no-body-for-delete
circular-refs	ibm-no-circular-refs
consecutive-path-param-segments	ibm-no-consecutive-path-parameter-segments
content-type-parameter	ibm-no-content-type-header
path-param-not-crn	ibm-no-crn-path-parameters
parameter-default	ibm-no-default-for-required-parameter
ref-sibling-duplicate-description	ibm-no-duplicate-description-with-ref-sibling
if-modified-since-parameter	ibm-no-if-modified-since-header
if-unmodified-since-parameter	ibm-no-if-unmodified-since-header
optional-request-body	ibm-no-optional-properties-in-required-body
examples-name-contains-space	ibm-no-space-in-example-name
unused-tag	ibm-openapi-tags-used
operation-summary	ibm-operation-summary
operation-id-case-convention	ibm-operationid-casing-convention
operation-id-naming-convention	ibm-operationid-naming-convention
pagination-style	ibm-pagination-style
parameter-case-convention	ibm-parameter-casing-convention
parameter-description	ibm-parameter-description
parameter-order	ibm-parameter-order
parameter-schema-or-content	ibm-parameter-schema-or-content
patch-request-content-type	ibm-patch-request-content-type
path-segment-case-convention	ibm-path-segment-casing-convention
precondition-header	ibm-precondition-headers
property-attributes	ibm-property-attributes
property-case-convention	ibm-property-casing-convention
property-inconsistent-name-and-type	ibm-property-consistent-name-and-type
property-description	ibm-property-description
ref-pattern	ibm-ref-pattern
content-entry-provided	ibm-request-and-response-content
request-body-object	ibm-requestbody-is-object
request-body-name	ibm-requestbody-name
response-status-codes	ibm-response-status-codes
schema-description	ibm-schema-description
schema-type	ibm-schema-type
valid-type-format	ibm-schema-type-format
ibm-sdk-operations	ibm-sdk-operations
security-scheme-attributes	ibm-securityscheme-attributes
security-schemes	ibm-securityschemes
server-variable-default-value	ibm-server-variable-default-value
string-boundary	ibm-string-attributes
response-example-provided	ibm-success-response-example
prohibit-summary-sentence-style	ibm-summary-sentence-style
valid-path-segments	ibm-valid-path-segments
description-mentions-json	n/a	this rule was removed

Detailed reference information about each rule can be found here.

Logging Implemented

In the new v1.x validator, we've implemented a common message logging facility that is described here.

One of the benefits of this change is that it is now fairly easy to obtain more detailed information (i.e. debug information) from a particular rule. Simply set the rule's log-level to be debug.

For example, suppose that the ibm-pagination-style rule is detecting violations in your API, but you're not quite sure why those violations are being flagged, and hence you're not sure how to fix them. You could add the --log-level ibm-pagination-style=debug (or -l ibm-pagination-style=debug) option to your validator command to enable debug logging for this rule. You would then see additional information displayed by the validator as the rule examines your API. Hopefully this can then lead to a solution.