Best practice in APIs always includes the advice to include examples. In older versions of OpenAPI (3.1 and earlier), that was simple for JSON data but a little bit unclear for other formats whether to describe the data structure or to show the actual data that would be transferred. Help is at hand in OpenAPI 3.2 where the new fields dataValue and serializedValue mean you can do whichever makes most sense - or both!
The Example Object in OpenAPI previously had a value field, but its usage was inconsistent because it just wasn't obvious what was supposed to go in this field. For an API that uses JSON, either the structure to validate or the actual data to send look similar enough that it's pretty simple to know what's what. But for APIs that do anything that is NOT that, things got a lot messier and people did the best they could with the fields they had.
OpenAPI 3.2 added two new fields to the Example Object:
- dataValue holds the structure of the data
- serializedValue holds the actual data in the format it is transmitted
You can use either or both fields.
Examples Example
I've picked an example that's a simple example of something I ran into recently, because it used application/x-www-form-urlencoded and that makes the difference between the two examples easier to see. The API accepts form post data, so the OpenAPI looks like this:
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
customer: {type: string}
items:
type: array
items: {type: string}
giftWrap: {type: boolean}
examples:
basicOrder:
summary: A simple order with two line items and gift wrap
dataValue:
customer: jane
items: [mug, sticker-pack]
giftWrap: true
serializedValue: "customer=jane&items=mug&items=sticker-pack&giftWrap=true"
(the interesting bit is in the end section!)
Seeing it like this shows why both example fields are needed.
externalValue is still available
There was also always an externalValue field which was very useful for any data formats that were either very large, or not something you want dumped in the middle of an API description! That field remains, but the description was clarified in the 3.2 release to make it clearer that the contents of the external value file should be the serialized example data - and that you should use either serializedValue or externalValue since they serve the same purpose but there are good reasons that an external file might be more convenient.
Upgrade your examples from OpenAPI 3.1 to 3.2+
The ambiguity around what the value field was actually intended to have in it means that there is no clear mapping to either dataValue or serializedValue in the newer OpenAPI versions. The old value field is still there and still works, your tools will continue to treat it the way they did in older OpenAPI versions, but there was not necessarily consistency between tools. This field is now marked deprecated.
If your API description consistently used either data structure or on-the-wire data, go ahead and replace value everywhere when you upgrade to OpenAPI 3.2 or later to make it clear which one you were thinking of! Otherwise, it's worth spending the time to update the fields to match their contents - and you can add the other option as well for any examples that need it.