Make schema object compatible with JSON Schema draft4

[IvanGoncharov]

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 68c6777 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.

[davesag]

Hi @IvanGoncharov Looks like we've been having similar issues. I'm having trouble getting documents that lack properties that are not actually required to be correctly validated. The Ruby JSON::Validator.validate_fully method takes a schema and a document and validates that the document conforms to the schema. That worked when we were using additionalProperties to define optional properties (until we realised that that's not what additionalProperties is for.) Also the Swagger Codegen ignores any property defined under additionalProperties which is either just a current limitation or a bug. see http://stackoverflow.com/questions/29714534/swagger-json-optional-fields-being-treated-as-required

[webron]

The existing JSON Schema validators out there should have no problem validating Swagger definitions as-is. Using a subset of properties doesn't take away from that functionality.

There are explicit reasons for most excluded keywords as to why they were excluded, though some excluded keywords may have been excluded by mistake. We will not be able to provide support for most these keywords without finding proper solutions for the problems they may cause.

JSON Schema is extensible to the user's needs. We chose to extend it with our own keywords to better support the use cases that we require. There's no technical problem there. If there's a problem with a specific validator, it's a bug with the validator. By definition, the validator should ignore any additional keyword that's use that it is not aware of.

The discriminator absolutely cannot be replaced by oneOf as it is required for proper polymorphism support. oneOf will not guarantee that and could break support for strongly-typed languages.

You are partially right about the readOnly, however it significantly reduces the complexity of the schema. If anything, we may extend readOnly in future versions.

Given all the above, it does not mean we will not provide support for whichever JSON Schema version is available when we work on the next Swagger specification version. We would have to be sure that we can provide end-to-end (for producers and consumers) which we couldn't do in the last version of the spec.

[IvanGoncharov]

The existing JSON Schema validators out there should have no problem validating Swagger definitions as-is.

I'm not speaking about validating Swagger definitions instead my concern is about request/reply body validation.

There are explicit reasons for most excluded keywords as to why they were excluded

Can you please post link or short description, because it really affects further discussion.
It especially interesting, because competitive standards(API Blueprint, RAML) fully support JSON Schema without any problems.

JSON Schema is extensible to the user's needs. We chose to extend it with our own keywords to better support the use cases that we require. There's no technical problem there. If there's a problem with a specific validator, it's a bug with the validator. By definition, the validator should ignore any additional keyword that's use that it is not aware of.

If we speak only about JSON Schema standard than your right, validator could simply ignore non-standard keywords.

From Swagger point of view situation is different, lets consider the following Pet model as an example. If you simply ignore discriminator keyword than you will validate all objects only against Pet schema.

The discriminator absolutely cannot be replaced by oneOf as it is required for proper polymorphism support.

discriminator implement so-called ad hoc polymorphism, that is why it can be replaced with oneOf.
For example, I removed discriminator from Pet model example.
Same aproach used in Swagger schema to distinguish between different parameter types based on value of in property.

We would have to be sure that we can provide end-to-end (for producers and consumers) which we couldn't do in the last version of the spec.

Right now I'm aware only of two types of "consumers", which could be affected by such change:

• request/reply validators is already broken
• documentation generators(for e.g. swagger-ui) is unaffected because simply display schema

Do you now about any other affected "consumers"?

[paulhill]

I'm with @IvanGoncharov. (with respect to allowing all of json-schema). It's been a PITA to have swagger fail the spec validation because we use the same json-schema for model definition as validation. It's "thou shalt not use unblessed attributes" approach seems unnecessarily restrictive.

We don't need to add full blown json-schema support to the spec definition.
That's not what this is about.

We should relax the spec validation to allow valid json-schema in the model definitions. I've never understood what the harm is. So I include valid json schema attributes swagger should just ignore, what's the big deal?

[fehguy]

Folks, I do understand the concern. Historically, however, we have had invalid swagger specifications from a variety of tooling providers, which has made it very difficult for end-users to know "what is compatible with what". One of the most requested, and frankly most important features in 2.0 is a strict schema that should tell you whether or not your swagger specification is compliant with the spec.

If for example we started ignoring definitions in the schema, it would be up to the end user (i.e. consumer) to know great detail of the swagger specification, including what is allowed vs. what is not before being confident that the definition would work with the tooling ecosystem. This has proven over and over again to hurt the consumers of the spec.

To all you to do "whatever you want" you should consider using vendor extensions. They can be easy to produce or possibly more complicated depending on what you're looking to do.

[paulhill]

So use vendor extensions to support existing json-schema constructs?

x-anyOf ?

That seems a little... awkward, don't you think?
Not at all supported by existing json-schema validators.
Re-implement json-schema validation anyone?

:-)

[IvanGoncharov]

@fehguy I think we divert from original problem.
It's about JSON Schema keywords and only in scope of Schema object.

[IvanGoncharov]

I think we should divide problem into three parts:

1. Support for oneOf and anyOf.
   As I understand main problem is codegen for strongly typed languages.
2. Rest of unsupported JSON keywords, such as: id, definitions, etc.
   I don't see any reason why they should be excluded from Swagger spec.
3. Swagger specific extensions: discriminator and readOnly.
   I done quick search in swagger-ui, swagger-codegen and swagger-js and it seems that no one is using them. IMHO, it's look like artifacts from 1.x, which no one really use.

@fehguy, Can you please comment?

[webron]

1. this is not an issue for the codegen only. This affects all the tooling.
2. Some of the missing keywords were missed unintentionally. That said, we cannot add them not. In a future version? Sure. As for the other ones, we need to cover them and see how we can add proper support for them. Like 1) above, it's easy to say we 'support' it, but if we don't provide support for it in the tools or unable to do so, we're providing poor service.
3. readOnly is being added to the codegen as we speak. The whole model inheritance is unfortunately underdeveloped in the tools and we're behind.

[noirbizarre]

Hi !

I'm just adding my 2 cents contribution as it's an important issue to me.

I second @IvanGoncharov , supporting the full JSON Schema v4 specs is essential, in my opinion, for many reason, mostly for being able to:

• use standards and reusables validators
• reference existing schemas
• use all the primitive types (lack of null is really problematic in many cases)
• describe ALL the API (legacy and new ones)

As I understand the main caveat is that existing tooling won't be able to implement all the specs.
In my opinion, the specs should allows to describe all the APIs, the tooling need to adapt as they can.
When Swagger 2.0 specifications were released, the tooling was not ready, but the specifications permitted to every developper behind a tool to make it evolve in few monthes.

I develop a tool too (flask-restplus) and the impossibility to use existing JSON schema validator is a real handicap because it means one of these:

• I have to develop a new validator from scratch (which I won't)
• I need to monkey patch an existing one, which is dirty and cost a lot to maintain

I don't know if this the place to debate about this, if there is already a dedicated issue or a dedicated topic on the mailing list, I'll join the existing debate.

[webron]

@noirbizarre - this is definitely the place to debate it. I'd just like to clarify that for 2.0, this will not change. I completely understand the problems this causes, but no matter which way we go, it will cause problems. I'd like to try and find a hopefully generic solution as part of this ticket when the time comes to be able to provide adequate support across the board. We should thrive to evolve, but do it in a thoughtful process.

[IvanGoncharov]

We should thrive to evolve, but do it in a thoughtful process.

That is why I think current model for standardisation is problematic.
2.0 was published and only then Swagger ecosystem slowly started to adapt.
And we have situations like this, de jure spec is correct but de facto many libraries can't implement it fully.

That said, I really like 2.0 standard, and think it best standard for documenting REST API.
But let's start community efforts toward 2.1 in better way:

• Publish list of proposals, similar to JSON Schema Draft 5 list
• Start working on alpha draft, probably in separate branch and accept PR.
• Gather feedback from library owners, who provide experimental support for alpha draft.
• In case of backward incompatibility. Prepare official 2.0 into 2.1 converter beforehand.

That procedure will ensure that Swagger ecosystem will be in sync with latest Swagger spec.
And some reference implementation will be available, for library authors.
IMHO, we should make 2.1 focused on resolving only critical issues, without adding new functionality.

[webron]

I agree we should improve on the process, and when the time is right we'll make an official announcement with a suggestion for such a process (we have something in mind). The process for 2.0 was open and practically anyone could have joined. Eventually, there was an agreement on the limitations we imposed on the spec, including the non-full JSON Schema support. I cannot say yet when we'll start the process for the next version and whether it would be 2.1 or 3.0. We do have a few issues we know we won't to address there, but I'm not sure this specific issue is one of them.

[glen-84]

I think that oneOf is needed for JSON patch (schema).

I can't find any examples of using JSON patch with Swagger, and the petstore example just uses POST to update resources.

From what I understand, the PATCH method is the most "correct" way to update parts of a resource. I was going to use this method with formData, but it's unclear (+ comments) as to whether or not this is acceptable usage.

We'll probably use PATCH (or even POST) + formData for now, but it would be nice if JSON patch was supported in the future.

[IvanGoncharov]

This is what I tried to communicate previously, Swagger spec give people false hopes that they can use it together with JSON Schema.

@glen-84 You can try to use RFC7386.
It missing some features from JSON Patch.
Although in some sense it even better, because it will allow you to validate data inside PATCH and not only patch format.

[webron]

How does it give false hope when it explicitly states that it supports a subset of it?

[glen-84]

@IvanGoncharov That's interesting (thanks for the link), but I'd prefer to use something with existing client- and server-side implementations if possible.

Edit: I found some libs. We might consider this.

[jamiehannaford]

I also need oneOf for implementing JSON patch params in Swagger.

[IvanGoncharov]

@jamiehannaford I personally solve this problem by prefixing unsupported keywords with x- prefix.
That turn them into specification extensions.
Next step is to strip x- before doing validation, it simple and straightforward process.
You can create PR or issue for libraries/frameworks which you use.

[jamiehannaford]

@IvanGoncharov But if you're writing a Swagger file to power a frontend (e.g. swagger-ui), will they know to strip out the x- prefix? Will validators work out of the box too?

I ended up simplifying up the JSON patch schema like so 😒 Not great but it works...

[IvanGoncharov]

@jamiehannaford, it just one of options and maybe it will be useful for other people reading this issue.
Right now, there no public plans for extending official Swagger spec, so I think common protocol extensions is good alternative.

But if you're writing a Swagger file to power a frontend (e.g. swagger-ui), will they know to strip out the x- prefix? Will validators work out of the box too?

No, almost every tool will simply ignore x-oneOf. But adding such support is easy, just map 'x-oneOf' => 'oneOf' before validation.

I ended up simplifying up the JSON patch schema like so  Not great but it works...

But you still need to validate the same constraints that you express with oneOf.
IMHO, it better solution than separate JSON Schema file or do validation inside code.

[Relequestual]

@IvanGoncharov Would you be able to provide two samples which fully explain and show your explanation of the problem in #333 (comment) please? Specifically discriminator. I'm not sure I fully understand the problem, and would like to before trying to explain to others.

[IvanGoncharov]

@Relequestual Right now it has some problems(see #403) and they definitely could be solved.

Disclaimer: All below text is my personal opinion.
I think discriminator is broken on conceptual level.
Main problem is reinventing the wheel, JSON Schema already provide oneOf which is superset discriminator(that mean any schema using discriminator can be rewrited with oneOf).

All other problems is consequence of the first one:

• I didn't saw any real support in tools and according to @webron: "The whole model inheritance is unfortunately underdeveloped in the tools and we're behind."
• It less flexible than oneOf, main thing it require you to have dedicated field in your JSON payload. This mean that in majority of cases you should redesign your implementation. Which isn't what people want than they try to document existing implementations.
• Moreover it break separation between data and metadata. You data become aware about of some types in JSON Schema.

And generally this feature not extend JSON Schema but replace oneOf. This lead to situation where in order to use both Swagger and JSON Schema(for example on DB level) you need to maintain two incompatible specifications.

In my particular example I tried to create API interface to collection of Swagger files, so I need to document function which return Swagger file. I naively thought that I could reuse official JSON Schema to describe payload, but it use a lot of oneOf. So in that sense Swagger 2.0 it isn't self hosted :)

I personally solve this issues using this approach #333 (comment).

P.S. If you I didn't answer your question or you have some other questions we can chat here

[paulhill]

Well said.
+1

On Oct 1, 2015, at 8:31 AM, Ivan Goncharov notifications@github.com wrote:

@Relequestual Right now it has some problems(see #403) and they definitely could be solved.

Disclaimer: All below text is my personal opinion.
I think discriminator is broken on conceptual level.
Main problem is reinventing the wheel, JSON Schema already provide oneOf which is superset discriminator(that mean any schema using discriminator can be rewrited with oneOf).

All other problems is consequence of the first one:

It doesn't define well in spec, see #403
I didn't saw any real support in tools and according to @webron: "The whole model inheritance is unfortunately underdeveloped in the tools and we're behind."
It less flexible than oneOf, main thing it require you to have dedicated filed in your JSON payload. This mean that in majority of cases you should redesign your implementation. Which isn't what people want than they try to document existing implementations.
Moreover it break separation between data and metadata. You data become aware about of some types in JSON Schema.
And generally this feature not extend JSON Schema but replace oneOf. This lead to situation where in order to use both Swagger and JSON Schema(for example on DB level) you need to maintain two incompatible specifications.

In my particular example I tried to create API interface to collection of Swagger files, so I need to document function which return Swagger file. I naively thought that I could reuse official JSON Schema to describe payload, but it use a lot of oneOf. So in that sense Swagger 2.0 it isn't self hosted :)

I personally solve this issues using this approach #333 (comment).

P.S. If you I didn't answer your question or you have some other questions we can chat here

—
Reply to this email directly or view it on GitHub.

[fehguy]

Validation and modeling are different beasts. JSON schema was designed for validation, not modeling. Thus supporting everything that it has for validation does not make sense for modeling in many cases.

3.0 has greatly increased support for JSON schema draft 4.

Decide what you want the spec to do. If it's just validate, then yes, there are constructs that may make sense outside the goals of design.

[StrayAlien]

Thanks fehguy. Where can I find out more about v 3.0? If there a published draft, or a repo?

[fehguy]

It's right here in this repo. From the home page there is a link to the branch where we're working on 3.0.

https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/README.md

The in-progress spec is here, if you don't feel like reading the README:

https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md

[StrayAlien]

Thanks fehguy - I did see that branch but wasn't sure I was in the right place. (though I did see your name on it which made me think I was . :-) )

The big question is ... can it describe itself? Off for a read.

If it can, what kind of release timeframe is v3.0 set for?

Thanks again.

[StrayAlien]

"can it describe itself?". No.

No apparent schema support for id keyword and a schema having its own definitions. As v3 is at the moment I still could not use it to describe an API that produces swagger JSON ....

It there a separate v3 discussion area that you could point me to?

[MikeRalphson]

@StrayAlien

Imagine if JSON schema or XML schema could not validate themselves ...

From wikipedia's article on XML schema

Practical limitations of expressibility:
XSD cannot require a specific root element (so extra information is required to validate even the simplest documents). Content and attribute declarations cannot depend on attributes or element context (this was also listed as a central problem of DTD). [Therefore] It is not 100% self-describing ... even though that was an initial design requirement.

[StrayAlien]

Hah! Oh that made me lough out loud! Very well done Mike. :-) I read this an hour ago and I am still smiling :-) Nice.

Though, that still doesn't change my feeling that a technology for describing APIs should be able to describe an API that produces those descriptions. Kinda makes sense I reckon.

I'll explain my situation: We're not talking about a guy here wanting to describe his shopping cart app. I am part of a API standards movement in a (very) large financial organisation. Part of those standards is that going forward, all APIs should have machine readable descriptions of themselves - part of a mindset move from SOAP/WSDL and a 'service enablement' of the org and mainframe systems so on. Indeed, there is a legislative requirement looming to publicly expose a number of financial APIs and that effort is now underway. This swagger limitation means that some APIs now have to be 'special cases'

What is also means is that when some part of the organisation that is designing an API using JSON schema to describe payloads hands over their interface spec it will not be able to be described in swagger. They'll have used ids, and #/definitions and oneOf/anyOf and friends (coming in swagger v3) and whatever they need to describe the payload / param structural correctness.

If we can't use those schemas in API docs then we're sunk with swagger.

It means that existing APIs to be exposed that have not taken swagger's limitations into account may not be able to be described.

Now, I have been heard many times saying "a bad standard is better than no standard". I do honestly believe that. We need standards. But even a bad standard has to actually achieve the functionality that you need or have decent workarounds. I dearly dearly want standards like swagger to succeed. But to succeed, it must be able to describe APIs - you simply cannot ask an organisation this large with such complex APIs to dumb down their objects and schemas to something swagger can describe.

It absolutely has to be the other way around. The API description tool has to fits people needs. It cannot be people working to fit the needs of the API description tool.

And again. Nice one. Still smiling at that. :-)

[webron]

@StrayAlien - putting aside the JSON Schema discussion itself, it was never Swagger's goal to support all APIs, nor is it the goal of the OpenAPI spec. We put a lot of effort into supporting more features, more design paradigms and concerns, but it is unlikely we will ever support everything.

Not supporting your needs doesn't make it a general bad solution, it makes it a bad solution for you. Just because a 2-seater can't accommodate a family of 7, doesn't make it a bad car.

Getting back to the topic - the upcoming version will not support the full draft, but that doesn't mean it won't be in the version after that.

[StrayAlien]

Thanks webron, I do get that. And it is good to see it evolving. Any timeframes for v3 release?

[webron]

We should be making an announcement regarding the timeline in the next few days.

[StrayAlien]

cool. Thanks.

[Vayu]

Validation and modeling are different beasts. JSON schema was designed for validation, not modeling. Thus supporting everything that it has for validation does not make sense for modeling in many cases.

I'm curious what is the idea behind OpenAPI regarding validation. If models were described using JSON Schema, then the same models could be used for validation. Which would make Swagger API description the single point of reference for both documentation and validation.

Otherwise one would have to maintain separate actual JSON schema for validation, which is a rather bad idea since schema and model would have to be kept in sync by hand.

IMO Swagger model descriptions should at least use a compatible subset of JSON schema (and ideally support full JSON schema).

PS considering code-generation I don't see a problem in allowing "hard" features of JSON schema, since it is already possible to create API for which generic code generation will not work (e.g. returning object with additionalProperties: true). So if code-generators are allowed not to work in that case, perhaps they could be allowed not to work when object contains anyOf, etc.

[morsok]

Otherwise one would have to maintain separate actual JSON schema for validation, which is a rather bad idea since schema and model would have to be kept in sync by hand.

IMO Swagger model descriptions should at least use a compatible subset of JSON schema (and ideally support full JSON schema).

PS considering code-generation I don't see a problem in allowing "hard" features of JSON schema, since it is already possible to create API for which generic code generation will not work (e.g. returning object with additionalProperties: true). So if code-generators are allowed not to work in that case, perhaps they could be allowed not to work when object contains anyOf, etc.

I cannot agree more with this statement !
Currently my team cannot use swagger for our API since it is impossible to describe it without some JSON schema keywords not in swagger, this is a real shame since a one stop shop for documentation and validation would be so great !

I do really agree that if some language cannot generate code because of the way they are made, then they should juste not generate it, it seems wasteful to prevent using those keywords simply because some but not all languages are incompatible with them, different languages means different way of doing things, uniformity would be a bad thing in this case.

We should be making an announcement regarding the timeline in the next few days.

It's been quite some time but we are just out of the holidays, any news on that ? Is there a way to help drive this forward ? Since it seems most people agree now to add those keywords, what is the blocker currently ?

If possible we'd like to make this happens quickly as then the tooling needs time to adapt.

[awwright]

Hello, I'm the editor of the most recent update to the JSON Schema Internet-Draft. @Relequestual and @handrews are some of my partners in crime. Of course JSON Schema is quintessentially for validating JSON, but that's so boring: perhaps our top use case for JSON Schema is actually in Web APIs (it's certainly my focus).

The two important features around that are, first, hypermedia (defining link relations between documents), and second, document submission to Web APIs: letting a Web server declare the requirements that a submitted document must follow, so that clients can validate their submissions before the server ever needs to reply with an error message.

Well, one of the interesting things about using JSON Schema to define what's acceptable for submission, is first you have to construct a document to submit. So the validation keywords are really a way of expressing useful constraints on input that can be used for building forms and other tools for interacting with data, and it's fully anticipated that validation keywords will used for these sorts of things.

From a user interface perspective, defining a field with {"type":"number", "minimum":0} would trigger a numeric keyboard and only allow non-negative number input.

From a computing perspective, you can use these assertions to optimize database indexes, or generate client libraries like Swagger does.

Further following from this, I think it's also totally reasonable to allow a profile of JSON Schema (a subset) that makes sense for the application. For example, allowing "anyOf" would in many cases require falling back on behavior that's just as useless as {} -- allowing any possible value whatsoever.

In many cases, though, most of the keywords should be implementable, even if only at runtime. For example, "patternPropeties" would likely have to generate errors at runtime ("Error! Key foo does not match required pattern ^[0-9a-f]{40}$").

[Relequestual]

Given how long this issue dates back, there's bound to be many things which have changed.
I suggest this issue is locked, but not closed, and new issues created to target SPECIFIC key words as needed.

It's clear (and has been for a long time) that Swagger / OAI will not fully support JSON Schema (like RAML does) for the foreseeable future. I totally understanding their reasoning, and that's OK. The problem however, even if you ignore many issues, as the original creator of the issue points out, many libraries use existing JSON Schema validators, and therefore do not conform to the OAI specification.

I've suggested before, a few times, the solution to this problem is to provide a comprehensive official test suite for this purpose, which allows you to confirm compliance or not. Heck, you could even base it off our existing JSON Schema test suite at https://github.com/json-schema-org/JSON-Schema-Test-Suite

[dolmen]

@awwright wrote:

For example, allowing "anyOf" would in many cases require falling back on behavior that's just as useless as {} -- allowing any possible value whatsoever.

Allowing any JSON possible value is not useless at all. We actually need that feature in our API where some API routes are just a gateway to another system that will validate the value asynchronously. This is also necessary to define API that are JSON document stores (should allow to store/retreive any raw JSON value without validation).

[webron]

To summarize what changed in 3.0.0:

• We moved to the latest Wright Draft 00 (aka, Draft 05).
• Added support for oneOf, anyOf, not.
• Dropped the file type.
• Added clarifications to the differences between what's supported by the spec and what variations are in it.

Thanks everyone who participated in this discussion.

[MikeRalphson]

oneOf can be used inside any schema object, including those under components/schemas.