[3.0.0] Introduce `Info Item Object`

[magicmatatjahu]

I noticed that we have some inconsistencies in describing the metadata for the 4 main elements of the AsyncAPI specification: servers, channels, operations, and messages (we can also treat schemas as 5 element). In Server Object we can only define description, in the Channel Object also only description, in the Operation Object we can define description, operationId , summary, tags and externalDocs, in the Message Object these same fields (except operationId) and also name and messageId. I wonder if we should standardise the item description with a single object type (I propose the name Info Item Object) that would have the following shape:

Field Name	Type	Description
name	string	A machine-friendly name for the item.
title	string	A human-friendly title for the item.
summary	string	A short summary of what the item is about.
description	string	A verbose explanation of the item. CommonMark syntax can be used for rich text representation.
tags	Tags Object	A list of tags for API documentation control. Tags can be used for logical grouping of items.
externalDocs	External Documentation Object	Additional external documentation for described item.

Some example

# server
info:
  title: Kafka server
protocol: kafka
protocolVersion: ...

# message
info:
  name: UserSignup
  title: User signup
  summary: Action to sign a user up.
  description: ...
  tags:
    - name: user
    - name: signup
    - name: register
payload:
  ...

Benefits:

• A single info object for item will allow for easier familiarization with AsyncAPI. Currently each of the above mentioned objects in AsyncAPI has a different set of metadata, and I wonder why we have such a big discrepancy. As html-template and markdown-template are the only ones (probably) using whole metadata, it's very strange for me and every time I had to look which metadata I can render.
• Easier support in tooling. One object shape can be reused in several places, which makes the implementation of e.g. parserJS simpler and easier to understand (it is mainly about the number of methods in classes).

NOTE: I am also considering adding a contact field to the new object to describe the main "maintainers" of the objects. This would be used mainly to indicate who is responsible for a given object in an organization/company, but I don't know if that makes sense. What do you think?

NOTE: Should we also add metadata field as Łukasz suggested in https://github.com/asyncapi/spec/issues/654#issuecomment-1088414968 comment?

[murari-goswami]

I like the idea here. This standardization will give more structure to the metadata for the core objects.

[magicmatatjahu]

@murari-goswami Thanks! We don't know if it will come in this form or rather be a composite, but we want to unify the metadata for core objects :)

[smoya]

I like the idea of having a standard object with all this info. Except for the ID. I'm going to drop why I think id should be considered as part of each object and not under info field:

• id doesn't give information about the object but the identifier.
• The rest of the fields could be reused from a common shared object (i.e. common.yaml) and will make sense. However, Id's are unique across the application that defines it.
• Additionally, from a point of view of the domain, those Ids will relate to the ID of the Entities. However, the rest of fields are right directly attributes of any value object (including but not limited to entities).

[magicmatatjahu]

@smoya id is removed -> https://github.com/asyncapi/spec/pull/796 no worries :)

[smoya]

@smoya id is removed -> #796 no worries :)

Then please update the description of this issue which still mentions it.

[jessemenning]

Would this be an appropriate place to have version to represent the semantic version? As we move into having reusable components, and presumably multiple different versions of those reusable objects, it's helpful to version at a more granular level

[magicmatatjahu]

@jessemenning I don't think we should combine such a thing in this issue/proposal. A better option would be to create a separate proposal, because it is quite a "big" contribution to the new spec, than the consolidation of the existing fields :)

[magicmatatjahu]

Handled by https://github.com/asyncapi/parser-js/pull/677 but not every fields that I described in the issue's description - we decided to not add name.