[Clarity] Differences OpenAPI specification, OpenAPI document and OpenAPI definition

[patricekrakow]

I have just realized that I was often wrongly using expressions like:

• my OpenAPI specification
• the OpenAPI specification of my API
• ...

I got it while reading the definition of 'OpenAPI Document':

A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.

I think that the sentence An OpenAPI definition uses and conforms to the OpenAPI Specification. makes it clear that OpenAPI Specification should be reserved to the specification of OpenAPI as language to define APIs, and not used to designate a particular definition of a specific API.

So, it looks like I should better use expressions like:

• my OpenAPI definition
• the OpenAPI definition of my API
• ...

However, I have then realized that 'OpenAPI definition' is not defined explicitly within OpenAPI Specification. Within the definition of 'OpenAPI Document', I found the jump from 'document' (in the 1st sentence) to 'OpenAPI definition' (in the 2nd sentence) rather uncomfortable.

Would it make sense to define explicitly 'OpenAPI Definition'? In addition or in replacement of 'OpenAPI Document'?

[MikeRalphson]

In progress as part of #1781

[BelfordZ]

I fixed it for open-rpc as well. I've found it hard to keep things named consistently. Many call the document a schema. =(

anyways, proof: https://spec.open-rpc.org/#openrpc-document

[MikeRalphson]

@philsturgeon is taking a stab at a glossary here although there he prefers (API) description or (API) description document over plain "document" which was all we were able to get over the line in OAS. In my view, especially if your API is in some way constructed from an OAS document, then "definition" is fine too.

[philsturgeon]

In my research I found a bunch of people considering the "API definition" to be the actual API code which was built.

The API document was vague, could be documentation or could be an instance of JSON.

We settled on API Description which is comprised of a Document written in a certain Format, but because document and format by theirselves are vague, when trying to be clear we say "API Description Document" and an "API Description Format"

"API description" or "API document" are generally fine terms when describing this when you know they are shorthand for those longer more clear things.

I don't much like trying to figure this all out but having a consistent way of referring to the same things is generally less confusing for everyone.

[BelfordZ]

@philsturgeon we've taken a hard stance that the specification will only ever refer to documents written in JSON. If a user wants to write their document in YAML, thats okay, but they will have to convert the yaml to JSON before it becomes an OpenRPC document =P.

Mind you, this is made easier by the fact that we are 100% tied to JSON-RPC, so JSON is already a strong assumption.

I think it's something where its hard to pick one thats clearly better than any other option, but fwiw I went with Document because people already use the term "Service Description" as a generic term for the concept of having api descriptions.

Definitions went out the door because its a pretty heavily used key in json schema, and since we are looking for reasons to pick 1 synonym over another...

@philsturgeon since convincing everyone that "for the sake of the spec, you should not talk about yml anymore" is a really hard sell. Might I suggest "OpenAPI Document", "JSON formatted OpenAPI Document", "XML formatted OpenAPI Document", .... etc

[philsturgeon]

I do not understand the relevance of JSON vs YAML in the context of this conversation, Why does that matter.

If you like the term "API specification" for your document it doesnt matter if its JSON or YAML you can call it that.

The one consistent bit of terminology I've managed to get Postman, Stoplight, Optic, and others to agree on is that the document you write is the API description document, and OpenAPI is an API description format. But none of us care if its JSON or YAML, and I don't think I want to get into that. Not sure there is a benefit in opening that can of opinonworms.

[BelfordZ]

@philsturgeon My bad, I misread entirely and should probably just go to sleep.

The one consistent...

Thats great. Thanks for clarifying. I too will do the same.

[philsturgeon]

Cool!