Suppress INVALID_TYPE errors when the property is set to null value in the example

[veronicagg]

Opening this issue to address Azure/azure-rest-api-specs#798 in OAV tool.
Since it's a swagger limitation to specify allowing null values, let's allow null to match any type when a property comes back with this value in a response. This way model validation should not report errors and avoids noise (we have seen a lot of case where the Azure service behaves this way, and no cases where a fix is expected on the service side).

[veronicagg]

Let's check a few examples to see if the service is actually returning null or the example is wrong and should actually not have the property with null value in it.

[veronicagg]

#158

[vishrutshah]

@amarzavery As we discussed this offline, on some lines of how should we tackle it right instead of going to the route or ignoring this, could you please add some context. Thanks!

[vishrutshah]

un-assigning as my focus would on #142 for next sprint.

[amarzavery]

• As we know that swagger spec is a sub set of json schema. For example json schema supports oneOf, anyOf, allOf. But swagger 2.0 only supports allOf.
• In the same way, swagger 2.0 says that the type of the schema (i.e) type of a model, type of a model property, type of a parameter can only be a string. I mean, we can say "type": "number", "type": "array" i.e. the value for the type property can only be of type string. However, JSON schema says that "type" can be an array/combination of basic json types "type": ["array", "object", "boolean", "string", "number", null] . Notice the null without quotes as a valid type.
• So we can have an option called options.resolveNullableTypes in the specResolver.js class. When set to true we will convert the "type" from string to an array comprising of the existing value of that type and null. Now when we give such a schema to z-schema to validate the model it should not complain.
• This will make it easy for us to not resolve nullable types for semantic validation (similar to what we do for resolving discriminators (replace with oneOf) today).
  • We can expose this via oav resolve-spec command with a new switch -n which resolve nullable types only when specified.

NOTE: We should not do this for all the model properties. This should be done only when

• the property is optional OR
• the property has the extension ("x-ms-nullable": true). When this extension is applied, it does not matter whether the property is required or not. The spec author is clearly saying that he/she wants this property to accept null as a valid value and we should honor that (We have such an example in resource deployment swagger spec).

In this way we can handle the issue in a better way.

[veronicagg]

Thanks @amarzavery I like the proposal, I'll look into this a bit more to prep a fix.
Should it be x-ms-nullable, or x-nullable?

[amarzavery]

Autorest supports x-nullable. It is a more generic extension that other tools mostly support as well. Hence Garrett thought of using the name x-nullable.

[veronicagg]

thanks @amarzavery ok, then looks like we should use x-nullable here too.

[amarzavery]

This StackOverflow link provides good explanation about requiredness type in a json document.