Prefer description when referring to an OAS document
#1247
Conversation
Usage of description and definition to refer to an OAS document was mixed. This makes it more consistent, and prefers "description" of the service, since as a possible-truth it is more broad than "definition," which suggests an actual truth. (note: definition does still occur in the doc, but those refer to specific parts of the document rather than the document as a whole)
|
I like using "API description" to consistently refer to OpenAPI-format descriptions of APIs. This seems clearer than calling them "specifications" which gets easily confused with "The" OpenAPI Specification. |
DavidBiesack
left a comment
DavidBiesack
left a comment
There was a problem hiding this comment.
I prefer the term definition over the term description. This is a document that conforms to a specification, and description feels like the wrong term to me -- i.e. prose that I would publish on a web site is a description of an API. Definition has a more precise, well, definition. Consider how the API provider would answer the API consumer's questions: "Where is the description of this API?" vs. "Where is the definition of this API"? The first would be a web page, the second an openapi.json document.
|
👍 for @DavidBiesack's comment. API description seems closest to API documentation as described by this blog post which reserves API definition for machine-readable artefacts. The OpenAPI document should be the objective truth of the definition of the API as far as the OpenAPI specification allows it to be defined. |
|
@DavidBiesack and @MikeRalphson, definition to me means the specification is truth. That might be the case if the spec is code or is generated from code. But when a spec is written by hand, it describes a service—often poorly, such as when a 3rd party tries to describe an existing service (such as the apis.guru collection, at least AFAICT). For me, a definition is a subset of description, truth vs possible truth. I'd love if all specs were, in fact, definitions, but in reality, we must appreciate that there will be many specs that are fallible. In that case, I strongly prefer the looser term. |
|
Thinking about this some more… descriptions may be inaccurate whereas definitions cannot be. Furthermore, an API spec often contains metadata for people, such as |
|
@earth2marsh I do believe that dictionaries attempt to provide definitions that are accurate. It doesn't mean that all dictionaries will have exactly the same definition. An OpenAPI document is an attempt to be precise about the shape of an API. It does not have to be an exhaustive description but what is defined should be correct. But as we all know, reality sucks and sometimes mistakes are made. I don't think that justifies watering down the OpenAPI document to be a just a description. Within the OpenAPI document there are descriptions of various elements of the API in human readable language. I would prefer to be able to distinguish between the OpenAPI document that is machine readable and the descriptions of the API that are only human readable. I was almost swayed by the IDL comparison but Wikipedia page says "definition" is cool too :-)
|
|
I'm actually more worried about watering down "definition". Changing a parameter description doesn't change the service definition, but it does change the description of the service. Plus, when the spec defines the service, how do you distinguish that from a spec written out of band that attempts to describe the same service? One of those is a definition, the other is an attempt to define, like saying hopping is like jumping. |
@earth2marsh You're missing the case where the code was generated from the definition/description (not 'spec', never that 😄). But just for clarity, around 95% of the APIs.guru collection is direct from the API owners, not third-party 'descriptions', so allowing for conversion errors in some cases, they are the published definitions/contracts of those APIs in OpenAPI terms. |
|
@MikeRalphson that's what I was trying to get at by the case of the D "being code." Funny, I have no qualms about the concept of the D being the contract—it is how the provider formally declares the capabilities of the service, and some contracts are poorly written. For me, the service is defined by the code behind it. If that code maps onto a D 1:1, then it is a definition. If it doesn't map closely, it's probably because it was written out of band, making it a description. If I were to generate tests from a definition, I would expect them to pass when run. If they were generated from a description, I'd expect a higher rate of failure because the service is not defined by the document. To put it another way, |
|
#TDC: When people create an OpenAPI document, do we call that a "definition" or a "description" ? |
|
I also think definition is better – it makes it clear that the OpenAPI document is what defines the API (even if the implementation doesn't actually conform to it), not the implementation (which is then just described). |
|
I'm happy with any of these. "document" is also a good choice since Paŭlo
just used it and it's consistent with the usage of "document" in the JSON
Schema specification.
http://json-schema.org/latest/json-schema-core.html
…On Fri, Jul 7, 2017 at 12:28 PM Paŭlo Ebermann ***@***.***> wrote:
I also think definition is better – it makes it clear that the OpenAPI
document is what defines the API (even if the implementation doesn't
actually conform to it), not the implementation (which is then just
described).
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#1247 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAABlYgY6mgT1aSxSKas9t2mwUmFJqoiks5sLlylgaJpZM4OLAOI>
.
|
|
@timburks I'm warming to that suggestion of @DavidBiesack, @MikeRalphson, @timburks, and @ePaul, how do you feel about this latest version? |
|
I just had a long conversation with someone about OpenAPI and couldn't stop myself from talking about API descriptions. Sigh. |
versions/3.0.md
Outdated
| An OpenAPI description MAY be made up of a single document. | ||
| However, parts of the description MAY be split into separate documents, at the discretion of the user. | ||
| An OpenAPI document MAY be made up of a single document. | ||
| However, parts of the document MAY be split into separate files, at the discretion of the user. |
There was a problem hiding this comment.
Ditto here.
An OpenAPI document MAY be made up of a single document, or split into separate documents, at the discretion of the user.
Re-using 'document' seems to be getting messy.
There was a problem hiding this comment.
+1. My use would be that a "document" is a thing which is a continuous sequence of bytes (e.g. as a file in a file system, a string in a database, or available via some URL at a web server). An API definition consists of one or multiple such documents.
There was a problem hiding this comment.
would files lessen the confusion here?
There was a problem hiding this comment.
files is again a bit of a backwards step as we had worked to eradicate it (except in terms of file uploads). Is resource/resources too woolly?
There was a problem hiding this comment.
Too woolly! Resource all the things. :)
There was a problem hiding this comment.
Better in latest commit?
versions/3.0.md
Outdated
| ##### <a name="oasDescription"></a>OpenAPI Description | ||
| A document or set of documents that describe an API. An OpenAPI description uses and conforms to the OpenAPI Specification. | ||
| ##### <a name="oasDocument"></a>OpenAPI Document | ||
| A document or set of files that document an API. An OpenAPI document uses and conforms to the OpenAPI Specification. |
There was a problem hiding this comment.
We seem to have gone backwards slightly here, where we removes 'files' before.
A document or set of documents that
or
A document (or set of documents) that
There was a problem hiding this comment.
good catch, missed that. will fix
DavidBiesack
left a comment
DavidBiesack
left a comment
There was a problem hiding this comment.
I still feel 'definition' is the most appropriate term. However, I will certainly accept what the majority agree to
versions/3.0.md
Outdated
| - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](http://yaml.org/spec/1.2/spec.html#id2802346). | ||
|
|
||
| **Note:** While APIs are described by OpenAPI documents in YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. | ||
| **Note:** While APIs may be described by OpenAPI documents in YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. |
There was a problem hiding this comment.
I suggest "are defined by OpenAPI documents" By using "may be", this opens up the misinterpretation that YAML/JSON are not the only formats. (I'd like to removed 'described by' here. However, we can't change the verb to 'documented' without it sounding awkward, so I suggest 'defined' instead.)
There was a problem hiding this comment.
I can address may be by adding either before YAML. I couldn't stomach defined here, since the code defines the service IMO (I recognize that others may not share that opinion).
versions/3.0.md
Outdated
| The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly documented, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. | ||
|
|
||
| An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools and many other use cases. | ||
| An OpenAPI document can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools and many other use cases. |
There was a problem hiding this comment.
I still feel that 'define' is the best term between the three. "document" is valid but (like description) has other meanings/associations which I think are distracting. In particular, phrases like "When properly documented" feel too much like "When properly described" which to me infers non-nominal prose description rather than an a source definition. This sentence itself highlights the problem: "An OpenAPI document can then be used by documentation generation tools to display the API" -- i.e. use the document to generate the documentation, when use the definition to generate the documentation feels more correct. (I do see how a UI or web page rendering is just another representation of the OpenAPI document.)
"document" is better that "description" but "definition" will yield the least amount of confusion.
There was a problem hiding this comment.
We do need a way to refer to these documents. The differences between definition and description are huge, at least in my opinion. Using document allows us to let a common parlance evolve, but it still provides a way to talk about these artifacts, sidestepping the implications of connotation.
… but if this isn't a satisfying compromise, we'll have to fall back.
There was a problem hiding this comment.
Latest commit hopefully resolves
| Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. | ||
| `null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution). | ||
| Models are described using the [Schema Object](#schemaObject) which is an extended subset of JSON Schema Specification Wright Draft 00. | ||
| Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00. |
There was a problem hiding this comment.
Did you mean to change this to documented? I think defined works well here 😄
There was a problem hiding this comment.
I also thought defined worked well here, since I was trying to use document to (mostly) refer to the actual document itself and to not completely purge description and definition. Interestingly, JSON Schema's landing page seems to prefer describe in these situation.
|
I feel I need to change my position on this. Consider these two images:
The more I talk to people about specifications like OpenAPI the more I find that they are commonly referred to as API Description Languages. See Wikipedia https://en.wikipedia.org/wiki/Overview_of_RESTful_API_Description_Languages I think trying to get traction behind a term other than "an API Description" is likely going to be hard. |
|
@darrelmiller's point is quite telling. Having looked at it again ccf4651 with 'description' is preferable to me to the latest commit, as it doesn't suffer from overloading 'document' and doesn't re-introduce 'files'. |
|
Ignoring which search engine @darrelmiller used (ahem), I can play that game too:
(using a non-signed-in incognito search) Now, while the OpenAPI may be a "description language", I still find that an instance of it is a Regardless of what we pick, people are going to use whatever they want, be it definition, description, document, or, sorry to say, most likely, spec. |
|
@earth2marsh ping |
This attempts to use `document` in its various forms when discussing the artifact (replaces `file` in the most part), though I tried to avoid mixing the file-like instances with the API documentation ones. Some instances have been changed to use `define` (or similar forms), though based on the comments suggesting that both `definition` and `description` are used in common parlance, `description` has not been fully expunged—hopefully this is a reasonable middle ground, but if upon review there is strong support for that, I'll re-submit.
Usage of description and definition to refer to an OAS document was mixed. This makes it more consistent, and prefers "description" of the service, since as a possible-truth it is more broad than "definition," which suggests an actual truth. (note: definition does still occur in the doc, but those refer to specific parts of the document rather than the document as a whole)