OpenAPI-specific Formats not supported

I’m submitting a…

• bug report
• feature request

What is the current behavior?

Setting the format for an integer doesn’t work.

test.yaml:

openapi: "3.0.2"
info:
  title: "Test"
  description: "Test spec"
  version: "1.0.0"
  contact:
    name: "Rob"
tags:
  - name: tag1
servers:
  - url: http://example.com

paths:
  /:
    get:
      operationId: root
      tags:
        - tag1
      summary: root
      description: The root node
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                ip_address:
                  description: IP address (as a `long int`)
                  type: integer
                  format: int64
                  example: 2886989840
      responses:
        '200':
          description: Nothing returned

Run:

$ spectral lint test.yaml
Linting test.yaml
OpenAPI 3.x detected
Encountered error when running rule 'valid-example' on node at path '$,paths,/,get,requestBody,content,application/x-www-form-urlencoded,schema,properties,ip_address':
Error: unknown format "int64" is used in schema at path "#"
No errors or warnings found!

What is the expected behavior?

Spectral should not display:

Error: unknown format "int64" is used in schema at path "#"

Also, it should not display No errors or warnings found! when the line above starts with the word Error !

What is the motivation / use case for changing the behavior?

The Spec says that int64 is a valid format and the petstore-expanded example shows it in use.

Please tell us about your environment:

$ spectral --version
@stoplight/spectral/2.1.1 darwin-x64 node-v8.12.0

[philsturgeon]

Alright edging closer to a complete solution, you no longer need --skip-rule you can just upgrade to v2.3.1 and the errors will stop being thrown.

[philsturgeon]

@akrabat ok I dug into this and figured it out.

OpenAPI declares int64 is valid in the text doc, but formats are not defined in the OpenAPI metaschema so shoving that metaschema into a JSON Schema validator doesn’t make it 100% into an OpenAPI validator as expected.

We are then getting an error because AJV v6 (which we use) is defaulting to throwing exceptions for unknown formats:

> * unknownFormats: handling of unknown formats. Option values:
> 
>   * true (default) - if an unknown format is encountered the exception is thrown during schema compilation. If format keyword value is $data reference and it is unknown the validation will fail.
> "ignore" - to log warning during schema compilation and always pass validation (the default behaviour in versions before 5.0.0). This option is not recommended, as it allows to mistype format name and it won't be validated without any error message. This behaviour is required by JSON Schema specification.

Somebody out there has noticed this before and created BiteBit/ajv-oai which is a wrapper for AJV which also declares the OpenAPI formats, and tells AJV about them.

/**
 * OpenAPI 2.0 data types format
 * https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types
 */

/**
 * Check that the data is integer and int32
 * @param {number} data
 * @returns {boolean}
 */
function int32(data) {
  return (
    Number.isInteger(+data) &&
    RANGES.int32.max.greaterThanOrEqualTo(data) &&
    RANGES.int32.min.lessThanOrEqualTo(data)
  );
}

/**
 * Check that the data is integer and int64
 * @param {number} data
 * @returns {boolean}
 */
function int64(data) {
  return (
    Number.isInteger(+data) &&
    RANGES.int64.max.greaterThanOrEqualTo(data) &&
    RANGES.int64.min.lessThanOrEqualTo(data)
  );
}

We will need to either switch to using this package, or take a similar approach to adding these formats when we know OAS2/3 is being used.

A short term solution will be switch to using “ignore”, which means we are not catching mismatches in formats unknown to AJV, which will at least stop this error from happening, and stop people needing to --skip-rule=valid-example just go get spectral working,.

Somebody will update this issue when one of those two things happens.