Keep primitive types within JSON schema draft specs

[tlivings]

Adding the file "primitive" is not something that is out-of-the-box validation by any JSON schema validator. It seems like this type is not a primitive, and also requires additional checks for consumes.

This requires a special edge case just for validating when type is file. And in fact, it is not validating the type, but rather the consumes.

It seems lie the appropriate path would be to not add to JSON schema spec, since developers implementing tools for swagger would simply perform their own assertions for multipart/form at the framework level.

[webron]

Not sure I follow you here, @tlivings.

[tlivings]

3.5.  JSON Schema primitive types

array
boolean
integer
number
null
object
string

and then from swagger

Data Types

Primitive data types in the Swagger Specification are based on the types supported by the JSON-Schema Draft 4. Models are described using the Schema Object which is a subset of JSON Schema Draft 4.

but

An additional primitive data type "file" is used by the Parameter Object and the Response Object to set the parameter type or the response as being a file.

File, is not a primitive. It can not be validated standalone as a primitive because:

If type is "file", the consumes MUST be either "multipart/form-data" or " application/x-www-form-urlencoded" and the parameter MUST be in "formData"

No JSON schema parser will support this, and as a result additional custom validation must be performed at a framework level to support swagger. Since this is the case, then there is little need to introduce a new "primitive" at all.

[tlivings]

Follow up: file should be a format and not a type.

[tlivings]

Another idea would be to use the hyper schema extensions for JSON schema. Example:

"imgData": {
    "title": "Article Illustration (small)",
    "type": "string",
    "media": {
        "binaryEncoding": "base64",
        "type": "image/png"
    }
}

[mohsen1]

@tlivings Swagger-Tools goes beyond JSON Schema to validate things like this. If you're validating Swagger 2.0 specs in JavaScript I recommend it instead of pure JSON Schema validation.

I understand your point about primitives but for 2.0 it's not going to change.

[tlivings]

Those are interesting tools, but Swagger is a specification, and that module is from a vendor, and is framework specific (example: connect/express middleware). In addition, I doubt the schema validation is as fast as some of the latest validators out there such as is-my-json-valid for example.

Swagger, afaik, wasn't designed to be a specification for apigee tools or insert framework / library here.

A specification that is using JSON schema should follow JSON schema standards, not introduce implementation specifics that do not work with standards.

[mohsen1]

@tlivings Swagger Tools is not vendor specific and it's MIT licensed. No reason to worry about Apigee paying it's maintainers do the work. Swagger offers a schema that tries to cover most of the spec. Note that schema is not the spec. There are some specifications in Swagger that is impossible to enforce via JSON Schema. For example "Each operation should have only one parameter of type body" and many more

[tlivings]

The issue isn't regarding Apigee maintaining the tool (wasn't implying that), and nor is it regarding general specifications of the swagger schema.

The issue is that swagger claims to be JSON schema, and it is not. It adds a new primitive type, that is not a primitive. This requires every single consumer of the specification (i.e. anyone writing a framework or library) to provide the special edge case validation themselves.

If it's going to be JSON schema, it should be standard JSON schema for the reasons outlined here and above. The specification can continue to have requirements around it while still conforming to schema.

[webron]

@tlivings - thank you for clarification and input.

If I understand correctly, you're referring to the usage of JSON Schema for the Schema Object and not the specification as a whole. In that case, I mostly agree with you. I don't know if file should be a format but we may want to explore a better way of defining it.

Normally when describing it, I say that the Schema Object uses an extended subset of the JSON Schema, since we do extend it. That's not the wording used in the spec and I may need to change that.

As @mohsen1 said though, this is not going to change for 2.0 but it's a good point for the next version of the spec.

[tlivings]

Yeah, as mentioned above, using hyper schema extensions in the spec may be the right path forward in the future.

Fully aware than nothing can change this version. Just wanted to raise the issue!

Thanks.

[viswguru]

    "/xxx-yy-ppp-rs-v1/person/trackitt": {
        "post": {
            "operationId": "/trackitt",
            "consumes": [
                "application/vnd.xxx-yy-ppp-rs-v1+xml"
            ],
            "parameters": [
                {
                    "name": "consumer",
                    "in": "header",
                    "required": true,
                    "type": "string"
                }, {
                    "name": "timestamp",
                    "in": "header",
                    "required": false,
                    "type": "Date"
                }, {
                    "name": "digest",
                    "in": "header",
                    "required": false,
                    "type": "string"
                }, {
                    "name": "guid",
                    "in": "header",
                    "required": true,
                    "type": "string"
                }, {
                    "name": "user-ref",
                    "in": "header",
                    "required": true,
                    "type": "string"
                }, {
                    "name": "sender-machine",
                    "in": "header",
                    "required": true,
                    "type": "string"
                }, {
                    "name": "correlation-id",
                    "in": "header",
                    "required": false,
                    "type": "string"
                }, {
                    "name": "partner-id",
                    "in": "header",
                    "required": false,
                    "type": "string"
                }, {

                    "in": "body",
                    "name": "request",
                    "description": "Request body",
                    "required": true,
                    "type":"object",

                    How can i Ref an node in schema person as below using 
                    #ref or any other way (as consumer is "application/vnd.xxx-yy-ppp-rs-v1+xml")
                     i need sample example 

                    },

                }
            ],
            "responses": {
                "200": {},
                "500": {}
            }
        }


        <person>
        <lastname></lastname>
        <lastname2></lastname2>
        <lastname3></lastname3>
        </person>

[webron]

@viswguru - I don't really see what this has to do with the issue at hand. Please use the Google group for general support questions.

[tlivings]

@webron: bumping this thread for a little more focus.

Still would like to call for any primitive type to be validatable by value alone.

[webron]

This is somewhat related to #430 and #50.

Parent issues: #565 and #579.

[ePaul]

@tlivings As I understand, the file type is just for the cases where your data (a body or form parameter, or a result body) is not in JSON format (but e.g. PDF, an image format, etc.). Using JSON Schema then doesn't make any sense.

[tlivings]

A primitive type is a type that can be validated on value alone. For something like file, hyper media extensions can be used.

[webron]

Tackling PR: #741

[webron]

PR #878 removed file type! 🎉

[tlivings]

Woot!

[spacether]

Related: #3024