Usage in `Channel Item Object.servers` field

[char0n]

I'm not 100% sure of the intended usage of Channel Item Object.servers field. The specification says following:

This limits using referencing Server Object to ones defined Servers Object (by name). Should we allow referencing the Server Object even from Components.servers field as well?

This is continuation of https://github.com/asyncapi/spec/issues/705 where this unclarity was first identified and it has been discussed that it probably warrants a separate issue.

[magicmatatjahu]

@char0n Hello! We only allow the names of the servers (and don't reference) for simple reason, If you will make reference to the Server Object we will have a problem of checking equality of available servers in the spec in the tooling side. From user perspective it can be easy to read but how to check that in the tool side? Only by checking deep equality of available servers and referenced one, yes? Probably you know that (then sorry for that obvious info 😆 ), but from the issue description I wanna clarify it also for another people.

Should we allow referencing the Server Object even from Components.servers field as well?

And this is a separate problem. In the mentioned issue, Jonas has right that channel.servers should point only to the "active" (available) servers in the spec, so you need first define that server in the servers section (by inline def or by $ref). However, with introduction Components.servers and Components.channels someone can indicate that there is possibility to define reusable channel, which is available for given server (defined in the components.servers) and if someone want to reuse that channel, have to also reuse appropriate server in spec. I hope you're keeping up 😅 And tbh at the moment we support that case, because our ParserJS throws error, when channel has defined servers that don't exist in the spec. So at the end user will reference the server from components.servers but then that server will be also available under servers section.

EDIT: Of course that name in the servers and components.servers should be the same.

[magicmatatjahu]

Another insight: I think that we actually have a problem with reusing channels that have defined servers from components.servers. An easier solution would be to use the server "id" (that we don't have), saved in the Server Object, instead of the server name in the servers section.

[char0n]

@char0n Hello! We only allow the names of the servers (and don't reference) for simple reason

Right, I was specifically referring to the usage with in Channel Item Object.server which can only reference Server Object via it's name (string). The name is defined in Servers Objects keys (or at least it was before 2.3.0). Now from the specification it it's not 100% clear that server names are also keys from Components.servers field.

However, with introduction Components.servers and Components.channels someone can indicate that there is possibility to define reusable channel, which is available for given server (defined in the components.servers) and if someone want to reuse that channel, have to also reuse appropriate server in spec. I hope you're keeping up sweat_smile And tbh at the moment we support that case, because our ParserJS throws error, when channel has defined servers that don't exist in the spec. So at the end user will reference the server from components.servers but then that server will be also available under servers section.

I think this is an actual problem of the 2.3.0 specification. If I create reusable Channel Item Object in Components.channels I'd assume I could use reusable Server Object from Components.server in Channel Item Object.servers field. But according to v2.3.0 spec I have to put new Server Object or Reference Object to Servers Object even for reusable Channel Item Object which may or may not be used later in the document. If I understand correctly your description, the current version of the tooling currently bypass this problem by artificially injecting Server Object into Servers Object?

Another insight: I think that we actually have a problem with reusing channels that have defined servers from components.servers. An easier solution would be to use the server "id" (that we don't have), saved in the Server Object, instead of the server name in the servers section.

Yes IMHO this is a problem introduced by reusable Server Object(s) and Channel Item Objects(s) and some implications of this have been missed. Best course of action would be fix it.

[magicmatatjahu]

If I understand correctly your description, the current version of the tooling currently bypass this problem by artificially injecting Server Object into Servers Object?

No, tooling doesn't inject Server Object into .servers field. I mean if you have defined some server (by name) in the reusable Channel Item Object (defined in the components.channels) and if destination server is placed in the components.servers and you wanna reuse that channel in your AsyncAPI spec, you have to make reference for server in the .servers with this same key, like:

servers:
  thisSameKey:
    $ref: '#/components/servers/thisSameKey'
    
channels:
  someChannel:
    $ref: '#/components/channels/anotherNameForChannel'
    
components:
  servers:
    thisSameKey:
      ...
  channels:
    anotherNameForChannel:
      servers: ['thisSameKey']
      ...

In current solution tooling throws error when you try to use server name (key in the .servers) that doesn't exist.

[char0n]

Thanks I get it now. Examples speaks he truth ;] So the tooling behaves as the specification mandates. And that's good.

Wouldn't the whole issue with reusable Channel Item Object be resolved if we allow Channel Item Object.servers field to be of type [string] | Servers Object? This way the reusable Channel Item Object will be self-contained and always reusable without any implications.

[magicmatatjahu]

Wouldn't the whole issue with reusable Channel Item Object be resolved if we allow Channel Item Object.servers field to be of type [string] | Servers Object? This way the reusable Channel Item Object will be self-contained and always reusable without any implications.

I don't think so, because as I wrote in the first comment:

We only allow the names of the servers (and don't reference) for simple reason, If you will make reference to the Server Object we will have a problem of checking equality of available servers in the spec in the tooling side. From user perspective it can be easy to read but how to check that in the tool side? Only by checking deep equality of available servers and referenced one

Of course defined Servers Objects in the Channel Item Object should be defined also in the .servers field, so its not that easy to solve. I guess that we need some like server.id field (like we have .id - https://www.asyncapi.com/docs/specifications/v2.3.0#A2SIdString) and then we will be able to use references because on tooling side we will only compare that id :)

[char0n]

I don't think so, because as I wrote in the first comment:

Let me explain what I mean on an example. I'm talking about going with more how OpenAPI defines it's servers.

---

Iteration 1

Every Channel Item Object allows to define it's own Servers Object map. If the map is defined for Channel Item Object.servers field, then this map is used. If Channel Item Object.servers field is absent or empty then this channel must be available on all servers defined in the Servers Object. Reference Object can be used here to reference other Server Objects. This allows allows complete self-containment of reusable Channel Item Objects defined in Components.channels field and allows to reference existing Server Objects and defining new ones.

# we define common servers for the definition
servers:
  production1: 
    url: "production.gigantic-server.com"
    description: "Production server"
    protocol: "kafka"
    protocolVersion: "1.0.0"
  production2:
    $ref: "#/components/servers/production2"

components:
  servers:
    production2: 
      url: "production.gigantic-server.com"
      description: "Production server"
      protocol: "kafka"
      protocolVersion: "1.0.0"
  channels:
    channelItem1:
      servers:
         production1: # this is distinct from #/servers/production1
           url: "production.gigantic-server.com"
           description: "Production server"
           protocol: "kafka"
           protocolVersion: "1.0.0"
         production2:
            $ref: "#/components/servers/production2"
channels:
  channelItem1:
    # no additional complexity is involved here as this entire AsyncAPI definition is self-contained
    # and referencing the reusable Channel Item Object doesn't force us to add new `Server Object`
    # into `Servers Objects` map.
    $ref: "#/components/channels/channelItem1" 

problem of checking equality of available servers in the spec in the tooling side

Hm, this sounds like more an implementation detail problem then the specification one, but let me elaborate here to establishing an understanding (on my side). You say that Reference Object cannot be used, instead name of the server (the key under which it's defined) must be used to reference the server. I would argue that it's possible to create an implementation that uses Reference Object which will transclude the referenced Server Object into Channel Item Object.servers field. I really don't see why there is need to do any equality checking between servers. For whatever reason there is, every Server Object can be identified by it's canonical JSON Pointer - absolute URL: http://example.com/asyncapi-definition.yaml/#/components/servers/production2 and this information can be used to for establishing the identity for comparison (if there is really needed one).

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart: