Should path parameters be implicitly required in the parameterSchema JsonSchema?

[ouvreboite]

(I hope I'm following the right process for this kind of discussion, don't hesitate to redirect me if needed 🙂)

The problem
Looking at the various examples, I have the feeling that having parameterSchema being a full JsonSchema will lead to either inconsistent definition or too much verbosity.

Extract from the petstore example

"pet/{petId}":
    parameterSchema:
      type: object
      properties:
        petId: #this is implicitly required?
          type: string
          format: int64
    requests:

For example, petId is not marked as required, while it is (it's a path parameter, not an optional query parameter). This gives us two options:

• implicit required (current solution): we have some implicit schema manipulation ("if the property is a path parameter, it's implicitly required") ➡️ So parameterSchema is supposed to be a 'raw' JsonSchema, but does not really behave like one. Furthermore, when handling both path params and required query params, should only the required query params be marked as required? Or also the path params?
• explicit required: we force designers to mark their path parameters as required ➡️ This will increase the verbosity of documenting path parameters, while one of the goal of OASv4 is to improve readability and editability

🗎 Implicit required confusion example:

"pet/{petId}/uploadImage{?requiredQueryParam,optionalQueryParam}":
    parameterSchema:
      type: object
      required:
        - requiredQueryParam #it's even less clear that petId is required :(
      properties:
        petId: 
          type: string
          format: int64
        requiredQueryParam:
           type: string
        optionalQueryParam:
           type: string
    requests:

🗎 Explicit required verbosity example:

"pet/{petId}":
    parameterSchema:
      type: object
      required:
        - petId #now we have 2 new lines for something implicit :(
      properties:
        petId: 
          type: string
          format: int64
    requests:

Proposal

If we want to improve readability and editability, I think the path parameter must be implicitly required, but we could go a bit farther. For example, it's could also be implicit that parameterSchema is type: object. Factoring the type: object out, only the properties and required part of the JSonSchema remains. And those could be moved directly on the path object.

So, instead of expecting a full JSONSchema, we could have the path (and request) object expose both path.parameters (~= JsonSchema's object.properties) and path.requiredQueryParameters (~= JsonSchema's object.required), with path parameters being implicitly required.

We could also use path.properties (~= JsonSchema's object.properties), and path.required (~= JsonSchema's object.required), keeping us closer to JsonSchema syntax, but I fear it would become confusing.

This would make the syntax more compact, while avoiding confusion when mixing path parameters and required query parameters. But we would still leverage JsonSchema's property syntax.

🗎 A petstore-like example

• more compact than before
• more explicit than before

"pet/{petId}":
    parameters: 
        petId: #implicitly required as it's a path param
           type: string
           format: int64
    requests:
"pet/{petId}/uploadImage{?requiredQueryParam,optionalQueryParam}":
    requiredQueryParameters: #we only need to explicit the required query params
        - requiredQueryParam
    parameters: 
        petId: #implicitly required as it's a path param
           type: number 
        requiredQueryParam:
           type: string
        optionalQueryParam:
           type: string
    requests:

🗎Applying it to the parameterSchema example

• we can still leverage the JsonSchema property syntax to support different response schema based on query parameter value

'speakers/{speakerId}{?format}': 
      parameters:
          speakerId: #implicitly required as it's a path param
              type: string
              title: Speaker ID
      requests:
          getSpeakerAsJson:
              parameters:
                  format: #still supports different response schema based on query parameter value
                      type: string
                      const: json
              method: get
              responses:
                  ok:
                      status: 200
                      contentType: application/json
                      contentSchema:
                          $ref: '#/components/schemas/speaker'
          getSpeakerAsCSV:
              parameters:
                  format:
                      type: string
                      const: csv
              method: get
              responses:
                  ok:
                      status: 200
                      contentType: text/csv
                      contentSchema:
                          type: string