spec chore: add metadata object, server trait and channel trait

title: "add metadata object, server trait and channel trait"

Related issue(s): Resolves https://github.com/asyncapi/spec/issues/795

This PR introduces:

new Metadata Object that user can inherits its fields in Server Object, Channel Object, Operation Object and Message Object (and corresponding traits). Metadata Object contains name, title, description, summary, tags and externalDocs fields. It can contains also extensions.
new Server Trait Object
new Channel Trait Object

The idea of Metadata Object was discussed in https://youtu.be/-qUGjylYLJg?t=3044 The idea of new traits was discussed in https://www.youtube.com/watch?v=uoKEet0jcSc

cc @fmvilas @derberg @jonaslagoni @smoya @dalelane

May 12 '22 13:05 magicmatatjahu

@fmvilas @jonaslagoni @jessemenning New way of applying Metadata Object was introduces alongside with Server and Channel Traits in latest commits. Feedback are more that welcome :)

May 26 '22 11:05 magicmatatjahu

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

May 26 '22 11:05 sonarqubecloud[bot]

I agree with some folks from https://www.youtube.com/watch?v=uoKEet0jcSc to not having a Metadata Object but have all those fields inline on those objects that don't have them. Regarding implementation on the spec, I'm up for duplicating the fields on the objects rather than creating the new "Metadata Object in there and talking about inheritance. I think this will overcomplicate the spec and its readability, adding no real value to the final user.

What I'm concerned about right now is the fact name is not clear to me once we have ids on each Object. Ok, Channel doesn't have ID but could have it, so why would we want to keep name field anymore? Could we then deprecate it?

Jun 17 '22 14:06 smoya

@smoya

What I'm concerned about right now is the fact name is not clear to me once we have ids on each Object. Ok, Channel doesn't have ID but could have it, so why would we want to keep name field anymore? Could we then deprecate it?

We don't have id on each object, please don't look on mentioned issue :)

Regarding implementation on the spec, I'm up for duplicating the fields on the objects rather than creating the new "Metadata Object in there and talking about inheritance. I think this will overcomplicate the spec and its readability, adding no real value to the final user.

For me it doesn't make the specification more complex, but let's see what other people say about it.

Jun 27 '22 11:06 magicmatatjahu

We don't have id on each object, please don't look on mentioned issue :)

By id I'm referring to operationId and messageId

Jun 27 '22 11:06 smoya

@smoya

But operationId and messageId are unique id for object, name is a name, you can have multiple these same names in spec and it should be still valid. I don't see any problems with that.

Jun 27 '22 11:06 magicmatatjahu

@smoya

But operationId and messageId are unique id for object, name is a name, you can have multiple these same names in spec and it should be still valid. I don't see any problems with that.

Let's check the definition for messageId field at https://www.asyncapi.com/docs/reference/specification/v2.4.0#messageObject:

A machine-friendly name for the message.

Now let's think, Isn't the messageId right made for that purpose?

My suggestion is to not only not add the name field but to go further and deprecate it.

Jun 27 '22 11:06 smoya

@smoya

Now let's think, Isn't the messageId right made for that purpose?

I don't think so. As I wrote, id should be one in spec, names you can have several. A good analogy would probably be a dictionary. You can only have unique keys but the given keys can have the same values. That's how I've always understood it.

Jun 27 '22 11:06 magicmatatjahu

@smoya

Now let's think, Isn't the messageId right made for that purpose?

I don't think so. As I wrote, id should be one in spec, names you can have several. A good analogy would probably be a dictionary. You can only have unique keys but the given keys can have the same values. That's how I've always understood it.

Is there a clear use case for declaring the same name on different messages?

Jun 27 '22 11:06 smoya

@smoya I don't know. I'm not the creator of this spec :trollface:

Jun 27 '22 12:06 magicmatatjahu

@smoya I don't know. I'm not the creator of this spec :trollface:

Let's ping them cc @fmvilas.

Jun 27 '22 12:06 smoya

I have a few concerns with this PR:

This PR is doing too much. Please let's keep PRs focused on one thing at a time. Server and Channel traits have not much to do with the metadata object.
I see the metadata object as premature optimization. We are prematurely assuming this information is common to multiple objects but the reality is that not all these fields apply equally to all the objects where metadata is applied. Instead, we're forcing the meaning and usefulness of the properties into the target object.
I think the metadata object is not really providing any value and potentially causing harm (see point 2).
I have the feeling that you're trying to define things in the wrong place. Especially, this: This object inherits the fields from [Metadata Object](#metadataObject). That sounds like you're defining how the parser should work. Like you're trying to apply programming concepts (i.e., inheritance) to a specification's text file. During the call you linked above, I explained how you can still have the "Metadata" object in your code and make everything else inherit it but I don't think this is necessarily useful for the user. It's actually worse because it's not clear at first sight that these objects can have name, description, etc.

Jul 04 '22 09:07 fmvilas

@fmvilas thanks! So tl;dr; 😄

create separate PR for new traits,
add all fields from Metadata Object to the destination Objects?

Jul 04 '22 11:07 magicmatatjahu

@fmvilas thanks! So tl;dr; 😄

* create separate PR for new traits,

* add all fields from Metadata Object to the destination Objects?

Yes, but only the fields that make sense or are providing real value.

Jul 04 '22 14:07 fmvilas

Ok, traits removed, all fields from Metadata Object (which is also removed) are inlined, updated examples.

cc @derberg @fmvilas @dalelane

Oct 03 '22 11:10 magicmatatjahu

As we discussed, I removed name property from objects (I leave name in Message Object - we have another discussion for it https://github.com/asyncapi/spec/issues/862). Could someone check it? :)

cc @derberg @fmvilas @dalelane @smoya @char0n @jonaslagoni

Nov 09 '22 10:11 magicmatatjahu

@fmvilas Thanks for review! Done :)

Nov 14 '22 13:11 magicmatatjahu

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

Nov 14 '22 13:11 sonarqubecloud[bot]

@derberg @smoya @char0n I need one more approval :)

Nov 22 '22 12:11 magicmatatjahu

PR in the parser-js https://github.com/asyncapi/parser-js/pull/677

Nov 22 '22 15:11 magicmatatjahu

@derberg @smoya @char0n can we help unlock this PR?

Dec 07 '22 06:12 fmvilas

@derberg @smoya @char0n @fmvilas @dalelane Ok, I have 3 approvals. Someone from you, feel free to merge when you have time :) Thanks!

Dec 19 '22 11:12 magicmatatjahu

/rtm

Dec 19 '22 11:12 magicmatatjahu

Sorry! I had forgotten that automerge works here 😅

Dec 19 '22 11:12 magicmatatjahu

:tada: This PR is included in version 3.0.0-next-major-spec.6 :tada:

The release is available on GitHub release

Your semantic-release bot :package::rocket:

Dec 19 '22 11:12 asyncapi-bot