One parameterSchema or one each for URL Parameters, headers and body?

[darrelmiller]

If we just have one parameterSchema then we need to reserve the property names "headers" and "body" in the parameterSchema. This could cause problems if someone has an API with those names as url parameters.

The advantage of one parameterSchema is that it would be possible to have dependencies between the URL parameters, and header parameters, and body content. It also makes the specification design simpler and makes request selection simpler.

[mkistler]

I think it is desirable to support dependencies between the different types of parameters, so I hope we can keep these all in one schema.

Could we use a JSON schema dialect to define our own in keyword that would distinguish "header", "cookie", "path", and "query"? Would JSON Schema allow us to define a "default" for in, say as "query"? If not I suppose we could still make it work: from a validation perspective, a parameter without "in" would validate if present as any parameter type ... that might be okay.

[darrelmiller]

That would be an alternative to the reserved property names that I used in the rpc examples. I'm not sure which I prefer.

[handrews]

@mkistler the trick here is that it has to work for both generative and evaluative use cases. In a generative use case, reading "in": "header" is straightforward. In an evaluative use case (like validation), you need to figure out how to map the instance data into the JSON Schema data model so that the schemas get applied to the right things.

Probably the best guide for that would be to define a mapping of the application/http media type (or a well-defined subset) into the JSON data model, but that just occurred to me this morning so I have not thought it through.

[AML14]

According to our research, dependencies between parameters of different types are extremely rare, but they do happen. Think, for example, an ID path parameter which must coincide with an ID property in the request body when making a PUT request to modify a resource. Therefore, I agree with Mike that we should have just one parameterSchema, if that is the only way to support these types of dependencies.

[handrews]

You could just model HTTP as an object with three fields: body, headers, and parameters. then you replace contentSchema, parameterSchema, and possibly contentType with schema/body, schema/parameters, and possibly schema/headers/properties/content-type (or schema/headers/properties/contentType if you want to require mapping between camelCase and header-name-with-dashes).

Then you don't have the duplication between different schemas, and you haven't reserved any actual parameter names.

Of course, schema/headers/properties/content-type is a pain for something so common so maybe you have a shortcut for that. Since tools probably don't get headers in the exact right object/array format to go straight to a schema, it's relatively acceptable to have to do some massaging on the header schemas.

[darrelmiller]

Creating a body and headers parameter is what I did so far. I hadn't considered creating a parameters property. I wouldn't want users to have to create a parameters property for simple cases where there is no need to specify headers or a body. Anyway, we have lots of options.

[handrews]

The absence of a parameters or body field would indicate that anything is allowed. But to forbid either, it would just be "parameters": false or "body": false. So it's a question of whether "anything is allowed" is an appropriate default behavior, and whether having to add "body": false would be burdensome. I can't really judge this sort of thing as I pretty much write JSON Schema on auto-pilot at this point.