v3.2: Should the `value` and `externalValue` fields be deprecated?

[handrews]

With PR #4647, these fields become obsolete and retained purely for compatibility. They have numerous ambiguities and variable implementations. They also MUST NOT be used alongside the newly added fields.

Should we deprecate them, given that their replacements are right there in the Example Object with them and migration would be relatively low-effort? In most cases, just move to the correct new field, although in some cases the serialization might need to be adjusted as serialization/encoding has been interpreted in several ways.

Note that this issue does NOT concern the singular example fields which will be covered in a separate issue.

[karenetheridge]

I think you mean "value" and "externalValue"?

Where is our deprecation policy? It doesn't seem to be linked from the spec.

[handrews]

I think you mean "value" and "externalValue"?

🤦 fixed, thanks.

Where is our deprecation policy? It doesn't seem to be linked from the spec.

It's only in 3.2: https://github.com/OAI/OpenAPI-Specification/blob/v3.2-dev/src/oas.md#deprecation

[LasneF]

i understand the purpose & value of those 2 fields dataValue vs serializedValue

but i would rather add a single one, keeping current value , and clearly document that it is either dataValue or serialiazedValue to pickup one we could use several aspect the common understanding ( to me is dataValue ) , practices of linter , practices of code generator

by doing that you make the public see as an addition and not yet another change that i need to adapt

what i feell from the community (at least i am leading the French api community ) is that OAS is main issue is the Swagger2 move to OAS 3.0 and OAS 3.1 impatibility . Key point is adoption

Deprecation is seen as change with a negative perseption, vs adding a field and a precision is more seen as a positive evolution

also i would say it is not the concern of most of the API designer, but only to a few, that said we need to address the concern but with in mind to not impact the vast majority

[handrews]

@LasneF we can't enforce the original meaning of the fields without de-facto "breaking" most existing implementations. Nor can we change the meaning of those fields because that would actually be a breaking change not allowed by our compatibility rules, and most likely there are some implementations that implemented it correctly and don't deserve to be broken in that way.

@mikekistler @lornajane (since you were both in the most recent all as well) @OAI/tsc can we get an official decision on whether it is possible to salvage the existing fields as an alternative? In issue #4664 I explain how the existing fields inside and outside of the Schema Object were intended to work together to do what we're now proposing to do with the new dataValue, serializedValue and their external* analogues. We could just (again) clarify the intent and tell the tools that they need to comply. It is unusual for us to just give up on a requirement like this, but the reality of this requirement is particularly murky. But I'd like to get a decision here and not keep going back and forth on it.

[mikekistler]

I am reluctant to deprecate fields that I think currently provide value even though they are not used as intended by the spec authors. My preference would be to allow them to continue to be used in the way that nearly all tooling vendors understand them, with the caveat that this meaning was not intended and thus cannot be relied on.

[LasneF]

for the actual field : we have in fact 4 choices

1. actual description followed is only by a few number and will break the majority
2. change de description, follow by majority and break few number
3. make it deprecated , that is some how a soft breaking change for every one (few number + majority)
4. leave it as it is , so wrongly used but as still first candidate as @mikekistler suggest

[handrews]

@hudlow and I have been discussing, and we are likely to leave externalValue as-is. For value, my current thought is to describe when it is safe to use (e.g application/json and +json targets, by far the most common use case, as well as certain string-to-string-without-escapes targets like text/plain) and deprecated only for ambiguous serialization targets. Which is itself a bit ambiguous but... that's kind-of the point?

[lornajane]

Deprecated in situations where the old field names would be confusing, the spec is updated.