Clarification: Source Description Object - type parameter

[ndenny]

In the spec, sourceDescriptions contain name, and url, both required. And then also type, which is not explicitly required - but I don't see anywhere where we say what it should be defaulted to if not set. The JSON schema also does not enforce a value, but does say it's an enum.

In discussion on Slack, @jeremyfiel pointed out that I think this is because we (in fact, probably me!) wanted to allow you to potentially specify other API definition types - e.g. for SOAP, or RAML, etc.

In which case, the JSON schema will need to be more permissive? And even then, I think we need to specify that type is required. Or should we just say that openapi or arazzo is the assumption if not set?

[frankkilcommins]

The expected type of a Source Description Object is either openapi or arazzo in the current specification version, and as stated by the following.

Possible values are "openapi" or "arazzo".

The type field is itself an affordance and if omitted, tooling would have to load and parse the document available at the Source Description Object url to determine if it's and openapi or arazzo document.

[frankkilcommins]

Could be beneficial to harden the documentation surrounding this field.

It's almost a human read affordance rather than anything else.

Tooling processing source descriptions should:

• determine the true source description type by loading and parsing the document
• if the actual type differs from the specified type, likely a validation error should be thrown
• supported actual types (as of 1.0.1) are openapi or arazzo