OAI
v3.2: Decide on names of new Example Object fields
PR #4647 adds four new fields to the Example Object. There seems to be consensus that we should add the fields once that PR is out of draft, but there is less consensus on the names.
In this issue, "JSON/YAML" refers to JSON (as specified by the RFC) and the subset of YAML that we allow for OAD authoring. This subset is intended to be essentially equivalent to JSON, as all OAD keys and values MUST be possible to write in JSON.
The names in the PR are:
-
dataValue: An inline example value of the data structure that is validated by a Schema Object, possibly trivially if the data is raw binary as that is outside of JSON Schema's standard data model -
externalDataValue: LikedataValuebut for values not possible to inline in JSON/YAML, such as a raw binary image or video -
serializedValue: An inline example of the fully serialized value, which MUST be a string -
externalSerializedValue: LikeserializedValuebut for values not possible to inline as a JSON/YAML string.
@mikekistler has questioned "data" and brought up that JSON Schema uses "instance." My feeling is that "instance" is too jargon-y, and the data is not necessarily a proper JSON Schema instance when binary data is involved, but I could be convinced to go with it if I'm in the minority here.
BTW I do not care what the names are. Just lmk when there's consensus and I'm happy to write a PR to update the text with the final names. I have just separated this out (and made it a 3.2 release blocker) so that PRs #4647 and #4648 do not get held up on naming debates.
I can't usefully contribute to a naming discussion separate from a semantics discussion unless the semantics are clear to me (and finalized), which they are not. I have commented with my objections, here: https://github.com/OAI/OpenAPI-Specification/pull/4671#discussion_r2141172449.
Regarding "DataValue", I would prefer a more descriptive name since "data" is very generic. My first thought was "JsonValue", since we want this to match the JSON Schema.
jsonValue could suggest that the value is json-encoded, which it isn't.
@hudlow and I have been discussing and are leaning towards keeping externalValue and not adding any further external* fields. I think serializedValue is pretty solid now.
I think @karenetheridge 's concern about jsonValue is a good reason to stick with dataValue. I have also been finding "data vs serialized" useful in writing some other guidance, as the OAS is largely about mapping back and forth between a set of in-memory data and a serialized HTTP message, which is never all-JSON. The fact that our data uses the JSON data model is probably a bit too obscure to hang a name on. Also, we have enough confusion over the divergence between the JSON data model, JSON Schema data model, and JSON Schema's type and format keywords. Let's go with "data" as it works no matter how you think of those.
(This is my current thought, and is not meant to indicate that this is resolved or has reached consensus).
