Support JSON Schema "not"

[dschenkelman]

http://json-schema.org/latest/json-schema-validation.html#anchor91

[webron]

Can you give an example for a use case where you'd want to use "not"? Currently, there are other json schema validation conditions that we don't support and we're a bit wary of adding support to some of them due to unnecessary complexity.

Since this is a spec procedure, it's better to elaborate how and why think think a change is required.

[dschenkelman]

@webron sure. The example that got me thinking of this is:

With the current version of JSON schema, the simplest way to indicate that a value is not valid for a particular schema is "email": { "not": {} }.

Valid values are a big part of an API's docs, and invalid values also are. Being able to indicate to users that a particular value is something that would be very useful.

Thoughts?

[webron]

Right, but since you have the validation options, you can actually express it as:

"email": { "type": "string", "minLength": 1, "pattern": "..." }

Of course, specifically for email:

"email": { "type": "string", "format": "email" }

It would really help to see an actual example that cannot be expressed this way.

[dschenkelman]

We have a concept of metadata. It's an object that can have anything except for some specific properties, such as e-mail.

We can't use something like additionalProperties:false, since we don't know in advance the potential values, we only know what those values can't be.

Let's say the only invalid property is email, then the schema would be:

{
  "type": "object",
  "properties": {
    "email": { "not": {} }
  }
}

This schema is valid for all objects that don't have an email property, which is what we want to express.

Sorry for the small amount of detail in the previous comment. Hope this makes things clearer.

[webron]

Yes, it does.

Unfortunately, that's one of the side effects we have in Swagger 2.0 which I dislike.
I don't think we should have added support for 'whatever value you want', and to me it was an unwanted result of the way we included additionalProperties.

To me, that pretty much misses the point of documenting your API. Plus, being able to send/receive a random reply is almost never useful. This wasn't really supported by previous versions of Swagger.

I understand some APIs do it, that doesn't mean we should have supported it. There are a few API paradigms out there that we don't support and don't intend to support.

That said, this got in Swagger 2.0 and it is what it is. My main concern with adding support for not is that it can lead to abuse and edge cases that we may not want to support. It makes the tooling that much more complicated (UI, codegen and so on).

Of course, I understand the need to tell users what a is or isn't a valid input/output, and it is indeed an important part of the documentation.

What we can try doing is find those edge cases where we don't want to support not or where it could cause extra trouble, and see if we can define it better within the scope of our needs. Perhaps just saying we support not is not good enough and we need to constrain it better.

[dschenkelman]

I see what you mean. Totally agree that in general JSON schema validations can be pretty specific about constraints.

Perhaps it might be worth considering a way to specify that a property is not valid instead of supporting the entire "not" feature.

[webron]

That's a possible alternative, sure. I'll mark it as a proposal for the next version of the spec, and let's give people a chance to give their input.

[webron]

Parent: #579.

[webron]

Tackling PR: #741

[webron]

not is in 3.0!