I think we need first entry in not yet existing AsyncAPI glossary

[derberg]

I continuously find myself struggling when thinking about docs and how to write about AsyncAPI.
there are different forms that we use here and there. I think we will never be able just to have one (I might be wrong) but we need some official guidelines, to make review/writing easier, and have a reference guideline when taking care of consistency in docs.

different ways we talk about and could talk about AsyncAPI:

• AsyncAPI, AsyncAPI specification and shorter AsyncAPI spec - this one is easy, as it is about specification itself, and I think all versions are ok 🤷🏼

but what when we talk about the AsyncAPI that was created by the user, according to AsyncAPI specification?

different options:

• AsyncAPI file - makes sense, but it is not always a file 😄
• AsyncAPI specification file - I think even more confusing than above
• AsyncAPI instance - yeah, tbh I never used it, it makes sense, but instance is rather used when you talk about instance of a service, or something like that
• AsyncAPI definition - I like it
• AsyncAPI contract - makes sense, but do people think about AsyncAPI as a contract? I think we all wish they have, but it is not a case
• AsyncAPI document - I think it is the most widely used. Even in existing AsyncAPI docs definitely. But I know some folks do not like this, as this is kinda suggesting AsyncAPI is for documentation only (I personally do not agree with such statement)

Let the academic dispute begin 😆
Again, I do not think there is one perfect name that we can use. More important is to pick something, and stick to it and be consistent, even if we end up with choosing AsyncAPI declaration 😆

[fmvilas]

Yeah, I like the AsyncAPI document one. It's not about documentation, it's a document that can be used to do other stuff. AsyncAPI definition is also a good one. I often use the two interchangeably.

[kevinswiber]

I use document and definition with OpenAPI, as well. I do make a slight distinction where definition often refers to the semantics of the specification and document refers to the YAML or JSON structure itself. But it's such a fine point, they're often used interchangeably.

I sometimes don't know why I do the things I do, but in thinking about it... "API definition" feels semantically correct whereas the YAML spec itself uses document to refer to a single structure. Note: This should be separate from file, as a file may contain multiple YAML documents or API definitions.

[Florence-Njeri]

I think of it as a JSON/YAML file so I always refer to it as an AsyncAPI file but I think I like the AsyncAPI definition better.

[derberg]

yeah, I get into this "trap" all the time. Because in the majority of cases, technically, it is actually a file 😅

[Julian]

In case it's helpful, I'll crosslink JSON Schema's "TODO list" for our own glossary -- it's here: https://github.com/json-schema-org/community/issues/199 and the live version of what's done so far is here: https://json-schema.org/learn/glossary.html

If I can throw in a random note, I think it's super useful if whatever is used for the glossary is usable in downstream docs -- in other words, if I write an AsyncAPI implementation and I use the term "AsyncAPI instance", how easy is it for me to interlink to the upstream glossary's definition of that term.

@philsturgeon also just linked https://github.com/openapi-contrib/glossary in a call, which is one OpenAPI has.

[derberg]

I went through openapi glossary and could not find an answer if I should say OpenAPI document or Swagger 😄

and regarding interlinking to upstream. You basically mean that would be nice if we publish glossary on a website, in a clear structure, maintain it in the same way we maintain docs and other stuff so others can easily link/refer to given definition. Right?

[Julian]

and regarding interlinking to upstream. You basically mean that would be nice if we publish glossary on a website, in a clear structure, maintain it in the same way we maintain docs and other stuff so others can easily link/refer to given definition. Right?

Yeah exactly!

[philsturgeon]

The answer has been “OpenAPI” since 2016 so I didn’t bother beating that very dead horse in this glossary.

[derberg]

@philsturgeon sorry for misunderstanding, I should have put my Swagger jokes aside

I went through openapi glossary and could not find an answer if I should say OpenAPI document or Swagger 😄

I meant that there is no entry that would say how to call documents/files that are created by following OpenAPI spec. Should I say "I just wrote my first OpenAPI file", or "hey folks, task for that week is to create OpenAPI document for our API". I hope that makes sense? sorry again.

[derberg]

We did not get to many answers on Twitter: https://twitter.com/AsyncAPISpec/status/1575121084420169728

In a few weeks, we need to try again, with a different message and probably different options. I guess we should explore Slack too, I mean do a survey in slack