Rework using webapi-parser

[postatum]

Major changes:

• Reworked to work with webapi-parser;
• New dependency: webapi-parser;
• Dropped dependencies: json-schema-compatibility, is-stream, object-values, raml-validate;
• Dropped option: RAMLVersion (now inferred automatically);
• Default exported function API Changed: It now accepts webapi-parser.Operation object as first argument, path string as second argument, method name as third and options object as final argument;
• Changed errors format;

Minor changes:

• Updated dependencies' versions;
• Switched to const/let instead of var;

Making a release:

• Release dependencies PRs;
• Bump major version and make a release;

PR depends on:

• Rework using webapi-parser osprey-resources#23
• Rework using webapi-parser node-raml-sanitize#13

To test the PR locally with all the reworked Osprey sub-dependencies, use this Makefile.

---

Error format change

The new version changes the errors response format for RAML and JSON Schema validation errors. The new errors responses are more uniformal and descriptive while at the same time being less verbose. The change is caused by the fact that a different parser is used to parse RAML specs, which in turn produces a different parsed document model.

Let's explore the changes on body validation examples.

JSON Schema validation example responses

Number value is greater than the "maximum":

Old:

{
  "errors":[
    {
      "type":"json",
      "keyword":"schema",
      "schema":"{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"type\": \"object\",\n  \"minProperties\": 2,\n  \"properties\": {\n    \"firstName\": {\n      \"type\": \"string\"\n    },\n    \"lastName\": {\n      \"type\": \"string\"\n    },\n    \"age\": {\n      \"type\": \"number\",\n      \"minimum\": 5,\n      \"maximum\": 99\n    }\n  }\n}",
      "data":{
        "firstName":"John",
        "age":200
      },
      "message":"invalid json (schema, {\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"type\": \"object\",\n  \"minProperties\": 2,\n  \"properties\": {\n    \"firstName\": {\n      \"type\": \"string\"\n    },\n    \"lastName\": {\n      \"type\": \"string\"\n    },\n    \"age\": {\n      \"type\": \"number\",\n      \"minimum\": 5,\n      \"maximum\": 99\n    }\n  }\n})"
    }
  ],
  "stack":"..."
}

New:

{
  "errors":[
    {
      "type":"json",
      "keyword":"maximum",
      "dataPath":"/age",
      "message":"should be <= 99",
      "data":200,
      "schema":99
    }
  ],
  "stack":"..."
}

Less properties than "minProperties":

Old:

{
  "errors":[
    {
      "type":"json",
      "keyword":"schema",
      "schema":"{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"type\": \"object\",\n  \"minProperties\": 2,\n  \"properties\": {\n    \"firstName\": {\n      \"type\": \"string\"\n    },\n    \"lastName\": {\n      \"type\": \"string\"\n    },\n    \"age\": {\n      \"type\": \"number\",\n      \"minimum\": 5,\n      \"maximum\": 99\n    }\n  }\n}",
      "data":{
        "firstName":"John"
      },
      "message":"invalid json (schema, {\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"type\": \"object\",\n  \"minProperties\": 2,\n  \"properties\": {\n    \"firstName\": {\n      \"type\": \"string\"\n    },\n    \"lastName\": {\n      \"type\": \"string\"\n    },\n    \"age\": {\n      \"type\": \"number\",\n      \"minimum\": 5,\n      \"maximum\": 99\n    }\n  }\n})"
    }
  ],
  "stack":"..."
}

New:

{
  "errors":[
    {
      "type":"json",
      "keyword":"minProperties",
      "dataPath":"",
      "message":"should NOT have fewer than 2 properties",
      "data":{
        "firstName":"John"
      },
      "schema":2
    }
  ],
  "stack":"..."
}

RAML validation responses examples

Number value is greater than the "maximum":

Old:

{
  "errors":[
    {
      "type":"json",
      "dataPath":"age",
      "keyword":"maximum",
      "schema":99,
      "data":200,
      "message":"Value 200 is greater than maximum 99"
    }
  ],
  "stack":"..."
}

New:

{
  "errors":[
    {
      "type":"json",
      "keyword":"maximum",
      "dataPath":"/age",
      "message":"should be <= 99",
      "data":200,
      "schema":99
    }
  ],
  "stack":"..."
}

Less properties than "minProperties":

Old:

{
  "errors":[
    {
      "type":"json",
      "keyword":"minProperties",
      "schema":2,
      "message":"Too few properties defined, minimum 2"
    }
  ],
  "stack":"..."
}

New:

{
  "errors":[
    {
      "type":"json",
      "keyword":"minProperties",
      "dataPath":"",
      "message":"should NOT have fewer than 2 properties",
      "data":{
        "firstName":"John"
      },
      "schema":2
    }
  ],
  "stack":"..."
}

[jstoiko]

Major changes:
(...)

• Changed errors format;

it would be nice to explain the rational behind this change (i.e. why it was needed) and what this change implies for the end-users.

[postatum]

it would be nice to explain the rational behind this change (i.e. why it was needed) and what this change implies for the end-users.

Updated the issue description to describe error format change in detail. Please let me know if the update looks good.