You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Open Community (TDC) Meeting, Thursday 05 June 2025 #4642
Weekly meetings happen on Thursdays at 9am - 10am Pacific
This agenda gives visibility into discussion topics for the weekly Technical Developer Community (TDC) meetings. Sharing agenda items in advance allows people to plan to attend meetings where they have an interest in specific topics.
Whether attending or not, anyone can comment on this issue prior to the meeting to suggest topics or to add comments on planned topics or proposals.
Improvements to Examples to support the improvements to data modeling and serialization (streaming, query strings, multipart, and XML), all of which involve complex relationships between data values and serialization formats:
v3.??? Data vs Serialized Examples in Example Objects #4647 (PR for basic dataValue, externalDataValue, serializedValue, externalSerializedValue Example Object fields, including many updates to examples in the spec that show the value of these fields even for us)
v3.2: Allow Parameter/Header "examples" field with "content" field #4648 (add-on PR allowing Example Objects with the content field in the Parameter and Header Objects, where it is currently forbidden but is needed for the new in: "querystring" format and because we now recommend against using schema and style for all but the most trivial headers, as shown by updated examples in the spec)
Please exclude the following topics until we have decided whether to add the new fields
Whether to deprecate the various example (singular) fields
Whether to deprecate value and externalValue
Whether to provide new / different guidance for value, dataValue, and singular example (which @mikekistler wants to do whether we add new fields or not)
Whether to change the requirement that non-schema examples override schema examples, which is not at all new (@mikekistler has suggested changing this, and I'm sympathetic, but it is orthogonal to whether we add new fields)
Whether to use more JSON Schema-esque terminology ("instance" rather than "data"), as this is easily tweaked if we're adding new fields, and irrelevant if we are not
@hudlow regarding your questions: Any media type, or any variation of a media type, that cannot be represented as desired in an embedded string can be shown as an external file. You can do whatever you want in the external file. How the character set of a JSON document is handled is a JSON RFC concern, not an OpenAPI concern. We don't need to try to figure out how to shove things that aren't natural JSON/YAML-as-serialized-for-OADs into the inline fields, that is what the external fields are for.
Activity
handrews commentedon May 29, 2025
Improvements to Examples to support the improvements to data modeling and serialization (streaming, query strings, multipart, and XML), all of which involve complex relationships between data values and serialization formats:
dataValue,externalDataValue,serializedValue,externalSerializedValueExample Object fields, including many updates to examples in the spec that show the value of these fields even for us)contentfield in the Parameter and Header Objects, where it is currently forbidden but is needed for the newin: "querystring"format and because we now recommend against usingschemaandstylefor all but the most trivial headers, as shown by updated examples in the spec)example(singular) fieldsvalueandexternalValuevalue,dataValue, and singularexample(which @mikekistler wants to do whether we add new fields or not)handrews commentedon Jun 5, 2025
@hudlow regarding your questions: Any media type, or any variation of a media type, that cannot be represented as desired in an embedded string can be shown as an external file. You can do whatever you want in the external file. How the character set of a JSON document is handled is a JSON RFC concern, not an OpenAPI concern. We don't need to try to figure out how to shove things that aren't natural JSON/YAML-as-serialized-for-OADs into the inline fields, that is what the external fields are for.