Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Define "undefined" and "implementation-defined" (3.0.4) #3779

Merged
merged 2 commits into from
May 14, 2024
Merged

Define "undefined" and "implementation-defined" (3.0.4) #3779

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0110101
Define "undefined" and "implementation-defined" (3.0.4)
handrews May 3, 2024
d5fccc5
Review feedback from notEthan and ralfhandl
handrews May 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion versions/3.0.4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,19 @@ Some examples of possible media type definitions:
The HTTP Status Codes are used to indicate the status of the executed operation.
Status codes SHOULD be selected from the available status codes registered in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).

##### <a name="undefinedAndImplementationDefinedBehavior"></a>Undefined and Implementation-Defined Behavior

This specification deems certain situations to have either _undefined_ or _implementation-defined_ behavior.

Behavior described as _undefined_ is likely, at least in some circumstances, to contradict the specification.
handrews marked this conversation as resolved.
Show resolved Hide resolved
This description is used when detecting the contradiction is impossible or impractical.
Implementations MAY support undefined scenarios for historical reasons, including ambiguous text in prior versions of the specification.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is confusing to me, both my general understanding of how the term 'undefined behavior' is used and as defined here. In particular the description "likely to contradict the specification" - my understanding has been that undefined behavior, either explicitly stated as undefined or by a lack of explicit specification, has no expectation for the outcome of that behavior. That would mean there's nothing specified for behavior to contradict.

And the statement "Implementations MAY support undefined scenarios" seems at odds with that behavior being likely to contradict specification. Combining the two, to my interpretation, results in "Implementations MAY have behavior that probably contradicts the specification" or so.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having since been reading related issues that led to this (on structural interoperability), this is making more sense - it seems not the undefined behavior itself (treating references' resolved objects as one type when their structural placement indicates another type) that will contradict the spec, but the natural result of doing that in some circumstances (not detecting schema $ids, not having the correct base URI).

Wording that distinguishes the undefined-but-allowed behavior from the possible specified-disallowed result might be clearer, though I'm not sure quite how that would be worded.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @notEthan , I'll try to think about better wording.

Wording that distinguishes the undefined-but-allowed behavior from the possible specified-disallowed result might be clearer, though I'm not sure quite how that would be worded.

That's specifically what I'm trying to avoid doing. Or, rather, I have laid out the specifics before and had people refuse to read it for being too long or complicated. One person complained that the topics are so obscure that "only four or five people" could probably even understand it.

It's much easier to say "just don't do anything like this" than try to explain all of the different things that have to happen for it to not work.

Allowing for implementations that do it anyway is just a concession to reality: Many tools do not implement 3.1 Schema Object reference parsing correctly, and are likely to ignore a directive to rip out their incorrect support. And given that it was not obvious to most how the specifications require different behavior in 3.1, I hesitate to penalize them.

If they have something that works for them and their customers, the most likely outcome is that they keep doing it. But changing the wording in the spec makes it clear that if there is a problem, it's not a spec problem (aside from past lack of clarity). It's outside the spec, and we know it won't work sometimes.

It's a difficult situation to articulate, really.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe just "Behavior described as undefined is likely, at least in some circumstances, to result in outcomes that contradict the specification." or so. Undefined behavior itself isn't contradicting the spec but its result likely will - if that isn't too much indirection for one sentence.

I don't know, the wording that goes into spec authorship is hard (much respect for all you have put into various specs my work relies on).

This support might produce correct outcomes in many cases, but relying on it is NOT RECOMMENDED as there is no guarantee that it will work across all tools or with future specification versions, even if those versions are otherwise strictly compatible with this one.

Behavior described as _implementation-defined_ allows implementations to choose which of several different-but-compliant approaches to a requirement to implement.
This documents ambiguous requirements that API description authors are RECOMMENDED to avoid in order to maximize interoperability.
Unlike undefined behavior, it is safe to rely on implementation-defined behavior if _and only if_ it can be guaranteed that all relevant tools support the same behavior.
ralfhandl marked this conversation as resolved.
Show resolved Hide resolved

## Specification

### Versions
Expand Down Expand Up @@ -147,7 +160,7 @@ Models are defined using the [Schema Object](#schemaObject), which is an extende
<a name="dataTypeFormat"></a>Primitives have an optional modifier property: `format`.
OAS uses several known formats to define in fine detail the data type being used.
However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value.
Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification.
Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though they are not defined by this specification.
Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified.

The formats defined by the OAS are:
Expand Down