Correct statement that media type */* is equivalent to application/octet-stream

[mixels]

The OAS 3 documentation states:

application/octet-stream:
# any media type is accepted, functionally equivalent to */*

I believe the intent here it to state that the type application/* is functionally equivalent to application/octet-stream. Perhaps not. At any rate, */*, if * is a wildcard, would not thought to be equivalent to application/octet-stream in the common sense, as the wildcard for type (remember, media type is {type} + '/' + {subtype}) should be taken to allow text, image, multipart, message, and so on in addition to application. If my spec says my service endpoint accepts */*, I don't want the callers to infer from OAS documentation that they are required to send some subtype of application.

It could also be that I'm missing something that came out of internal discussion. Can you please explain this decision so my teams can better understand how to interact with the spec or otherwise consider my request to change the specification and existing documentation?

[MikeRalphson]

Note that the wording you quote is within a comment in an example, and is not a normative part of the specification itself.

The section originally looked like this when first added, and in the subsequent movement of the content property, the comment was also moved.

This appears to alter the intended meaning of the (perhaps not ideally worded) comment.

I take it to mean that any media type is acceptable in the OAS document (i.e. anything matching '*/*'), not that any media type is accepted by the described API, but I may be wrong.

I'm sure we can find better wording (or remove the comment if it is just misleading). Thanks for pointing it out.

[mixels]

Ah, I see! I do believe the comment is currently misleading. I should note, too, that the Swagger website is currently using the comment to inform a statement on this page (in the "requestBody, content and Media Types" section) and possibly in other places.

Thank you! I will share this information with my teams.

I do believe the spec document should describe what is accepted by the API. That's essentially the purpose of the spec, right? To define a contract the client can consume to understand how to interact with the service? In this sense, I don't believe */* is in any way equivalent to application/octet-stream, so I would advise simply removing the comment (and asking the people who maintain official public documentation to update that documentation, if that has anything at all to do with your organization). Perhaps the comment intends that application/octet-stream is an example of a media type that matches */*; if the intent is to give examples, I'd give more than one and avoid describing the examples as equivalent to the match pattern. Or just remove the comment... :)

[mixels]

Also reviewing the old version you linked, it appears to make the same statement except in reverse (that application/octet-stream is functionally equivalent to */* instead of that */* is functionally equivalent to application/octet-stream). I don't view either statement as true. The media type application/octet-stream describes application-purposed binary content. That is, it's a specific subtype of a specific type. */* matches any media type.

[darrelmiller]

We shall remove the comment "# any media type is accepted, functionally equivalent to */*" as it does not appear to add any value.

[mixels]

Great, thank you! I appreciate the quick response!

[MikeRalphson]

Will be included in v3.0.3. Thanks again for pointing this out.