Sway should have options to accept a vendor specific swagger schema

[amarzavery]

Why am I asking this?

We have developed our (vendor) extensions and have added that to the swagger schema. We want to take advantage of the z-schema validator.
This is the link to our swagger schema with extensions.

How it will benefit the community?

It would be nice if Sway would provide an option

• to accept a different swagger schema than the one it is using right now.
• to set remote references for the external schemas used in our scehma. This is required by the z-schema validator.
  • If Sway can expose the validator so that customers can add external references to it then that would be fine as well.

If nothing is provided then by default Sway will use the current one it is using right now.

This will help us take advantage of the z-schema validator. I tried playing with it by locally modifying couple of lines in the validator.js and helper.js and it worked like a charm. The tool was not giving any warnings for our extensions and it also threw an error when i tried to use an extension incorrectly.

What do you think about this?

[whitlockjc]

I'm not sure I want to support custom Swagger documents. I'm not completely against it but since we already give you APIs for registering custom validators and will soon have an API for registering custom format validators and an API for registering custom format generators, is there really a need for this?

[amarzavery]

Open-API allows us to provide extensions on any part/artifact of the swagger spec. The extensions are not limited to being used for "types" and "formats".

For example: we have an extension to describe a "long-running/asynchronous" operation and an extension to describe a "pageable" operation. We also have an extension for specifying examples.

All the extensions are described/added in the swagger schema which was derived from the actual swagger schema.

I believe, exposing an option to add a custom schema will only add value. The default behavior would still be the original swagger schema. If the customer is using his/her custom schema then he/ she would be responsible for any undesired outcome. Sway is no way responsible for anything over there.

By providing a mechanism to add the custom schema, we get the z-schema validation for free. It reduces an extra pass of validation in the end.

I am sure you would have valid concerns as you know the tool better than anyone else. If possible can you please list those concerns? This will help us better understand the tool.

[whitlockjc]

The point I made is that sway already has an API to register custom validators, so validations for custom extensions and other stylistic checks that are not covered by the Swagger specification itself. I'm not saying sway doesn't support custom Swagger documents, I'm saying that all extension support Swagger supports sway does, other than the two open issues.

What isn't working like you want? If you are using vendor extensions, just register a custom validators to perfo m the validation you want.

[whitlockjc]

To me, I read your request as you saying you've taken the JSON Schema file from Swagger, altered it and want sway to read it in as the JSON Schema for Swagger. If that's the case, that is not a supported Swagger approach.

I'm going to get @webron's eyes on this too.

[amarzavery]

Yup I was looking at that. We do like that in our CI.
First set all the remote references and then Validate the spec against the schema.

I want to start using Sway in our CI. It is definitely a value add. I was thinking if I can do the structural and semantic validation in one pass then that would be awesome. Hence filed an issue with the request.

[amarzavery]

We are not modifying the swagger schema in any way, as that would be against the rules. We are simply adding schema for our extensions so folks in Azure get intellisense experience for the custom extensions and can get validation errors if they are used incorrectly.

[whitlockjc]

So what doesn't work like you want? If you can register a custom validators for the document, what is missing? I'm missing something or overlooking it in your original message.

[amarzavery]

I am sorry. I replied to your second comment.

To me, I read your request as you saying you've taken the JSON Schema file from Swagger, altered it and want sway to read it in as the JSON Schema for Swagger. If that's the case, that is not a supported Swagger approach.

Yes, I meant that. We have not altered the schema. We have simply extended it to add schema for our custom extensions. Then I gave an example of how we are doing it in our CI.

//Setting the remote references

validator = new z({ breakOnFirstError: false });
var valid = validator.validate(parsedData, extensionSwaggerSchema); // our version of the swagger schema
var error = validator.getLastErrors();

The above code is very similar to what is happening in Sway at

• instantiating the validator

[helper.js L104 - var validator = new ZSchema({
    breakOnFirstError: false,
    ignoreUnknownFormats: true,
    reportPathAsArray: true
  });](https://github.com/apigee-127/sway/blob/master/lib/helpers.js#L104)

• actual validation

[helper.js L443 - if (!validator.validate(value, schema)) {
    response.errors = _.map(validator.getLastErrors(), function (err) {
      normalizeError(err);

      return err;
    });
  } in validateAgainstSchema()](https://github.com/apigee-127/sway/blob/master/lib/helpers.js#L443).

[webron]

It's an interesting situation. Sway, as far as I understand, allows you to provide custom code validations (and uses some of its own), but at the core uses a JSON Schema to validate the spec.

@amarzavery is asking for a way to use an altered (sorry, @amarzavery, any kind of mutation is altering, even if just adding) version of the schema to validate additional vendor extensions added within the scope of Azure (which is exciting!).

I get why @whitlockjc is a bit wary of this because that's a core functionality and there's a way to extend validations. I imagine you can even write a custom validator that would run against the altered JSON Schema and provide the same feedback, but a - it would come at a performance cost (especially if it's all the schema and not just the added extensions) and b - it would serve as a maintenance burden for the user. I'd say it could be an advanced feature that Sway provides, but I can't say whether it's something Sway should provide or not.

That's my 2c :)

[whitlockjc]

Well, I'm not interested in supporting custom Swagger documents primarily because that is not the way to extend Swagger. Swagger supports vendor extensions to extend Swagger without the need to customize its core JSON Schema. On top of that, Sway has support for registering custom validators which will let you validate these vendor extensions any any other stylistic things you'd gain by modifying the Swagger JSON Schema.

To me, it just doesn't seem necessary and I just don't think extending Swagger this way makes sense.

[webron]

@whitlockjc I believe they are using vendor extensions, they're just using a modified json schema to validate their own vendor extensions. Azure specs are by all means valid Swagger specs - they're not customizing it beyond.

[whitlockjc]

I didn't see mention of vendor extensions being used, that's why I suggested them. Regardless, Sway allows you to write your own validators and they can validate anything you want them to, including vendor extensions.