feat: add missed "metadata" fields in the Server/Channel/Operation Objects #796

magicmatatjahu · 2022-05-12T13:39:09Z

title: add missed "metadata" fields in the Server/Channel/Operation Objects

Related issue(s):
Resolves #795
Part of #750

This PR introduces:

add title, summary, externalDocs fields in Server Object,
add title, summary fields in Channel Object,
add title field in Operation Object and Operation Trait Object,

cc @fmvilas @derberg @jonaslagoni @smoya @dalelane

magicmatatjahu · 2022-05-12T13:48:05Z

spec/asyncapi.md

+
+#### <a name="metadataObject"></a>Metadata Object
+
+The object provides metadata about the described object. May contain previously non defined fields.


I have a problem with May contain previously non defined fields. sentence, because I don't know if we should allow only defining extensions and not non defined field. With this possibility there will be problems with validation on tooling side, by extension we can support it, by non defined fields no.

magicmatatjahu · 2022-05-26T11:27:13Z

@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 :)

sonarcloud · 2022-05-26T11:32:33Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

smoya · 2022-06-17T14:52:48Z

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?

magicmatatjahu · 2022-06-27T11:22:12Z

@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.

smoya · 2022-06-27T11:28:00Z

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

By id I'm referring to operationId and messageId

magicmatatjahu · 2022-06-27T11:31:01Z

@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.

smoya · 2022-06-27T11:35:34Z

@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.

magicmatatjahu · 2022-06-27T11:47:11Z

@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.

smoya · 2022-06-27T11:54:43Z

@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?

magicmatatjahu · 2022-06-27T12:14:49Z

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

smoya · 2022-06-27T12:18:53Z

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

Let's ping them cc @fmvilas.

fmvilas · 2022-07-04T09:33:15Z

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.

magicmatatjahu · 2022-07-04T11:52:37Z

@fmvilas thanks! So tl;dr; 😄

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

fmvilas · 2022-07-04T14:03:25Z

@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.

magicmatatjahu · 2022-10-03T11:59:51Z

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

cc @derberg @fmvilas @dalelane

fmvilas · 2022-10-06T20:19:23Z

spec/asyncapi.md

@@ -371,32 +391,54 @@ Field Name | Type | Description
 <a name="serverObjectUrl"></a>url | `string` | **REQUIRED**. A URL to the target host.  This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served. Variable substitutions will be made when a variable is named in `{`braces`}`.
 <a name="serverObjectProtocol"></a>protocol | `string` | **REQUIRED**. The protocol this URL supports for connection. Supported protocol include, but are not limited to: `amqp`, `amqps`, `http`, `https`, `ibmmq`, `jms`, `kafka`, `kafka-secure`, `anypointmq`, `mqtt`, `secure-mqtt`, `solace`, `stomp`, `stomps`, `ws`, `wss`, `mercure`, `googlepubsub`.
 <a name="serverObjectProtocolVersion"></a>protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc.
+<a name="serverObjectName"></a>name | `string` | A machine-friendly name for the server.


Isn't the server id (the key in servers object) already a machine-friendly name for the server? Why do we need one more property here? 🤔

Thanks for review! This is one field I wonder if it makes sense. Of course, we can treat the key in servers/channels/operations as an id/name of object, but in v3, servers/channels/operations/messages will be easily referenced, hence this id between references can change, and someone, for example, needs to give a "static" name for an object that will not change between refs. This makes a lot of sense for model generation and reusability of models.

If, on the other hand, the name doesn't make sense, we should probably remove it also from the Message Object - the messageId could be such a name for message. What do you think?

cc @derberg @jonaslagoni @smoya @dalelane

fmvilas · 2022-10-06T20:22:00Z

spec/asyncapi.md

@@ -612,12 +654,15 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="channelObjectAddress"></a>address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions).
 <a name="channelObjectMessages"></a>messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the [message objects](#messageObject) defined in this map.**
+<a name="channelObjectName"></a>name | `string` | A machine-friendly name for the server.


Same as with server above. Isn't the channel id already a machine-friendly name?

If we end up leaving it, let's not forget to fix the typo:

Suggested change

<a name="channelObjectName"></a>name | `string` | A machine-friendly name for the server.

<a name="channelObjectName"></a>name | `string` | A machine-friendly name for the channel.

fmvilas · 2022-10-06T20:22:46Z

spec/asyncapi.md

@@ -612,12 +654,15 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="channelObjectAddress"></a>address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions).
 <a name="channelObjectMessages"></a>messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the [message objects](#messageObject) defined in this map.**
+<a name="channelObjectName"></a>name | `string` | A machine-friendly name for the server.
+<a name="channelObjectTitle"></a>title | `string` | A human-friendly title for the server.


Suggested change

<a name="channelObjectTitle"></a>title | `string` | A human-friendly title for the server.

<a name="channelObjectTitle"></a>title | `string` | A human-friendly title for the channel.

fmvilas · 2022-10-06T20:23:53Z

spec/asyncapi.md

@@ -808,6 +855,8 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="operationObjectAction"></a>action | `string` | **Required**. Allowed values are `send` and `receive`. Use `send` when it's expected that the application will send a message to the given [`channel`](#operationObjectChannel), and `receive` when the application should expect receiving messages from the given [`channel`](#operationObjectChannel).
 <a name="operationObjectChannel"></a>channel | [Reference Object](#referenceObject) | **Required**. A `$ref` pointer to the definition of the channel in which this operation is performed. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience.
+<a name="operationObjectName"></a>name | `string` | A machine-friendly name for the operation.


Same as with server and channel above. Isn't it enough with the operation id?

fmvilas

LGTM but you got conflicts.

magicmatatjahu · 2022-11-14T13:10:19Z

@fmvilas Thanks for review! Done :)

sonarcloud · 2022-11-14T13:10:22Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

dalelane

LGTM 👍

dalelane · 2022-11-20T19:53:34Z

spec/asyncapi.md

@@ -2316,7 +2362,7 @@ type: userPassword
 ```

 ```yaml
-type: apiKey,
+type: apiKey


nice catch :-)

magicmatatjahu · 2022-11-22T12:04:29Z

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

magicmatatjahu · 2022-11-22T15:03:31Z

PR in the parser-js asyncapi/parser-js#677

fmvilas · 2022-12-07T06:19:34Z

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

char0n

LGTM. Nice work!

magicmatatjahu · 2022-12-19T11:00:52Z

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

magicmatatjahu · 2022-12-19T11:01:09Z

/rtm

magicmatatjahu · 2022-12-19T11:02:15Z

Sorry! I had forgotten that automerge works here 😅

asyncapi-bot · 2022-12-19T11:02:25Z

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

The release is available on GitHub release

Your semantic-release bot 📦🚀

…jects (asyncapi#796) Co-authored-by: Jonas Lagoni <[email protected]>

magicmatatjahu requested review from fmvilas, derberg, dalelane and asyncapi-bot-eve as code owners May 12, 2022 13:39

magicmatatjahu commented May 12, 2022

View reviewed changes

magicmatatjahu changed the title ~~chore: add metadata object~~ chore: add metadata object, server trait and channel trait May 26, 2022

magicmatatjahu mentioned this pull request Jun 10, 2022

[3.0.0] Introduce Info Item Object #795

Closed

jonaslagoni mentioned this pull request Jul 18, 2022

Work on 3.0 release #691

Closed

fmvilas force-pushed the next-major-spec branch from 8805c88 to 624ad52 Compare September 22, 2022 13:38

magicmatatjahu force-pushed the next-major/metadata-object branch from 1b876a1 to 4aa95d0 Compare October 3, 2022 10:08

magicmatatjahu changed the title ~~chore: add metadata object, server trait and channel trait~~ feat: add missed "metadata" fields in the Server/Channel/Operation/Schema Objects Oct 3, 2022

magicmatatjahu mentioned this pull request Oct 3, 2022

Expanded tags support: allow adding tags to more entities, support refs #750

Closed

fmvilas requested changes Oct 6, 2022

View reviewed changes

smoya requested a review from fmvilas October 10, 2022 11:27

magicmatatjahu mentioned this pull request Oct 26, 2022

Spec 3.0 Meeting, 16:00 UTC Wednesday October 26th 2022 asyncapi/community#491

Closed

magicmatatjahu added 3 commits November 9, 2022 12:22

fix conflicts

0384438

fix server external docs

4784ff2

remove traits

9cb4551

fmvilas reviewed Nov 14, 2022

View reviewed changes

Merge branch 'next-major-spec' into next-major/metadata-object

cf810a0

fmvilas approved these changes Nov 20, 2022

View reviewed changes

dalelane approved these changes Nov 20, 2022

View reviewed changes

magicmatatjahu changed the title ~~feat: add missed "metadata" fields in the Server/Channel/Operation/Schema Objects~~ feat: add missed "metadata" fields in the Server/Channel/Operation Objects Nov 22, 2022

smoya mentioned this pull request Nov 23, 2022

[3.0.0] Should we have messageId and name fields in Message Object? #862

Closed

char0n approved these changes Dec 19, 2022

View reviewed changes

asyncapi-bot added the ready-to-merge label Dec 19, 2022

asyncapi-bot merged commit c46448f into asyncapi:next-major-spec Dec 19, 2022

magicmatatjahu deleted the next-major/metadata-object branch December 19, 2022 11:02

asyncapi-bot added the released on @next-major-spec label Dec 19, 2022

GreenRover pushed a commit to GreenRover/asyncapi-spec that referenced this pull request Jan 18, 2023

feat: add missed "metadata" fields in the Server/Channel/Operation Ob…

c8ff048

…jects (asyncapi#796) Co-authored-by: Jonas Lagoni <[email protected]>

This was referenced Feb 6, 2023

feat: add reusable tags and externalDocs objects asyncapi/spec-json-schemas#245

Merged

feat: add title, summary and description fields to the core models asyncapi/spec-json-schemas#315

Merged

jonaslagoni mentioned this pull request Mar 15, 2023

Spec 3.0 Meeting, 16:00 UTC Wednesday March 15th 2023 asyncapi/community#624

Closed

quetzalliwrites mentioned this pull request Mar 15, 2023

[📑 Docs]: Create docs for spec 3.0 release asyncapi/website#1433

Closed

9 tasks

smoya mentioned this pull request Mar 31, 2023

[2.0.0] Discussion how to release 2.0.0 parser-js asyncapi/parser-js#585

Closed

6 tasks

quetzalliwrites mentioned this pull request Apr 4, 2023

docs: common metadata fields asyncapi/website#1438

Closed


		#### <a name="metadataObject"></a>Metadata Object

		The object provides metadata about the described object. May contain previously non defined fields.

	<a name="channelObjectName"></a>name \| `string` \| A machine-friendly name for the server.
	<a name="channelObjectName"></a>name \| `string` \| A machine-friendly name for the channel.

	<a name="channelObjectTitle"></a>title \| `string` \| A human-friendly title for the server.
	<a name="channelObjectTitle"></a>title \| `string` \| A human-friendly title for the channel.

feat: add missed "metadata" fields in the Server/Channel/Operation Objects #796

feat: add missed "metadata" fields in the Server/Channel/Operation Objects #796

Conversation

magicmatatjahu commented May 12, 2022 • edited Loading

title: add missed "metadata" fields in the Server/Channel/Operation Objects

magicmatatjahu May 12, 2022

Choose a reason for hiding this comment

magicmatatjahu commented May 26, 2022

sonarcloud bot commented May 26, 2022

smoya commented Jun 17, 2022

magicmatatjahu commented Jun 27, 2022 • edited Loading

smoya commented Jun 27, 2022

magicmatatjahu commented Jun 27, 2022 • edited Loading

smoya commented Jun 27, 2022

magicmatatjahu commented Jun 27, 2022

smoya commented Jun 27, 2022

magicmatatjahu commented Jun 27, 2022

smoya commented Jun 27, 2022

fmvilas commented Jul 4, 2022 • edited Loading

magicmatatjahu commented Jul 4, 2022

fmvilas commented Jul 4, 2022

magicmatatjahu commented Oct 3, 2022

fmvilas Oct 6, 2022

Choose a reason for hiding this comment

magicmatatjahu Oct 7, 2022 • edited Loading

Choose a reason for hiding this comment

fmvilas Oct 6, 2022

Choose a reason for hiding this comment

fmvilas Oct 6, 2022

Choose a reason for hiding this comment

fmvilas Oct 6, 2022

Choose a reason for hiding this comment

fmvilas Oct 6, 2022

Choose a reason for hiding this comment

fmvilas left a comment

Choose a reason for hiding this comment

magicmatatjahu commented Nov 14, 2022

sonarcloud bot commented Nov 14, 2022

dalelane left a comment

Choose a reason for hiding this comment

dalelane Nov 20, 2022

Choose a reason for hiding this comment

magicmatatjahu commented Nov 22, 2022 • edited Loading

magicmatatjahu commented Nov 22, 2022

fmvilas commented Dec 7, 2022

char0n left a comment

Choose a reason for hiding this comment

magicmatatjahu commented Dec 19, 2022

magicmatatjahu commented Dec 19, 2022

magicmatatjahu commented Dec 19, 2022

asyncapi-bot commented Dec 19, 2022

magicmatatjahu commented May 12, 2022 •

edited

Loading

magicmatatjahu commented Jun 27, 2022 •

edited

Loading

magicmatatjahu commented Jun 27, 2022 •

edited

Loading

fmvilas commented Jul 4, 2022 •

edited

Loading

magicmatatjahu Oct 7, 2022 •

edited

Loading

magicmatatjahu commented Nov 22, 2022 •

edited

Loading