Evaluate using JSON schema

[txels]

Consider looking at JSON schema as a way to define the format and validate ABE files.

[nwhite89]

We could have something like this, will allow for providing further details regarding each part of the ABE-Spec?

{
    "description": {
        "type": "string",
        "desc": "A brief description about the Mock file."
    },
    "url": {
        "type": "string",
        "desc": "The URL Path for the mock the file is representing."
    },
    "method": {
        "type": "string",
        "desc": "The HTTP Method of the mock the file is representing.",
        "options": [
            "GET",
            "POST",
            "PATCH",
            "PUT"
            "DELETE"
        ]
    },
    "examples": {
        "type": [
            "Object", 
            "Array"
        ]
        "desc": "Contains the mock example",
        "contains": {
            "description": {
                "type": "string",
                "desc": "A brief description about the Mock file."
            },
            "request": {
                "type": "Object",
                "desc": "Contains the example request to the API",
                "contains": {
                    "queryParams": {
                        "type": "Object",
                        "description": "The query string attached to the URL."
                    }
                }
            },
            "response": {
                "type": "Object",
                "desc": "Contains the example response from the API",
                "contains": {
                    "status": {
                        "type": "number",
                        "desc": "The response status code from the API.",
                        "example-options": [
                            200,
                            201,
                            404
                        ]
                    },
                    "body": {
                        "type": [
                            "Object",
                            "Array"
                        ],
                        "desc": "The body response from the API."
                    }
                }
            }
        }
    }
}

[nwhite89]

@txels I've been looking at this a bit more now and have come up with this using http://json-schema.org/ what do you think do we need to be more implicit? To test I've been using this site http://jsonschemalint.com/

{
    "type": "object",
    "$schema": "http://json-schema.org/draft-03/schema",
    "id": "http://jsonschema.net",
    "required": false,
    "properties":{
        "description": {
            "type": "string",
            "id": "http://jsonschema.net/description",
            "required": false
        },
        "examples": {
            "type":[
                "object",
                "array"
            ],
            "id": "http://jsonschema.net/examples",
            "required": false,
            "patternProperties": {
                "([A-Z])": {
                    "type": "object",
                    "id": "http://jsonschema.net/examples/0",
                    "required": false,
                    "properties":{
                        "description": {
                            "type": "string",
                            "id": "http://jsonschema.net/examples/0/description",
                            "required": false
                        },
                        "items": {
                            "type": "object",
                            "id": "http://jsonschema.net/examples/0/request",
                            "required": false,
                            "properties":{
                                "body": {
                                    "type": "object",
                                    "id": "http://jsonschema.net/examples/0/request/body",
                                    "required": false
                                },
                                "headers": {
                                    "type": "object",
                                    "id": "http://jsonschema.net/examples/0/request/headers",
                                    "required": false
                                },
                                "queryParams": {
                                    "type": "object",
                                    "id": "http://jsonschema.net/examples/0/request/queryParams",
                                    "required": false
                                },
                                "url": {
                                    "type": "string",
                                    "id": "http://jsonschema.net/examples/0/request/url",
                                    "required": true
                                }
                            }
                        },
                        "response": {
                            "type": "object",
                            "id": "http://jsonschema.net/examples/0/response",
                            "required": false,
                            "properties":{
                                "body": {
                                    "type": "object",
                                    "id": "http://jsonschema.net/examples/0/response/body",
                                    "required": true
                                },
                                "headers": {
                                    "type": "object",
                                    "id": "http://jsonschema.net/examples/0/response/headers",
                                    "required": false
                                },
                                "status": {
                                    "type": "number",
                                    "id": "http://jsonschema.net/examples/0/response/status",
                                    "required": false
                                }
                            }
                        }
                    }
                }
            }
        },
        "method": {
            "type": "string",
            "id": "http://jsonschema.net/method",
            "required": false
        },
        "url": {
            "type": "string",
            "id": "http://jsonschema.net/url",
            "required": false
        }
    }
}

[nwhite89]

also @txels, @jonman, @jedrichards & @apibyexample/developers should we make Content-type required? for both request & response

[jedrichards]

There should be a mechanism to specify whether a Content-Type header is required for a particular request or response in the spec, but I wouldn't enforce its presence via the schema since its an optional header as far as I understand it ...

[nwhite89]

True it's because I started to look at a Node app to make mocked endpoints, I was setting the content type for the headers and realised that sometimes it's not there. Thought either should explicitly specify always in the JSON or just use a default in that scenario

[jedrichards]

Being able to optionally set a default req/res Content-Type for all the endpoints would be a good way of doing it, since afaiu it's often an API wide thing ... e.g. either the API requires Content-Type: application/json to be present, or it doesn't care. Should be able to override the default in certain endpoints too I guess.

[txels]

@nwhite re: the schema I find the id urls a bit weird ("id": "http://jsonschema.net/examples/0/response").

I think we don't need to require content-type in the schema as @jedrichards says. If it's an API-wide default it should go elsewhere, in some API config file that you load into your node mock server. I was thinking of something like that for pretenders, a separate API description file that contains info about the api as a whole, in order to mock it. That could also be used when automatically building API documentation.

[nwhite89]

fair enough, yeah the id bit I'm not sure is necessary the schema bit that I was basing it on says to use it but it may not be needed

[txels]

Maybe for ID we need something like http://rockabox.com/ or ideally if we registered a domain apibyexample.com/io/org or something.

[nwhite89]

@txels I realised this was done with JSON Schema v3 I've moved it to v4, I'd like to finalise this asap 👍 😄

{
    "title": "API By Example JSON Schema",
    "type": "object",
    "properties":{
        "description": {
            "description": "A brief description about your mock",
            "type": "string"
        },
        "examples": {
            "description": "Contains your example mocks",
            "type":[
                "object",
                "array"
            ],
            "patternProperties": {
                "(([\\w\\d])+)|((\\d)+)": {
                    "type": "object",
                    "properties":{
                        "description": {
                            "description": "A brief description about the mock example",
                            "type": "string"
                        },
                        "request": {
                            "description": "Contains the data send to the end-point within the request headers",
                            "type": "object",
                            "properties":{
                                "body": {
                                    "description": "Contains the body sent within the request",
                                    "type": [
                                        "object",
                                        "string",
                                        "array"
                                    ]
                                },
                                "headers": {
                                    "description": "Contains the information about the headers within the request",
                                    "type": "object"
                                },
                                "queryParams": {
                                    "description": "Contains the query paramaters of the request",
                                    "type": "object",
                                    "patternProperties": {
                                        "([A-Z])": {
                                            "description": "The individual query paramaters (Arrays used for multiple)",
                                            "type": [
                                                "string",
                                                "boolean",
                                                "array"
                                            ]
                                        }
                                    }
                                },
                                "url": {
                                    "description": "Contains the URL of the mock example",
                                    "type": "string"
                                }
                            }
                        },
                        "response": {
                            "description": "Contains information about the response from the API end-point.",
                            "type": "object",
                            "properties":{
                                "body": {
                                    "description": "Contains the body of the response from the end-point.",
                                    "type": "object"
                                },
                                "headers": {
                                    "description": "Contains the headers of the response from the end-point.",
                                    "type": "object"
                                },
                                "status": {
                                    "description": "Contains the status code of the response from the end-point.",
                                    "type": "number"
                                }
                            },
                            "required": [
                                "body"
                            ]
                        }
                    }
                }
            }
        },
        "method": {
            "description": "Contains the HTTP method of the end-point.",
            "type": "string",
            "enum": [
                "CONNECT",
                "DELETE",
                "GET",
                "HEAD",
                "OPTIONS",
                "PATCH",
                "POST",
                "PUT",
                "TRACE"
            ]
        },
        "url": {
            "type": "string"
        }
    },
    "required": [
        "examples",
        "method",
        "url"
    ]
}

[txels]

@nwhite89 - on first inspection this looks OK, can you submit as a PR so that we can comment on details? E.g. patternProperties for queryParams [A-Z] seems too limiting.

[nwhite89]

yep no problem I shall take a look at doing this today hopefully 👍

[nwhite89]

for the last part of this I'm going to look at making a grunt helper using an already existing JSON Schema validator