raml-org/raml-java-parser

Validation of example is trying to parse a date value as XML or JSON

juanchib opened this issue · 4 comments

#%RAML 1.0
title: test 

/test:
  get:
   queryParameters:
     timeout:
       type: date-only
       required: true
       example: <2019-09-09>

Validation of the example is throwing - Error validating XML. Error: The markup in the document preceding the root element must be well-formed. [line=11, col=17] when the expected error message is Provided value <2019-09-09> is not compliant with the format date_only provided in rfc3339
Same happen when the example value starts with { the example is treated as JSON.

The way I can do this is attempt to actually parse the example as either XML or JSON and upon failing that, not treat it as a XML or JSON document.

This makes invalid JSON examples error messages more obscure:

/hello:
  get:
  post:
    responses:
      202:
        body:
          application/json:
            type: object
            properties:
              key:
                type: object
                properties:
                  x: string
                example: |
                  {
                  x: "lala"
                  }

used to say: "Error validating JSON. Error: Unexpected character ('x' (code 120)): was expecting double-quote to start field name"
But now says: "Invalid type String, expected Object for example", as it will now not be parsed as json, it will be treated as a string.

Honestly, I don't think it's worth the change. I'll try to find a better solution, but there's not many variations.

On a semi-related note: be aware that in RAML, examples do not have to be defined in the same syntax as the media type(s) of the parent resource.

There are two reasons for this:

  1. Content negotiation: some APIs and their underlying resources may support content type negotiation which means that a given payload in the API definition may be defined in YAML or JSON but the actual payload that people would end-up seeing/getting over the network could be in a different media type. One way to achieve this could be to use the RAML default media type feature.
  2. Also, what an API definition primarily describes is the semantic, not the syntax (although it can enforce a particular syntax). Examples in RAML are defining the semantic (it's an object, it has properties, those properties may have certain values) and that can be represented in any supported format.

The issue comes from the fact that there is "pre-processing" validation happening when an example defined on ANY type starts with either < (XML), or {, [ (JSON). That validation should only happen when the type or one of the subtypes (union) is object.

@juanchib: make sense?

@jstoiko yes it makes total sense to me. Thanks