Thanks @hkosova.

... can be defined as a single parameter whose value is a dictionary ...

Unfortunately, I'm not at liberty to change the API at the moment. The tag names have to be the query string parameter names as this is an existing API with many clients.

The dictionary value would be a good approach going forward for new endpoints.

Hi @MikeRalphson, I merged in the main branch it looks like that updated the filename. Please take a look and see if this is ready to merge.

For most people, email and url may be enough, but others - me, in today's case - need more info like jobTitle/position, phone, companyName, and companyUrl. This may be important if we write API Specification for another company.

Closing as I think we identified alternative avenues here to extending the spec. itself, but feel free to re-open! Thanks all.

@danieljacobs1 Free-form query parameters can be defined as a single parameter whose value is a dictionary and that uses style: form + explode: true (this is the default serialization style for query parameters). The parameter name can be arbitrary, it does not appear in the URL but may be used by code generators.

Both the tagNameNs and tagValueN's are user-supplied and arbitrary, but have to conform to be "identifier names" (no spaces, alphanumeric, must not start with a digit).

This condition can be defined in OAS 3.1 using patternProperties or propertyNames. Make sure to use the ^ and $ anchors in regexes because regexes are not implicitly anchored.

patternProperties example:

        - in: query
          name: tags  # Arbitrary name
          schema:
            type: object
            patternProperties:
              '^[A-Za-z][A-Za-z0-9]*$':
                type: string
              # or   '^[A-Za-z][A-Za-z0-9]*$': {}   if tag values can be other than strings
            additionalProperties: false
            example:
              tagName1: tagValue1
              tagName2: tagValue2

propertyNames example:

        - in: query
          name: tags  # Arbitrary name
          schema:
            type: object
            propertyNames:
              pattern: '^[A-Za-z][A-Za-z0-9]*$'
            additionalProperties:
              type: string
            # or   additionalProperties: true   if tag values can be other than strings
            example:
              tagName1: tagValue1
              tagName2: tagValue2

<br/>

OAS 3.0 also supports free-form query parameters, but does not have a way to limit their names.

        - in: query
          name: tags  # Arbitrary name
          schema:
            type: object
            additionalProperties:
              type: string
            # or   additionalProperties: true   if tag values can be other than strings
            example:
              tagName1: tagValue1
              tagName2: tagValue2

@ioggstream @hkosova woudl one of you like to take a go at that proposed PR?

“the spec is clear but Darrel said this in an issue a few years ago” or “this issue says X and that pull request says Y but the spec doesn’t say anything so which is right”. I’d like to try and get away from that.

I see either @Relequestual's proposed use of Architectural Decision Records over at JSON Schema, or the publishing of some "technical notes" as a good way to capture additional information about how the sausage was made, without bloating the spec itself.

I'm still struggling to see what an example would add above the stated support for the type that's already in the spec. But, as ever, PRs for discussion are always welcomed!

https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/EXTENSIONS.md does not say extensions can be placed under schema object.

https://github.com/OAI/OpenAPI-Specification/issues/241

Closing due to inactivity, and the age of v2.0 - but please feel free to reopen the issue if necessary.

We should consider where the bar is for contributions.

@RobDolinMS to gather data on PRs/contributions/comments looking for natural breaks

We're now discussing moving to more of an 'all-contributors' model, so closing this. Thanks all.

@tedepstein what changes to the proposals template did you have in mind?

@ioggstream sorry to come back to this after so long. I don't think this recommendation should be in the spec itself, as people should be free to quote (and indent etc) their OpenAPI documents in any way which is valid.

However, a PR to a (new) README.md file in the examples subdirectory would I think be a good idea so our own examples can aim for consistency.

What does "summary" give us that "description" does not? Perhaps "summary" could just be an alias for "description"?

#2408 was merged, closing this. Thanks all.

@aliraza1231 Here you go - meeting recording, complete with audio issues from about 0:24:0 in!

@MikeRalphson Can you please share the recording?

Most JSON Schema keywords are evaluated in isolation from each other, so the effect is cumulative. There is one keyword that asserts that 'request_id' and 'name' are required, and then later on another keyword asserts that 'recipient_id' is required. These are all considered separately, so the end result is that all three properties are required.

Hi all,

I am unclear on the behavior of allOf as it relates to required fields.

If I have one schema that includes another via allOf, how are required fields calculated?

Are they the union of the required fields of the two schemas? Are they JUST the required fields of the encapsulating schema? Are they something else?

For example, let's say I have the following schemas:

PaymentInitiationRecipientGetResponse:
      additionalProperties: true
      description: PaymentInitiationRecipientGetResponse defines the response schema for `/payment_initiation/recipient/get`
      allOf:
        - $ref: '#/components/schemas/PaymentInitiationRecipient'
        - type: object
          properties:
            request_id:
              $ref: '#/components/schemas/RequestID'
      required:
        - request_id
        - name

    PaymentInitiationRecipient:
      type: object
      additionalProperties: true
      description: PaymentInitiationRecipient defines a payment initiation recipient
      properties:
        recipient_id:
          type: string
          description: The ID of the recipient.
        name:
          type: string
          description: The name of the recipient.
      required:
        - recipient_id

In this example, what would be the required fields for PaymentInitiationRecipientGetResponse?

Just request_id and name? request_id and recipient_id? All three?

Thanks!

Thanks for the fast reply. I think I saw those earlier when I was searching around, but I wasn't sure.

It would be nice for confirmation, but I read https://github.com/OAI/OpenAPI-Specification/issues/1637 as if they have an endpoint that can produce the query parameter names and would it be possible to generate a UI dynamically from its response.

And https://github.com/OAI/OpenAPI-Specification/issues/1054 has the q as it's query parameter name and it feels a bit different.

For the case I'm asking about, I was imagining it might look like this:

openapi: 3.0.0
info:
  title: Service
  description: Endpoints
  version: 1.0.0
paths:
  /resources:
    get:
      parameters:
        - in: query
          name: state
          schema:
            type: string
            enum:
              - active
              - inactive
        - in: query
          metaVarName: tagName  # Mutually exclusive with 'name'
            schema:
              type: string
              regexp: [_a-zA-Z][_a-zA-Z0-9]*
          metaVarValue: tagValue
            schema:
              type: string
              regexp: [_a-zA-Z][_a-zA-Z0-9]*
      responses:
        '200':
          description: "All resources successfully obtained."

and it could generate a UI that allowed adding of arbitrary numbers of name/value pairs for tags.

It might be possible that one solution in openapi solves all three of the problems, but I'm not qualified to say.

I checked the issues for "dynamic parameter names" and came up with issues #1637 and #1054 which may be related? Can you let me know if you think there is some similarity and maybe we can coalesce the discussion here as you have expressed the issue in quite general terms.

maybe similar to #2089, PR to v3.1 in #2181

These are some changes I propose for discriminator that are minor, but would probably be considered breaking changes for 3.1.

• The discriminator keyword is an annotation. It doesn't affect validation, so it would not be ideal for it to cause validation failures. This changes the behavior of discriminator from being an error if the propertyName is not a required property in the object to being a no-op. This is also more consistent with other JSON Schema keywords that ignore things that don't apply to them, like properties only applying to instances that are objects.

• There is no way for implementations to tell the difference between a value that is intended to be a schema name and a value that is expected to be a URI. This changes mapping to allow only URIs and not schema names. Requiring all mappings to use URIs avoids the problem while not losing any functionality. The only consequence is that some mappings would be a little more verbose than they otherwise would have needed to be (example: #/components/schemas/Dog vs Dog).

• It doesn't make sense that the discriminator keyword would affect allOf. There's no point in discriminating if all schemas need to validate successfully. This removes mention of discriminator being used with allOf.

There are a couple bigger changes I'd like to make as well, but I'll leave those for separate PRs. I'd like to remove the "schema name" addressing concept, the mapping sub-keyword, and the parent discriminator feature. I'm going to open a couple issues to try to learn more about why these things exist before trying to remove them.

Note: This builds on #2618 which is not merged yet. I'm going to put this in "draft" status so it doesn't get merged until the other is merged, but please do review even though it's in draft. The first commit brings in the changes from the other PR, so it might be more effective to view just the last three commits that cove the actual changes.

@MikeRalphson ,

For the "special characters", in addition to the ones mentioned (?, # and %), please fine more examples below, where (, ), ', &, $ are used:

• /somePath/({param})
• /somePath/'{param1}'
• /somePath/{param1}&{param2}
• /somePath/{param1}${param2}

Best regards, Junjie

Yes, you need to define both in: path parameters to match the path templated items. Each in: path parameter must have required: true.

All of your other examples are valid.

I'm not sure what you mean by "special characters" though. ? and # cannot appear unescaped in a path key, % introduces a hex-coded character... were you thinking of these or some other characters?

Hi @MikeRalphson ,

thanks for your quick response.

For me, it seems the path /somePath/{param1}:{param2} is valid, if both parameter param1 and param2 are defined like:

        "parameters": [
          {
            "name": "param1",
            "in": "path",
            ...
          },
          {
            "name": "param2",
            "in": "path",
            ...
          }]

Could you please confirm?

Of course, similar question would be whether the path pattern below are valid:

• /somePath/{param1}-{param2}
• /somePath/{param1}={param2}
• /somePath/{param1}.{param2}
• other variants with special characters

Best reagards, Junjie

NOTE: This meeting is on Thursday at 9am - 10am PT

Zoom Meeting link: https://zoom.us/j/975841675. Dial-in passcode: 763054

In order to give some more visibility into the topics we cover in the TDC meetings here is the planned agenda for the next meeting. Hopefully this will allow people to plan to attend meetings for topics that they have an interest in. And for folks who cannot attend they can comment on this issue prior to the meeting. Feel free to suggest other potential agenda topics.

Please submit comments below for topics or proposals that you wish to present in the TDC meeting

The agenda backlog is currently maintained in issue #2482

/cc @OAI/tsc Please suggest items for inclusion

Dear OpenAPI specification experts,

I have a question regarding "path pattern" and "path parameters". The questionis whether this path pattern /somePath/{param1}:{param2} is valid.

Let's split the whole "path pattern" (/somePath/{param1}:{param2}) into multiple parts with /, so the original "path pattern" contains two parts:

1. /somePath
2. /{param1}:{param2}

Usually, every part contains one parameter like this example /cars/{carId}/drivers/{driverId}, where the {carId} and {driverId} are located in different parts. However, /{param1}:{param2} contains two parameters connected with a delimiter :.

This doc shows how style keyword is related to the delimiters, which does not tell that : is a valid delimiter.

As : is not mentioned as one of the supported delimiters, I would assume, my example is an invalid "path pattern". Could you please share your opinion and maybe point out some docs that I might miss.

Thank you very much in advance.

Best regards, Junjie

The only delimiters in a URL path are /, ?, & and #. The : character here doesn't function as a delimiter between path segments, nor, as it is not within a path parameter, does it act as part of the name of a parameter, or a delimiter for the purposes of the style keyword.

It is valid to have multiple in: path parameters within one URL path segment, but they may not 'cross' a path segment boundary, by containing an unescaped / character.

Please feel free to update this issue if you think the spec. or examples subdirectory should be updated to make this clearer.