According to spec swagger inside schema object support only limited subset of JSON Schema draft4 and extend it with custom keywords.

This isssue was hidden, before 68c6777dc5eba98dc1eb791983693f089e9d3366 commit any swagger model with arbitrary JSON schema was valid(against Swagger schema).

These create a problem, because in reality most of tools use standard JSON schema validators(for e.g. swagger-tools use z-schema, swagger-express-middleware use tv4). And I didn't found any true Swagger 2.0 validator in the wild.

Another problem is that you can't reference existing schemes inside your swagger files. It became real problem, if you want to use some standard scheme or simply reuse your existing validation scheme. For example if you make API that return swagger definitions and want to reuse existing schema, you can't simply use '$ref' or even copy-paste it.

Finally it brake compatibility with all tooling around JSON Schema not only validators but also documentation generators, UI form generators, etc.

On technical side, this is list of Draft4 keywords doesn't supported by Swagger: id, $schema, additionalItems, definitions, patternProperties, dependencies, anyOf, oneOf, not.

Also there are "discriminator" and "readOnly" Swagger specific keywords that don't supported by JSON Schema validators. "discriminator" could be safely substitute with "oneOf" construction, as for "readOnly" same behaviour could be achieved by using "allOf" with "write part" and "read-only part". My proposal it either to remove these keywords or make them optional to support.

Also there are "safe" custom keywords namely "example" and "externalDocs", they shouldn't cause any serious trouble, but should be submitted as requests for Draft5 to ensure future compatibility.

Last keyword is "xml", I didn't make any research about it, so I can't say if it used in any Swagger related project or if it brake JSON schema compatibility.

A long standing request has been to add support for alternate schemas. See #764 #1443

There are many concerns about the effect this will have on the tooling ecosystem, however, there is also a strong desire from the community to support both more recent versions of JSON Schema and other formats such as XSD Schema, Protobuf Schema.

Instead of simply adding this feature to the specification and hoping that tooling vendors will implement it. I propose we use the draft feature (PR #1531 ) process to validate the value and feasibility of this feature.

openapi: 3.0.2
info:
  title: A sample using real JSON Schema and xsd
  version: 1.0.0
paths:
  /:
    get:
      responses:
        '200':
          description: Ok
          content:
            application/json:
              x-oas-draft-alternate-schema:
                type: json-schema
                externalValue: ./rootschema.json
            application/xml:
              x-oas-draft-alternate-schema:
                type: xml-schema
                externalValue: ./rootschema.xsd

• The property is called alternate-schema because it can be used in instead of, or in addition to the OAS Schema object. If both are present then both schemas must be respected.
• The type field is required and must match one of the values identified in an alternate schema registry which will be created as part of this proposal. The alternate schema registry will provide a link to a specification for the schema file.
• It is recommended that tools provide users with warnings when they encounter an alternate schema type that they do not support. Tools should not fail to process a description, unless the schema is essential to the operation. Ideally they should continue as if the alternate-schema is not present in a form of graceful degradation.
• The externalValue property is required and must be a relative or absolute URL.
• The alternate-schema property can be used anywhere the schema property can be used.

Per https://github.com/swagger-api/swagger-core/issues/459 there are cases where passing null is important. For example:

[ null ]

will be quite different than []. See if this can be an option

I guess this is a 2.0+ request as 2.0 is already "released".

Basically, there is currently no way to express a single path which may have different request/response formats based on additional criteria, namely headers. two possible scenarios:

1. An API which supports both xml and json, but the models for each format are different enough that they cannot be expressed via a single json schema w/ xml annotations (even if the xml format is expressible using the xml annotations).
2. An API which supports versioning the representation via the media-type. e.g. application/my+v1 returns a json model which is sufficiently different from the application/my+v2 model such that i cannot describe them both using one unified model.

If supporting different responses for arbitrary headers is too big of a change, just supporting multiple media-types (for request and response) would be sufficient for the cases described here.

Hi everyone.

I feel that the ignoring of extra properties when using JSON References goes against the goal of reusability.

Take this example from a fictional Swagger contract:

{
    addresses: [
        "homeAddress": {
            "description": "The premises at which electricity is provided.",
            "$ref": "#/definitions/Address"
        },
        "invoiceAddress": {
            "description": "The billing address - must be where the customer's credit card is registered.",
            "$ref": "#/definitions/Address"
        }
    ]
}

The "description" properties help to distinguish between the two uses of the "Address" Reference. Of course you could argue that better naming of the "homeAddress" and "invoiceAddress" properties could achieve this, but we are not always in control of property names in our data models and sometimes you need a more verbose description.

The Swagger editor (http://editor.swagger.io/#/) is an example of an application that could be improved by removing this limitation.

Is this something that has been raised previously? Please see here for a discussion on the Swagger Google Group: https://groups.google.com/forum/#!topic/swagger-swaggersocket/ewgimdO2cOI

Example

  responses:
    200:
      description: An array of events
      schema:
        type: array
        items:
          $ref: '#/definitions/Event'
    200:
      description: |
        An array of flattened events. This is the response
        object when singleEvents is True.
      schema:
        type: array
        items:
          $ref: '#/definitions/EventFlat'
    default:
      description: Unexpected error
      schema:
        $ref: '#/definitions/Error'

TLDR

(added after some discussion)

• "interfaces" (like path items, just without path parameters, and not linked to a path template)
• a path item can refer to an interface (which is implemented), possibly adding path parameters to it
• a string property (containing an URI) in a schema can refer to an interface (which means the consumer can know which operations can be used on this URI)

Background / Current Situation

I work at a company where our Restful API Guidelines prescribe both "document your API using OpenAPI" and "Use HATEOAS" ("Hypertext as the Engine of Application State", one of the core principles of REST).

Unfortunately both do not work together nicely:

• Swagger/OpenAPI 2.0's model is "we have paths which can be distinguished in some way, and describe the operations on those paths" (including their data format).
• The HATEOAS model is "The client gets a result which might contain links to other resources, and can decide to follow them, no matter which URI format they have".

Currently the intersection between both is "have links in your result, but just to URIs which are also described as paths in your Swagger definition, and describe in descriptions what kind of URIs you can expect".

Ideas

A core point of HATEOAS are media types and link relations. An API definition should mainly be a description of the media types and what operations they imply for links included in them. (Paraphrased from a blogpost of Roy Fielding.)

Media type definitions are analogous to what OpenAPI's definitions are currently, might even be an extension of that. For models with a property of type string, format uri we can then additionally refer to the URI class of that URI.

A URI class is defined analogously to the current path definitions, but with some name to be used in model definitions. The URI class defines what operations are possible on an URI, which parameters are allowed/needed (no path parameters, I guess), and what can be expected in return. (The URI class is not a property of the URI itself, but of its usage in a specific place. The same URI could appear with multiple URI classes.)

I'm not yet sure how link relations can come into this – I guess we might need a way to define the URI class depending on link relation or similar.

A client needs just some initial "bookmark URI" (so a single path definition might be fine), and then can take a link (with a given URI class) and use the operation behind the URI class to do what it wants to do. The format of the second URI doesn't matter anymore to the client – it can even have a different domain name than the bookmark one. But still everything can be strongly typed if wanted.

It looks like we don't yet have a JSON Schema to describe the OpenAPI 3.0 spec. The schemas folder has 1.2 and 2.0 subfolders, but nothing for 3.0 yet.

We'd like to contribute to this. Is anyone working on a JSON Schema for the 3.0 spec yet?

Fixes #333 Fixes #397 Fixes #470 Fixes #1026 Fixes #1238 Fixes #1313 Fixes #1368 Fixes #1389 Fixes #1494 Fixes #1523 Fixes #1666 Fixes #1719 Fixes #1766 Fixes #1869 Fixes #1985

Checklist items from #1766 so we can close.

• [x] @handrews "We should probably make sure none of the formats added in the newer draft conflict with the ones OpenAPI defines."
• [x] @handrews "At most you might want to check if we have any slight incompatibilities for readOnly and writeOnly which were moved/added to the validation spec in [Draft 07]"

Picking up from where https://github.com/OAI/OpenAPI-Specification/pull/1766 left off, this PR is helping OpenAPI v3.1 make a non-breaking change, to catch up with JSON Schema's latest draft.

Instead of OpenAPI continuing to confuse everyone by being a JSON Schema draft 05 sub-set, and a super-set, with some notable differences to watch out for, it will now be a JSON Schema draft 2019-09 superset. More info on that here.

The goal here is to help people write pure JSON Schema for their data model if they want to, or write OpenAPI-flavoured JSON Schema if they want to, but we are closing the gaps on what these two things mean. The list of differences is now tiny, only 4 extra keywords, with 2 notes about how exlusiveMinimum and exclusiveMaximum can be used in two ways (in order to maintain BC with OpenAPI v3.0).

Alternative Solutions

Alternative Schemas are a big topic which needs more work to be done. We should address the JSON Schema divergence issue to make the v3.x branch a happy place to be, and follow up with Alternative Schemas for v3.2 or v4.0, so our XML using friends can play with XML Schema, and all the other good things.

Risks

There are concerns that tooling vendors who work with static languages will have a hard time adding some of JSON Schemas newer more dynamic features. I understand this in theory, but most of JSON Schema's new features like if/then/else, and the old "type can be an array" issue, are just sugar for allOf/anyOf/oneOf, as can be seen in wework/json-schema-to-openapi-schema.

Seeing as allOf, anyOf, oneOf already exist in OpenAPI v3.0, whatever tooling vendors are doing to support that, should be done to support these keywords. Other new things like const are just an enum of 1.

Nothing should be that scary, yet people seem scared, but I think we can overcome in. We need to. JSON is a dynamic format, a property can contain a string one minute, and an object another, and this is pretty common practice for those using evolution. You might start out with a simple string, then decide you need more information and offer an object, deprecating the old way of doing things, and folks move over to use the object. This was an issue for reading JSON in Go for a while, then better JSON tooling came out and its not an issue.

OpenAPI tooling should be able to deal with this too. For example, ReDoc is an awesome open-source documentation generator, and it has no trouble at all with showing oneOf:

The argument I keep hearing is "tooling vendors are complaining about anyOf, allOf, oneOf, because it's hard, so lets not add any more keywords... Meh? Which is the priority here, making lives slightly easier for the tooling vendors by not adding new features, or making lives substantially less confusing for all the users of all the OpenAPI tools by letting them not have to unpack the differences between OpenAPI and JSON Schema? I lose 10% of every day helping people navigate this mess on APIs You Won't Hate, and I'm a tooling vendor at Stoplight.io. I'd rather have a few more complex keywords to figure out for the tooling, than have all the users of that tooling be constantly confused about which keywords they can use when, and how to convert from one to the other because different tools need OpenAPI or JSON Schema.

Anyhow, the tools that support advanced features will end up being more popular than the tools which do not. 🤷‍♂️

Life for tooling vendors trying to add these new keywords can be simplified in a few ways:

• Provide guidance in the form of blog posts (I got this)
• Common tooling (Stoplight got this for JS)
• JSON Schema tools can now be used directly, instead of building OpenAPI-based tooling which is similar then tweaking it... 🤦‍♂

I'd like to dig into this fear of adopting actual JSON Schema further on the OpenAPI slack, so please swing by and throw examples at me. I have heard vague concerns about patternProperties, but would love to sink my teeth into concrete examples.

Matrix type parameters are not fully supported by Swagger. Would be great to have them supported. See following google groups discussion on this topic with concrete example and a bunch of links about what matrix parameters are: https://groups.google.com/forum/#!topic/swagger-swaggersocket/lnQOLOLh3MI

Thanks for great product! Greetings from Ireland

hi.

Would like to be able present a type of Either[Dog,Cat] (or in clojure (either Dog, Cat, Moose) in the Spec. Quite common construct in the FP land. Would be like a enum, but with values of any type.

Currently such a thing could be presented as a complex type with optional fields for all the value => at least the swagger-ui would be able to generate sample models (with all possible alternatives in place) for it. Not perfect, but ~works. Requires also special coercion in the server side to map back into Either.

http://www.scala-lang.org/api/2.11.0/index.html#scala.util.Either

https://github.com/Prismatic/schema/blob/master/test/cljx/schema/core_test.cljx#L194-L203

NOTE: This meeting is on Thursday at 9am - 10am PT

Zoom Meeting link: https://zoom.us/j/975841675. Dial-in passcode: 763054 - Code-of-Conduct

In order to give some more visibility into the topics we cover in the TDC meetings here is the planned agenda for the next meeting. Hopefully this will allow people to plan to attend meetings for topics that they have an interest in. And for folks who cannot attend they can comment on this issue prior to the meeting. Feel free to suggest other potential agenda topics.

Please submit comments below for topics or proposals that you wish to present in the TDC meeting

The agenda backlog is currently maintained in issue #2482

| Topic | Owner | Decision/NextStep | |-------|---------|---------|
| | | | Reports from Special Interest Groups | TDC | | AOB (see below) | TDC | | New issues / PRs labelled review | @OAI/triage | | New issues without response yet | @OAI/triage | |

/cc @OAI/tsc Please suggest items for inclusion

I have after almost a decade with JSON, decided to use CBOR as the foundation for new designs (except for browser-based applications where the JavaScript/JSON combo still makes sense).

The rationale is here: https://github.com/cyberphone/cbor-everywhere

In order to encourage the creation and registration of extensions in a central registry, this PR proposes creating a new namespace registry for extensions so that OpenAPI users can reserve an extension prefix for their organization to ensure uniqueness.

One shortcoming of the type and format options relates to dates and times. Currently, I need to specify type: string and a format of either date, datetime, or time. That's great that we can specify those values, but there is nothing that allows me to specify to my API users what date or time format we use. Is it a unix timestamp, or ISO 8601, or MySQL format, or....? Are timestamps included? Do we cut off times at the minute, second, millisecond?

Every modern language has a whole library for dealing with the complexities of this because it's not trivial. But, in OpenAPI, all I can do is say it's a date, and it's up to you to figure out how it's formatted. I can provide an example, but that doesn't help much with validation and tooling. My best option is to stick a pattern in there, repeat it for every date in my app, and hope users recognize the regex as "Oh, that's ISO 8601."

I'd propose that date, datetime and time be promoted from formats to types in their own right, such that format becomes viable. Common formats can be provided for in the same way that formats for things like email and uuid are today, and for anything not covered by one of those constants, a format string similar to what language libraries use could be employed. This could then be supported by tooling for more flexible validation.

Examples:

type: datetime
format: iso8601

type: datetime
format: "H:i:s A F j, Y"

I have the following use case I'd like to solve:

type: object
description: Settings for a country
allOf:
   - type: object
      properties:
        country_code:
            type: string
            description: ISO 3166 country code
            enum: AD, AE, AF, AG .... ZW
        common_field:
            type: string
            description: Something all countries have
discriminator:
   description: Adds extra fields we need depending on country 
   propertyName: country_code
   mapping: 
       CA: #/CountryCA
       MX: #/CountryMX
       US: #/CountryGeneric
       DE: #/CountryGeneric
       ES: #/CountryGeneric
       # insert many more country definitions here that go to CountryGeneric

This can be made to work, but I would have to have all 200+ countries in the mapping object, each pointing to a reference of an object, and this is really cumbersome. I'd really love to be able to do this, treating the discriminator almost like a switch statement:

discriminator:
   description: Adds extra fields we need depending on country 
   propertyName: country_code
   mapping: 
       CA: #/CountryCA
       MX: #/CountryMX
   default: #/CountryGeneric

NOTE: This meeting is on Thursday at 9am - 10am PT

Zoom Meeting link: https://zoom.us/j/975841675. Dial-in passcode: 763054 - Code-of-Conduct

In order to give some more visibility into the topics we cover in the TDC meetings here is the planned agenda for the next meeting. Hopefully this will allow people to plan to attend meetings for topics that they have an interest in. And for folks who cannot attend they can comment on this issue prior to the meeting. Feel free to suggest other potential agenda topics.

Please submit comments below for topics or proposals that you wish to present in the TDC meeting

The agenda backlog is currently maintained in issue #2482

| Topic | Owner | Decision/NextStep | |-------|---------|---------|
| | | | Reports from Special Interest Groups | TDC | | AOB (see below) | TDC | | New issues / PRs labelled review | @OAI/triage | | New issues without response yet | @OAI/triage | |

/cc @OAI/tsc Please suggest items for inclusion