Proposed format: jsonObject and jsonArray to type: string

[deefactorial]

Here is the problem:

I'm lacking the tools to fully validate the response of an API end point of 3rd party middleware. The middleware is passportJS and the response is JSON.stringified before being sent. The only way I've found to validate the response is to say that it's a string and perhaps provide a regex to the string. But what I would really like to do is JSON.parse the string and validate the contents of the string.

What is the proper way to define an response to do so ?

Perhaps there is a way to do it with the 2.0 spec. If there isn't a way I would like to propose a format: jsonObject and format: jsonArray added to the type: string

proposed format: jsonObject:

definitions:
  token_response:
    type: string
    format: jsonObject
    minProperties: 2
    maxProperties: 5
    required:
      - access_token
      - expires
    properties:
      access_token:
        type: string
      expires:
        type: string

proposed format: jsonArray

definitions:
  list_response:
    type: string
    format: jsonArray
    items:
      type: string

[deefactorial]

I'm closing this issue,
It's due to a bug in swagger-tools response validation.
apigee-127/swagger-tools#333

[deefactorial]

I'm re-opening this issue, because I think this would be a great proposal for the 2.0 specification.
It would allow me to validate json encoded strings.

[ePaul]

So you are wrapping JSON data into a string, and put this into some JSON data structure? This sounds somehow wrong. Why not include the JSON data directly in your data structure?

(Also, you can use any format string as you want, just the ones in the spec have predefined meaning.)

[deefactorial]

The problem I encountered was with a common third party middleware that JSON.stringified the response before sending as the http body. Therefore I could only validate that the output was a string, and not the contents of the string. If there was a method to define that a string contained a json object or json array, then I could validate the contents of that string contained a json object or json array, and the proceed to validate those objects or arrays within the string.

I want to be able to validate the output of a middleware without having to change the middleware just to validate it. See the swagger tools error above.

[webron]

Tackling PR: #741

[webron]

This is covered in 3.0 now in a different way. You can specify that any parameter is serialized as application/json and the validation can follow the specified schema.

[ePaul]

@webron I think that @deefactorial didn't want to use JSON for parameters (or response headers), but to have string-typed fields in a normal JSON response (or request) body (i.e. properties in a schema) containing a serialized JSON object or array, and to describe what is in there.

I guess this could solved the same way, if a schema object with type: string would also support the same properties as a parameter, or at least content. But I think this is not what was intended there (and I also don't think we really want to support this).

As an example derived from the OP's example:

definitions:
  foo:
    type: object
    properties:
      token:
        $ref: '#/definitions/token_response'
  token_response:
    type: string
    content:
      'application/json':
         schema:
           type: object
           minProperties: 2
           maxProperties: 5
           required:
             - access_token
             - expires
           properties:
             access_token:
               type: string
             expires:
               type: string

And an object fitting foo would then be e.g.

{
   "token": "{\"access_token\":\"abcd\", \"expires\":\"tomorrow\"}"
}

[webron]

That's not my understanding from the post, but if @deefactorial wants to clarify, then by all means.

If it's what you think, then agreed, we shouldn't support it.

[deefactorial]

Yes, ePaul was correct. I wanted to be able to validate the contents of a string that contains JSON. It all stems from this issue:

jaredhanson/oauth2orize#156

In which a middleware project stringified the output before being sent. Therefore I didn't have the the tools to be able to verify the output of the stringified response without modifying the middleware package.

[provokateurin]

So is this solved or not? I have exactly the same problem as @deefactorial. @ePaul's example looks like a good proposal, but as far as I understand it was just to show how it could look like, not how it actually works, right?

[karenetheridge]

Yes, it's solved. You can use the "content*" keywords in the json schema in an openapi 3.1 document, if your evaluator supports those keywords.

https://json-schema.org/draft/2020-12/json-schema-validation.html#name-a-vocabulary-for-the-conten

[provokateurin]

Oh that's nice :)