[WIP] Alternative OAS3 JSON Schema #1270

webron · 2017-07-14T00:18:00Z

This is a proposal for an alternative JSON Schema provided by #1236.

The work done in #1236 is good but:

It is too permissive - it allows things that should not validate, for example, a parameter with both content and schema (and a few other cases).
It doesn't cover types properly.
As far as I understand, it adds a couple of restrictions that are not provided in the spec itself.

The reasons for creating a new PR instead of suggesting fixes to #1236:

Editing JSON Schemas can be a pain, and trying to navigate through different styles is not easy.
The amount of changes to make it less permissive is quite large.
I had about 80% of the schema ready...

Odd things about this version:

It's a JSON Schema written in YAML. It's just easier to write and edit and.. read. Easy enough to convert to JSON if this PR is accepted.
To make it more restrictive, there are somewhat a lot of duplication in the schema. Using allOf to reuse things didn't work for me due to additionalProperties: false. If anyone wants to take a crack and minimizing it, by all means... I just wanted to get a working version.

What's missing:

It doesn't cover checking of style/explode inside Request Bodies where it's multipart. That was just too much for me for now.
Testing. I'm willing to bet there are bugs in it.
JSON Schema decorations (version, id, $schema and so on).

Pinging @darrelmiller as he asked to be pinged.

Pinging @MikeRalphson for assistance in testing - would really appreciate if you can take a crack at it.

I'm sure converting the YAML to JSON is going to be easy enough.

fehguy · 2017-07-14T03:57:30Z

👍

timburks · 2017-07-14T04:53:30Z

Glad to see effort going into this. The schema that I automatically generated from the spec is easy to reexport as YAML, which I'll append for comparison. The most apparent difference to me is that you've flattened out some intermediate structures.

title: A JSON Schema for OpenAPI 3.0.
id: http://openapis.org/v3/schema.json#
$schema: http://json-schema.org/draft-04/schema#
type: object
description: This is the root document object of the OpenAPI definition.
required:
- openapi
- info
- paths
additionalProperties: false
patternProperties:
  ^x-:
    $ref: '#/definitions/specificationExtension'
properties:
  openapi:
    type: string
  info:
    $ref: '#/definitions/info'
  servers:
    type: array
    items:
      $ref: '#/definitions/server'
    uniqueItems: true
  paths:
    $ref: '#/definitions/paths'
  components:
    $ref: '#/definitions/components'
  security:
    type: array
    items:
      $ref: '#/definitions/securityRequirement'
    uniqueItems: true
  tags:
    type: array
    items:
      $ref: '#/definitions/tag'
    uniqueItems: true
  externalDocs:
    $ref: '#/definitions/externalDocs'
definitions:
  info:
    type: object
    description: The object provides metadata about the API. The metadata can be used
      by the clients if needed, and can be presented in editing or documentation generation
      tools for convenience.
    required:
    - title
    - version
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      title:
        type: string
      description:
        type: string
      termsOfService:
        type: string
      contact:
        $ref: '#/definitions/contact'
      license:
        $ref: '#/definitions/license'
      version:
        type: string
  contact:
    type: object
    description: Contact information for the exposed API.
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      name:
        type: string
      url:
        type: string
      email:
        type: string
  license:
    type: object
    description: License information for the exposed API.
    required:
    - name
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      name:
        type: string
      url:
        type: string
  server:
    type: object
    description: An object representing a Server.
    required:
    - url
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      url:
        type: string
      description:
        type: string
      variables:
        $ref: '#/definitions/serverVariables'
  serverVariable:
    type: object
    description: An object representing a Server Variable for server URL template
      substitution.
    required:
    - default
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      enum:
        type: array
        items:
          type: string
        uniqueItems: true
      default:
        type: string
      description:
        type: string
  components:
    type: object
    description: Holds a set of reusable objects for different aspects of the OAS.
      All objects defined within the components object will have no effect on the
      API unless they are explicitly referenced from properties outside the components
      object.
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      schemas:
        $ref: '#/definitions/schemasOrReferences'
      responses:
        $ref: '#/definitions/responsesOrReferences'
      parameters:
        $ref: '#/definitions/parametersOrReferences'
      examples:
        $ref: '#/definitions/examplesOrReferences'
      requestBodies:
        $ref: '#/definitions/requestBodiesOrReferences'
      headers:
        $ref: '#/definitions/headersOrReferences'
      securitySchemes:
        $ref: '#/definitions/securitySchemesOrReferences'
      links:
        $ref: '#/definitions/linksOrReferences'
      callbacks:
        $ref: '#/definitions/callbacksOrReferences'
  paths:
    type: object
    description: Holds the relative paths to the individual endpoints and their operations.
      The path is appended to the URL from the `Server Object` in order to construct
      the full URL.  The Paths MAY be empty, due to ACL constraints.
    additionalProperties: false
    patternProperties:
      ^/:
        $ref: '#/definitions/pathItem'
      ^x-:
        $ref: '#/definitions/specificationExtension'
  pathItem:
    type: object
    description: Describes the operations available on a single path. A Path Item
      MAY be empty, due to ACL constraints. The path itself is still exposed to the
      documentation viewer but they will not know which operations and parameters
      are available.
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      $ref:
        type: string
      summary:
        type: string
      description:
        type: string
      get:
        $ref: '#/definitions/operation'
      put:
        $ref: '#/definitions/operation'
      post:
        $ref: '#/definitions/operation'
      delete:
        $ref: '#/definitions/operation'
      options:
        $ref: '#/definitions/operation'
      head:
        $ref: '#/definitions/operation'
      patch:
        $ref: '#/definitions/operation'
      trace:
        $ref: '#/definitions/operation'
      servers:
        type: array
        items:
          $ref: '#/definitions/server'
        uniqueItems: true
      parameters:
        type: array
        items:
          $ref: '#/definitions/parameterOrReference'
        uniqueItems: true
  operation:
    type: object
    description: Describes a single API operation on a path.
    required:
    - responses
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      tags:
        type: array
        items:
          type: string
        uniqueItems: true
      summary:
        type: string
      description:
        type: string
      externalDocs:
        $ref: '#/definitions/externalDocs'
      operationId:
        type: string
      parameters:
        type: array
        items:
          $ref: '#/definitions/parameterOrReference'
        uniqueItems: true
      requestBody:
        $ref: '#/definitions/requestBodyOrReference'
      responses:
        $ref: '#/definitions/responses'
      callbacks:
        $ref: '#/definitions/callbacksOrReferences'
      deprecated:
        type: boolean
      security:
        type: array
        items:
          $ref: '#/definitions/securityRequirement'
        uniqueItems: true
      servers:
        type: array
        items:
          $ref: '#/definitions/server'
        uniqueItems: true
  externalDocs:
    type: object
    description: Allows referencing an external resource for extended documentation.
    required:
    - url
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      description:
        type: string
      url:
        type: string
  parameter:
    type: object
    description: Describes a single operation parameter.  A unique parameter is defined
      by a combination of a name and location.
    required:
    - name
    - in
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      name:
        type: string
      in:
        type: string
      description:
        type: string
      required:
        type: boolean
      deprecated:
        type: boolean
      allowEmptyValue:
        type: boolean
      style:
        type: string
      explode:
        type: boolean
      allowReserved:
        type: boolean
      schema:
        $ref: '#/definitions/schemaOrReference'
      example:
        $ref: '#/definitions/any'
      examples:
        $ref: '#/definitions/examplesOrReferences'
      content:
        $ref: '#/definitions/mediaTypes'
  requestBody:
    type: object
    description: Describes a single request body.
    required:
    - content
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      description:
        type: string
      content:
        $ref: '#/definitions/mediaTypes'
      required:
        type: boolean
  mediaType:
    type: object
    description: Each Media Type Object provides schema and examples for the media
      type identified by its key.
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      schema:
        $ref: '#/definitions/schemaOrReference'
      example:
        $ref: '#/definitions/any'
      examples:
        $ref: '#/definitions/examplesOrReferences'
      encoding:
        $ref: '#/definitions/encodings'
  encoding:
    type: object
    description: A single encoding definition applied to a single schema property.
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      contentType:
        type: string
      headers:
        $ref: '#/definitions/headers'
      style:
        type: string
      explode:
        type: boolean
      allowReserved:
        type: boolean
  responses:
    type: object
    description: A container for the expected responses of an operation. The container
      maps a HTTP response code to the expected response.  The documentation is not
      necessarily expected to cover all possible HTTP response codes because they
      may not be known in advance. However, documentation is expected to cover a successful
      operation response and any known errors.  The `default` MAY be used as a default
      response object for all HTTP codes  that are not covered individually by the
      specification.  The `Responses Object` MUST contain at least one response code,
      and it  SHOULD be the response for a successful operation call.
    additionalProperties: false
    patternProperties:
      ^([0-9X]{3})$:
        $ref: '#/definitions/responseOrReference'
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      default:
        $ref: '#/definitions/responseOrReference'
  response:
    type: object
    description: Describes a single response from an API Operation, including design-time,
      static  `links` to operations based on the response.
    required:
    - description
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      description:
        type: string
      headers:
        $ref: '#/definitions/headersOrReferences'
      content:
        $ref: '#/definitions/mediaTypes'
      links:
        $ref: '#/definitions/linksOrReferences'
  callback:
    type: object
    description: A map of possible out-of band callbacks related to the parent operation.
      Each value in the map is a Path Item Object that describes a set of requests
      that may be initiated by the API provider and the expected responses. The key
      value used to identify the callback object is an expression, evaluated at runtime,
      that identifies a URL to use for the callback operation.
    additionalProperties: false
    patternProperties:
      ^:
        $ref: '#/definitions/pathItem'
      ^x-:
        $ref: '#/definitions/specificationExtension'
  example:
    type: object
    description: ""
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      summary:
        type: string
      description:
        type: string
      value:
        $ref: '#/definitions/any'
      externalValue:
        type: string
  link:
    type: object
    description: The `Link object` represents a possible design-time link for a response.
      The presence of a link does not guarantee the caller's ability to successfully
      invoke it, rather it provides a known relationship and traversal mechanism between
      responses and other operations.  Unlike _dynamic_ links (i.e. links provided
      **in** the response payload), the OAS linking mechanism does not require link
      information in the runtime response.  For computing links, and providing instructions
      to execute them, a runtime expression is used for accessing values in an operation
      and using them as parameters while invoking the linked operation.
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      operationRef:
        type: string
      operationId:
        type: string
      parameters:
        $ref: '#/definitions/anysOrExpressions'
      requestBody:
        $ref: '#/definitions/anyOrExpression'
      description:
        type: string
      server:
        $ref: '#/definitions/server'
  header:
    type: object
    description: 'The Header Object follows the structure of the Parameter Object
      with the following changes:  1. `name` MUST NOT be specified, it is given in
      the corresponding `headers` map. 1. `in` MUST NOT be specified, it is implicitly
      in `header`. 1. All traits that are affected by the location MUST be applicable
      to a location of `header` (for example, `style`).'
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      description:
        type: string
      required:
        type: boolean
      deprecated:
        type: boolean
      allowEmptyValue:
        type: boolean
      style:
        type: string
      explode:
        type: boolean
      allowReserved:
        type: boolean
      schema:
        $ref: '#/definitions/schemaOrReference'
      example:
        $ref: '#/definitions/any'
      examples:
        $ref: '#/definitions/examplesOrReferences'
      content:
        $ref: '#/definitions/mediaTypes'
  tag:
    type: object
    description: Adds metadata to a single tag that is used by the Operation Object.
      It is not mandatory to have a Tag Object per tag defined in the Operation Object
      instances.
    required:
    - name
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      name:
        type: string
      description:
        type: string
      externalDocs:
        $ref: '#/definitions/externalDocs'
  examples:
    type: object
    description: ""
    additionalProperties: false
  reference:
    type: object
    description: A simple object to allow referencing other components in the specification,
      internally and externally.  The Reference Object is defined by JSON Reference
      and follows the same structure, behavior and rules.   For this specification,
      reference resolution is accomplished as defined by the JSON Reference specification
      and not by the JSON Schema specification.
    required:
    - $ref
    additionalProperties: false
    properties:
      $ref:
        type: string
  schema:
    type: object
    description: The Schema Object allows the definition of input and output data
      types. These types can be objects, but also primitives and arrays. This object
      is an extended subset of the JSON Schema Specification Wright Draft 00.  For
      more information about the properties, see JSON Schema Core and JSON Schema
      Validation. Unless stated otherwise, the property definitions follow the JSON
      Schema.
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      nullable:
        type: boolean
      discriminator:
        $ref: '#/definitions/discriminator'
      readOnly:
        type: boolean
      writeOnly:
        type: boolean
      xml:
        $ref: '#/definitions/xml'
      externalDocs:
        $ref: '#/definitions/externalDocs'
      example:
        $ref: '#/definitions/any'
      deprecated:
        type: boolean
      title:
        $ref: http://json-schema.org/draft-04/schema#/properties/title
      multipleOf:
        $ref: http://json-schema.org/draft-04/schema#/properties/multipleOf
      maximum:
        $ref: http://json-schema.org/draft-04/schema#/properties/maximum
      exclusiveMaximum:
        $ref: http://json-schema.org/draft-04/schema#/properties/exclusiveMaximum
      minimum:
        $ref: http://json-schema.org/draft-04/schema#/properties/minimum
      exclusiveMinimum:
        $ref: http://json-schema.org/draft-04/schema#/properties/exclusiveMinimum
      maxLength:
        $ref: http://json-schema.org/draft-04/schema#/properties/maxLength
      minLength:
        $ref: http://json-schema.org/draft-04/schema#/properties/minLength
      pattern:
        $ref: http://json-schema.org/draft-04/schema#/properties/pattern
      maxItems:
        $ref: http://json-schema.org/draft-04/schema#/properties/maxItems
      minItems:
        $ref: http://json-schema.org/draft-04/schema#/properties/minItems
      uniqueItems:
        $ref: http://json-schema.org/draft-04/schema#/properties/uniqueItems
      maxProperties:
        $ref: http://json-schema.org/draft-04/schema#/properties/maxProperties
      minProperties:
        $ref: http://json-schema.org/draft-04/schema#/properties/minProperties
      required:
        $ref: http://json-schema.org/draft-04/schema#/properties/required
      enum:
        $ref: http://json-schema.org/draft-04/schema#/properties/enum
      type:
        type: string
      allOf:
        type: array
        items:
          $ref: '#/definitions/schemaOrReference'
        minItems: 1
      oneOf:
        type: array
        items:
          $ref: '#/definitions/schemaOrReference'
        minItems: 1
      anyOf:
        type: array
        items:
          $ref: '#/definitions/schemaOrReference'
        minItems: 1
      not:
        $ref: '#/definitions/schema'
      items:
        anyOf:
        - $ref: '#/definitions/schemaOrReference'
        - type: array
          items:
            $ref: '#/definitions/schemaOrReference'
          minItems: 1
      properties:
        type: object
        additionalProperties:
          $ref: '#/definitions/schemaOrReference'
      additionalProperties:
        oneOf:
        - $ref: '#/definitions/schemaOrReference'
        - type: boolean
      default:
        $ref: '#/definitions/defaultType'
      description:
        type: string
      format:
        type: string
  discriminator:
    type: object
    description: When request bodies or response payloads may be one of a number of
      different schemas, a `discriminator` object can be used to aid in serialization,
      deserialization, and validation.  The discriminator is a specific object in
      a schema which is used to inform the consumer of the specification of an alternative
      schema based on the value associated with it.  When using the discriminator,
      _inline_ schemas will not be considered.
    required:
    - propertyName
    additionalProperties: false
    properties:
      propertyName:
        type: string
      mapping:
        $ref: '#/definitions/strings'
  xml:
    type: object
    description: A metadata object that allows for more fine-tuned XML model definitions.  When
      using arrays, XML element names are *not* inferred (for singular/plural forms)
      and the `name` property SHOULD be used to add that information. See examples
      for expected behavior.
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      name:
        type: string
      namespace:
        type: string
      prefix:
        type: string
      attribute:
        type: boolean
      wrapped:
        type: boolean
  securityScheme:
    type: object
    description: Defines a security scheme that can be used by the operations. Supported
      schemes are HTTP authentication, an API key (either as a header or as a query
      parameter), OAuth2's common flows (implicit, password, application and access
      code) as defined in RFC6749, and OpenID Connect Discovery.
    required:
    - type
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      type:
        type: string
      description:
        type: string
      name:
        type: string
      in:
        type: string
      scheme:
        type: string
      bearerFormat:
        type: string
      flows:
        $ref: '#/definitions/oauthFlows'
      openIdConnectUrl:
        type: string
  oauthFlows:
    type: object
    description: Allows configuration of the supported OAuth Flows.
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      implicit:
        $ref: '#/definitions/oauthFlow'
      password:
        $ref: '#/definitions/oauthFlow'
      clientCredentials:
        $ref: '#/definitions/oauthFlow'
      authorizationCode:
        $ref: '#/definitions/oauthFlow'
  oauthFlow:
    type: object
    description: Configuration details for a supported OAuth Flow
    additionalProperties: false
    patternProperties:
      ^x-:
        $ref: '#/definitions/specificationExtension'
    properties:
      authorizationUrl:
        type: string
      tokenUrl:
        type: string
      refreshUrl:
        type: string
      scopes:
        $ref: '#/definitions/strings'
  securityRequirement:
    type: object
    description: Lists the required security schemes to execute this operation. The
      name used for each property MUST correspond to a security scheme declared in
      the Security Schemes under the Components Object.  Security Requirement Objects
      that contain multiple schemes require that all schemes MUST be satisfied for
      a request to be authorized. This enables support for scenarios where multiple
      query parameters or HTTP headers are required to convey security information.  When
      a list of Security Requirement Objects is defined on the Open API object or
      Operation Object, only one of Security Requirement Objects in the list needs
      to be satisfied to authorize the request.
    additionalProperties: false
    patternProperties:
      ^[a-zA-Z0-9\.\-_]+$:
        type: array
        items:
          type: string
        uniqueItems: true
  anyOrExpression:
    oneOf:
    - $ref: '#/definitions/any'
    - $ref: '#/definitions/expression'
  callbackOrReference:
    oneOf:
    - $ref: '#/definitions/callback'
    - $ref: '#/definitions/reference'
  exampleOrReference:
    oneOf:
    - $ref: '#/definitions/example'
    - $ref: '#/definitions/reference'
  headerOrReference:
    oneOf:
    - $ref: '#/definitions/header'
    - $ref: '#/definitions/reference'
  linkOrReference:
    oneOf:
    - $ref: '#/definitions/link'
    - $ref: '#/definitions/reference'
  parameterOrReference:
    oneOf:
    - $ref: '#/definitions/parameter'
    - $ref: '#/definitions/reference'
  requestBodyOrReference:
    oneOf:
    - $ref: '#/definitions/requestBody'
    - $ref: '#/definitions/reference'
  responseOrReference:
    oneOf:
    - $ref: '#/definitions/response'
    - $ref: '#/definitions/reference'
  schemaOrReference:
    oneOf:
    - $ref: '#/definitions/schema'
    - $ref: '#/definitions/reference'
  securitySchemeOrReference:
    oneOf:
    - $ref: '#/definitions/securityScheme'
    - $ref: '#/definitions/reference'
  anysOrExpressions:
    type: object
    additionalProperties:
      $ref: '#/definitions/anyOrExpression'
  callbacksOrReferences:
    type: object
    additionalProperties:
      $ref: '#/definitions/callbackOrReference'
  encodings:
    type: object
    additionalProperties:
      $ref: '#/definitions/encoding'
  examplesOrReferences:
    type: object
    additionalProperties:
      $ref: '#/definitions/exampleOrReference'
  headers:
    type: object
    additionalProperties:
      $ref: '#/definitions/header'
  headersOrReferences:
    type: object
    additionalProperties:
      $ref: '#/definitions/headerOrReference'
  linksOrReferences:
    type: object
    additionalProperties:
      $ref: '#/definitions/linkOrReference'
  mediaTypes:
    type: object
    additionalProperties:
      $ref: '#/definitions/mediaType'
  parametersOrReferences:
    type: object
    additionalProperties:
      $ref: '#/definitions/parameterOrReference'
  requestBodiesOrReferences:
    type: object
    additionalProperties:
      $ref: '#/definitions/requestBodyOrReference'
  responsesOrReferences:
    type: object
    additionalProperties:
      $ref: '#/definitions/responseOrReference'
  schemasOrReferences:
    type: object
    additionalProperties:
      $ref: '#/definitions/schemaOrReference'
  securitySchemesOrReferences:
    type: object
    additionalProperties:
      $ref: '#/definitions/securitySchemeOrReference'
  serverVariables:
    type: object
    additionalProperties:
      $ref: '#/definitions/serverVariable'
  strings:
    type: object
    additionalProperties:
      type: string
  object:
    type: object
    additionalProperties: true
  any:
    additionalProperties: true
  expression:
    type: object
    additionalProperties: true
  specificationExtension:
    description: Any property starting with x- is valid.
    oneOf:
    - type: "null"
    - type: number
    - type: boolean
    - type: string
    - type: object
    - type: array
  defaultType:
    oneOf:
    - type: "null"
    - type: array
    - type: object
    - type: number
    - type: boolean
    - type: string

MikeRalphson

With the changes implied by these comments I was able to validate a converted v2 petstore definition. It is possible by making change X I have weakened the schema, thus missing problem Y, so I would appreciate your thoughts @webron on each individually.

MikeRalphson · 2017-07-14T08:21:12Z

schemas/v3.0/schema.yaml

+  openapi:
+    type: string
+    enum:
+      - 3.0.0


Replaced this with a regex pattern to allow testing of 3.0.0-rc2 compatible documents. This would keep schema churn to a minimum.

Yeah, this should actually change to a pattern that matches anything starting with 3.0 as according to semver, any patch level changes should not affect validation. That said, I'm embarrassed to say I've avoided learning regex as much as I can 😁

MikeRalphson · 2017-07-14T08:23:20Z

schemas/v3.0/schema.yaml

+        type: string
+      type:
+        type: string
+          enum:


Incorrect indentation of enum:. Yay, yaml FTW! :)

MikeRalphson · 2017-07-14T08:24:42Z

schemas/v3.0/schema.yaml

+
+  Responses:
+    allOf:
+      - $ref: '#/definitions/Extensions'    


Is 'Extensions' defined anywhere? Should the following be part of the allOf array?

That was from a previous life of the schema, and I just forgot to remove it. Will do.

MikeRalphson · 2017-07-14T08:36:11Z

schemas/v3.0/schema.yaml

+  Reference:
+    type: object
+    properties:
+      $ref:


Should $ref be a required property? Otherwise I get false matches of both halves of a oneOf.

Yes, will fix.

MikeRalphson · 2017-07-14T08:38:10Z

schemas/v3.0/schema.yaml

+        type: object
+        patternProperties:
+          '^[a-zA-Z0-9\.\-_]+$':
+            oneOf:


Both Schema and Reference include a $ref property and Reference allows additionalProperties. Either change to anyOf or disallow additionalProperties in Reference objects - which would be a change to the OAS? Multiple examples.

That's an excellent question. I've revisited the spec. I'll either make it anyOf or remove the $ref from the Schema definition and make sure it's always interchangeable with the Reference in the JSON Schema.

@MikeRalphson - not that I recall, but it seems that right now, there's no $ref property in Schema and it stayed oneOf wherever a Schema is called. I think that should be fine. Please let me know what you're thinking - if it's fine, I'll create a definition for SchemaOrReference and use that across the board instead of repeating the oneOf everywhere.

MikeRalphson · 2017-07-14T08:45:31Z

schemas/v3.0/schema.yaml

+    not:
+      type: object
+      patternProperties:
+        '^x-': {}


I think this requires an additionalProperties: false otherwise responses do match this sub-schema.

@webron @MikeRalphson why is this not: block here? Filtering out other stuff, you have

Responses: type: object patternProperties: '^x-': {} additionalProperties: false not: type: object patternProperties: '^x-': {} additionalProperties: false

which is an impossible schema. {"type": "object", "not": {"type": "object"}} alone makes it impossible. Any keywords that are the same inside and outside of a not by definition are impossible to satisfy.

Am I misreading something here?

MikeRalphson · 2017-07-14T09:13:09Z

schemas/v3.0/schema.yaml

+      '^x-': {}
+    additionalProperties: false  
+
+  ParameterWithSchemaWithExamples:


I seem to be having problems with these - as neither example or examples is required in ParameterWithSchemaWithExampleInQuery or ParameterWithSchemaWithExamplesInQuery and there is no ParameterWithSchemaWithoutExampleInQuery type, how is the correct type to match the oneOf to be determined?

I temporarily changed examples to be a required property in ParameterWithSchemaWithExamplesIn*.

MikeRalphson · 2017-07-14T09:18:57Z

schemas/v3.0/schema.yaml

+
+  Schema:
+    type: object
+    properties:


Is the Schema object missing the items property?

Yeah, will add.

MikeRalphson · 2017-07-14T09:25:26Z

schemas/v3.0/schema.yaml

+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      examples:


Similarly, I had to make examples a required property to make the oneOf detection work correctly.

Can you explain this one?

Sorry, I made this edit after another comment, but it appears earlier in the schema. I believe this is MediaTypeWithExample vs MediaTypeWithExamples. A media-type object with neither example or examples properties matches both definitions. Suggest making examples a required property of MediaTypeWithExamples.

@MikeRalphson

You can also make things mutually exclusive by forbidding the other property rather than requiring the property that you have:

oneOf: - properties: example: properties: ... examples: not: {} - properties: example: not: {} examples: patternProperties: ...

MikeRalphson · 2017-07-14T09:27:31Z

schemas/v3.0/schema.yaml

+      attribute:
+        type: boolean
+        default: false
+      wrapperd:


Typo wrapperd for wrapped.

MikeRalphson · 2017-07-14T12:58:26Z

schemas/v3.0/schema.yaml

+         - number
+         - object
+         - string
+      not:


Are we also missing definitions for the allOf, oneOf and anyOf arrays?

Yes, added.

MikeRalphson · 2017-07-14T13:03:03Z

schemas/v3.0/schema.yaml

+      default: {}
+      $ref:
+        type: string
+        format: uri-ref


Is this uriref in Draft 05? Multiple occurences.

Yes, that's a miss on my part. I actually looked it up before, and went with the wrong one 😕

MikeRalphson · 2017-07-14T13:14:11Z

schemas/v3.0/schema.yaml

+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      examples:
+        type: array


Is this correct, or is it now a Map as elsewhere?

This requires a complete rework.

MikeRalphson · 2017-07-14T13:22:57Z

schemas/v3.0/schema.yaml

+      description:
+        type: string
+      value:
+        type: string


Example.value should be an empty schema?

Yup, will fix.

MikeRalphson · 2017-07-14T14:44:42Z

@webron with the changes implied by the above comments, I've now successfully validated 574 converted OpenAPI v2 definitions - with only one minor bug found in my converter (thank you).

Does

JSON Schema decorations

include descriptions ? It would be great to port those across to aid readability. Also required in future iteration: readme.

MikeRalphson · 2017-07-15T08:02:06Z

schemas/v3.0/schema.yaml

+        type: string
+      namespace:
+        type: string
+        format: url


Should this format be uri-ref / uriref not url ?

No. We changed the namespace definition to be an absolute URI.

Hi @webron, as far as I can tell, url isn't a format that's in the official specification. It sounds like you're implying here that it's like a uri, but required to be absolute?

uri is the correct format for an absolute URI.
uriref (which became uri-reference in the next draft so that is really preferred) is for relative URI references.

It would be really great to avoid url as having uri and url is horribly confusing, particularly as RFC 3986 goes out of its way to explain that there is no hard line between url and urn (e.g. you cannot make the distinction based on the scheme)

@webron @MikeRalphson I'm planning to change this to uri-reference, even if we are saying that this schema is a draft-wright-*-00 (a.k.a. "draft-05") schema, and that draft used uriref. I'm doing this because:

Literally no one has ever implemented a validator for draft-wright-*-00. Every implementation that I'm aware of skipped from draft-04 (draft-zyp-json-schema-04 + draft-fge-json-schema-validation-00) to draft-06 (draft-wright-*-01).

There is no official meta-schema for draft-05, and there never will be, so there is no programmatic way to inform validators that you are using draft-05

Format is extensible, so using uri-reference as a format is entirely valid even in draft-05

Any objections?

Ideally we could also publish a draft-06 version where uri-reference would be recognized, but format validation in general is such a hazy weird optional thing that, really, no one should rely on it unless they are using a specific validator and know it's exact behavior. e.g. some validators try to use a complex regex to validate the email format, but at least one popular validator just checks to see if there's an "@" character in it somewhere and doesn't bother with anything else.

webron · 2017-07-18T00:21:52Z

@MikeRalphson No, I wasn't referring to adding the descriptions as part of the decorations. While important, those are nice to have, and I don't necessarily have the capacity to add those right now all around the schema. If we decide to merge this schema (with it's JSON representation, of course), it'd be great if people helped contributing descriptions.

Right now I'm more focused on the functionality.

webron · 2017-07-18T00:32:54Z

@MikeRalphson Updated with your comments a possible a few additional things I've found. Would appreciate a second look.

tfesenko · 2017-07-18T01:52:21Z

schemas/v3.0/schema.yaml

+            - $ref: '#/definitions/Schema'
+            - $ref: '#/definitions/Reference'
+      items:
+        type: array


Wondering why array's item type is array and not an object(schema or reference). From the OAS3 spec:

items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. <...>

That's me being too tired. Good catch, will fix shortly.

MikeRalphson · 2017-07-18T08:45:05Z

schemas/v3.0/schema.yaml

+    type: object
+    required:
+      - type
+      - openIdConnect


Think this should be openIdConnectUrl.

MikeRalphson · 2017-07-18T08:50:13Z

schemas/v3.0/schema.yaml

+    properties:
+      url:
+        type: string
+        format: uriref


I think this should be a uri-template format, but this doesn't exist in JSON schema Draft 5. If we replace format with pattern a suitable regex seems to be (lifted from ajv which quotes https://tools.ietf.org/html/rfc6570)

/^(?:(?:[^\x00-\x20"'<>%\\^`{|}]|%[0-9a-f]{2})|\{[+#.\/;?&=,!@|]?(?:[a-z0-9_]|%[0-9a-f]{2})+(?:\:[1-9][0-9]{0,3}|\*)?(?:,(?:[a-z0-9_]|%[0-9a-f]{2})+(?:\:[1-9][0-9]{0,3}|\*)?)*\})*$/i

I'd rather not get into that. I'm not sure what the difference is between uriref and uri-template. If it's too permissive, in this case, I'm ok with it. If it's too constrict, we can drop the format altogether.

I find adding complex regex impossible to read and maintain. We could have added a regex to define media types as well and we didn't (we had a similar discussion about it around 2.0's schema).

Understood. I'm seeing that it's too restrictive being a uriref, not allowing {} characters. Dropping the format seems the best option.

Makes sense, will remove.

MikeRalphson · 2017-07-18T09:09:09Z

schemas/v3.0/schema.yaml

+      $ref: '#/definitions/PathItem'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false


The additionalProperties: false should be removed, as it overrides the other additionalProperties property when converted to JSON. This is the only such occurrence.

webron · 2017-07-18T17:29:37Z

@MikeRalphson thanks for the review - any other comments or thoughts?

tfesenko · 2017-07-18T17:50:19Z

schemas/v3.0/schema.yaml

+      callbacks:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/Callback'


Should not it be Callback or Reference:

callbacks | Map[string, Callback Object | Reference Object]

MikeRalphson · 2017-07-18T18:00:14Z

@webron I'm seeing a rate of about 0.35% errors over 35,000 converted 'valid' OpenAPI 2.0 documents. All the failures appear to be correctly identified - i.e. things which have changed in the spec that the converter can't process automatically or that the 2.0 validators missed. This schema certainly validates more of the spec than the @timburks / #1236 schema, but I do think you may have made a rod for your own back by multiplying out the combinations of (for example) parameters in X with/without Y with/without a Z.

What I'm trying to say is that maintenance of this schema is going to be somewhat harder going forward (depending on what changes come along in 3.1 and subsequent minor versions) as it has more redundancy and a slightly different mental model to grok rather than modelling only those objects that the spec defines. When (if?) we have a test-suite and a reference parser/validator, some of these issues go away.

The schema seems to be performant even on large documents, though the use of oneOf means more verbose error messages, at least from the schema validator I'm using.

That said... add the id and schema properties and

webron · 2017-07-18T22:46:48Z

@MikeRalphson Thanks for the feedback.

Trust me, I don't like the breakdown as it is now, and I agree it's harder to maintain. The issue is derived from the way JSON Schema combines allOf with additionalProperties: false. If I had a solution to that, it'd make things much much easier. I only need one example of making it work and I can convert the rest.

MikeRalphson · 2017-07-21T11:09:52Z

schemas/v3.0/schema.yaml

+      - default
+    properties:
+      enum:
+        type: string


serverVariables.enum should be an array of string. @webron

Thanks, should be fixed now.

hkosova · 2017-08-02T13:32:05Z

@webron In this schema, ParameterWithContentNotInPath object seems to be missing the allowReserved property. Is this a bug or by design (e.g. allowReserved is incompatible with content)?

webron · 2017-08-03T22:05:29Z

@hkosova it's by design. A parameter can have either content or a schema, and style, explode and so on are only applicable with schema.

hkosova · 2017-08-08T14:55:07Z

@webron openIdConnectUrl has format: url - shouldn't it be uriref (relative URL allowed) like tokenUrl etc?

MikeRalphson · 2019-03-22T16:41:19Z

Thanks for clarifying @handrews - I obviously misremembered the situation.

Reduce duplications and complexity in v3.0 JSON Schema

Added `id`, `$schema`, `description`

webron · 2019-04-02T19:55:59Z

@MikeRalphson, @handrews - I've updated the schema with the missing metadata (id, $schema, description). Can you please run final validation and tests on it?

If you give the thumbs up, and we get an official @OAI/tsc vote, I'll add a conversion of the schema to JSON, and merge it (at last).

handrews

Newly added metadata looks good, @webron

philsturgeon · 2019-04-02T22:17:45Z

🚢 🚢 🚢 🚢 🚢 🚢 🚢 🚢

permalink: https://github.com/OAI/OpenAPI-Specification/blob/92e15eba1d4591ebfe8c11898c48241e72854381/schemas/v3.0/schema.yaml

@webron

* adopt @webron's OpenAPI 3.0 schema from OAI/OpenAPI-Specification#1270 permalink: https://github.com/OAI/OpenAPI-Specification/blob/92e15eba1d4591ebfe8c11898c48241e72854381/schemas/v3.0/schema.yaml * use literal `$ref` key in Reference Object schema * `"$ref"` -> `$ref`

MikeRalphson

LGTM. No regressions found.

permalink: https://github.com/OAI/OpenAPI-Specification/blob/92e15eba1d4591ebfe8c11898c48241e72854381/schemas/v3.0/schema.yaml

webron · 2019-04-18T14:42:11Z

Added the converted JSON file and a README with some relevant details.

Thanks everyone for making it happen.

philsturgeon · 2019-04-18T14:49:46Z

Great work everyone, this is awesome.

cebe · 2019-04-18T16:32:54Z

this has been merged into OpenAPI.next, what is the process or what are the plans of getting it into master?

webron · 2019-04-18T20:12:51Z

@cebe sigh just shows how old this PR was. I'll move the content to master as well. Thanks for catching it.

@webron

* adopt @webron's OpenAPI 3.0 schema from OAI/OpenAPI-Specification#1270 permalink: https://github.com/OAI/OpenAPI-Specification/blob/92e15eba1d4591ebfe8c11898c48241e72854381/schemas/v3.0/schema.yaml * add ajv-errors * address error messages for #1808's Swagger 2.0 example clarifies the schema and adds custom error messages for unclear error conditions * address error messages for #1808's OpenAPI 3.0 example * restrict underlying JSON Schema `type` field to simple types only (for #1832) * fix limitation in JSON Pointer conversion helper * add clear `not` error message (for #1489) * add additionalProperties message (for #1394) * add ajv-keywords * use `switch` to intelligently identify inline vs referenced content (for #1853) * use `switch` to XOR `schema` and `content` (for #1853) * use `switch` to pivot security scheme based on type (for #1672) * use switch to fall-through to inline security scheme validation (for #1672) * rewrite more Reference oneOfs (for #1519) * add custom message for `Schema.required` type error (for #1519) * rewrite Response/Reference oneOf (for #1489) * use switch in ParameterLocation validation (for #1797) * define pivot key switches for SecurityDefinitions (for #1711) * give helpful `format: uri` messages for SecurityDefinitions (for #1711) * eliminate NonBodyParameter; pivot on `Parameter.in` with a switch (for #1511) * oneOf -> switch for Parameters.items reference * (for #1711) * remove redundant semantic validator (for #1511) * adjust wording of custom error message (for #1853) * add regression tests for all related issues * revert to expect@^1.20.2 * linter fixes * fix messaging flaw for #1832 * improve messaging for #1394 * use literal key for `$ref` in Reference Object * remove commented legacy data from OAS3 schema * remove superfluous quotation marks * normalize test case paths to `/` * normalize openapi fields to 3.0.0 * drop unused `paths` information * ensure clear errors for 3.0 Parameter style/content exclusivity * add `required` assertions to switch statements that pivot on a key's value this prevents false positives when the pivot key is missing entirely * remove stray space

cebe · 2019-04-19T07:41:26Z

hehe, I thought this was part of your workflow :)

@webron

…ger-api#1984) * adopt @webron's OpenAPI 3.0 schema from OAI/OpenAPI-Specification#1270 permalink: https://github.com/OAI/OpenAPI-Specification/blob/92e15eba1d4591ebfe8c11898c48241e72854381/schemas/v3.0/schema.yaml * use literal `$ref` key in Reference Object schema * `"$ref"` -> `$ref`

@webron

…i#1985) * adopt @webron's OpenAPI 3.0 schema from OAI/OpenAPI-Specification#1270 permalink: https://github.com/OAI/OpenAPI-Specification/blob/92e15eba1d4591ebfe8c11898c48241e72854381/schemas/v3.0/schema.yaml * add ajv-errors * address error messages for swagger-api#1808's Swagger 2.0 example clarifies the schema and adds custom error messages for unclear error conditions * address error messages for swagger-api#1808's OpenAPI 3.0 example * restrict underlying JSON Schema `type` field to simple types only (for swagger-api#1832) * fix limitation in JSON Pointer conversion helper * add clear `not` error message (for swagger-api#1489) * add additionalProperties message (for swagger-api#1394) * add ajv-keywords * use `switch` to intelligently identify inline vs referenced content (for swagger-api#1853) * use `switch` to XOR `schema` and `content` (for swagger-api#1853) * use `switch` to pivot security scheme based on type (for swagger-api#1672) * use switch to fall-through to inline security scheme validation (for swagger-api#1672) * rewrite more Reference oneOfs (for swagger-api#1519) * add custom message for `Schema.required` type error (for swagger-api#1519) * rewrite Response/Reference oneOf (for swagger-api#1489) * use switch in ParameterLocation validation (for swagger-api#1797) * define pivot key switches for SecurityDefinitions (for swagger-api#1711) * give helpful `format: uri` messages for SecurityDefinitions (for swagger-api#1711) * eliminate NonBodyParameter; pivot on `Parameter.in` with a switch (for swagger-api#1511) * oneOf -> switch for Parameters.items reference * (for swagger-api#1711) * remove redundant semantic validator (for swagger-api#1511) * adjust wording of custom error message (for swagger-api#1853) * add regression tests for all related issues * revert to expect@^1.20.2 * linter fixes * fix messaging flaw for swagger-api#1832 * improve messaging for swagger-api#1394 * use literal key for `$ref` in Reference Object * remove commented legacy data from OAS3 schema * remove superfluous quotation marks * normalize test case paths to `/` * normalize openapi fields to 3.0.0 * drop unused `paths` information * ensure clear errors for 3.0 Parameter style/content exclusivity * add `required` assertions to switch statements that pivot on a key's value this prevents false positives when the pivot key is missing entirely * remove stray space

Initial schema commit

45971df

MikeRalphson suggested changes Jul 14, 2017

View reviewed changes

MikeRalphson reviewed Jul 14, 2017

View reviewed changes

MikeRalphson reviewed Jul 15, 2017

View reviewed changes

so many fixes

bda4218

tfesenko reviewed Jul 18, 2017

View reviewed changes

items array -> object

1eb22f0

MikeRalphson suggested changes Jul 18, 2017

View reviewed changes

webron added 2 commits July 18, 2017 08:13

A couple more fixes

bd277c6

Fixed restriction on Server's url

069367f

tfesenko reviewed Jul 18, 2017

View reviewed changes

make callbacks great again!

629cd7c

MikeRalphson reviewed Jul 21, 2017

View reviewed changes

fixed servervariable.enum

49e784d

darrelmiller mentioned this pull request Jul 27, 2017

Official 3.0 schema? #1301

Closed

shockey mentioned this pull request Aug 2, 2017

Update oas3-schema.js swagger-api/swagger-editor#1449

Merged

webron and others added 2 commits March 26, 2019 12:40

Merge pull request #1800 from vearutop/oas3-schema

c094c22

Reduce duplications and complexity in v3.0 JSON Schema

Add schema metadata

92e15eb

Added `id`, `$schema`, `description`

webron requested review from MikeRalphson and darrelmiller April 2, 2019 19:53

handrews approved these changes Apr 2, 2019

View reviewed changes

MikeRalphson approved these changes Apr 17, 2019

View reviewed changes

webron and others added 3 commits April 18, 2019 17:34

JSON version of the schema

6d17b63

Added README with basic information

3dcfee1

Update README.md

35ab014

webron merged commit ce93fe4 into OpenAPI.next Apr 18, 2019

webron mentioned this pull request Apr 18, 2019

OAS3 Schema to master #1897

Merged

cebe mentioned this pull request Apr 19, 2019

implement cli tool for validating against OpenAPI schema v3 cebe/php-openapi#20

Merged

MikeRalphson mentioned this pull request Apr 30, 2019

actions: reinstate validation of schemas and examples, fixes #1739 #1911

Closed

Relequestual mentioned this pull request Jun 13, 2019

Proposal: x-oas-draft-alternativeSchemas #1532

Closed

MikeRalphson mentioned this pull request Jun 13, 2019

Add field descriptions to JSON schema #1948

Closed

webron deleted the oas3-schema branch April 23, 2020 16:08

[WIP] Alternative OAS3 JSON Schema #1270

[WIP] Alternative OAS3 JSON Schema #1270

Conversation

webron commented Jul 14, 2017

fehguy commented Jul 14, 2017

timburks commented Jul 14, 2017

MikeRalphson left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MikeRalphson Jul 14, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MikeRalphson Jul 14, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MikeRalphson commented Jul 14, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

handrews Nov 8, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webron commented Jul 18, 2017

webron commented Jul 18, 2017

tfesenko Jul 18, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webron commented Jul 18, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MikeRalphson commented Jul 18, 2017

webron commented Jul 18, 2017

MikeRalphson Jul 21, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hkosova commented Aug 2, 2017

webron commented Aug 3, 2017

hkosova commented Aug 8, 2017

MikeRalphson commented Mar 22, 2019

webron commented Apr 2, 2019

handrews left a comment

Choose a reason for hiding this comment

philsturgeon commented Apr 2, 2019

MikeRalphson left a comment

Choose a reason for hiding this comment

webron commented Apr 18, 2019

philsturgeon commented Apr 18, 2019

MikeRalphson left a comment •

edited

Loading

MikeRalphson Jul 14, 2017 •

edited

Loading

MikeRalphson Jul 14, 2017 •

edited

Loading

MikeRalphson commented Jul 14, 2017 •

edited

Loading

handrews Nov 8, 2018 •

edited

Loading

tfesenko Jul 18, 2017 •

edited

Loading

MikeRalphson Jul 21, 2017 •

edited

Loading