Allow for complete topic name description through flexible baseTopic & topics.topic composition about spec HOT 11 CLOSED

Sorry for the confusing message. I decided not to go for Version 2 yet because most of these changes were non-breaking changes. So I released versions 1.1.0 and 1.2.0. And I'm about to start working on 1.3.0.

New features are there since my last reply and more are coming. I'm just not bumping major version yet until it's necessary.

from spec.

But that completely changes the way baseTopic and topics work, making it backward incompatible. Or, am I missing something? On the other hand, this approach sounds much more rigid to me.

How would you do it if you want to have my/base/topic/anEvent/v1 and my/base/topic/anEvent/v1/somethingElse?

baseTopic was conceived to avoid repetition, but if you want you can still avoid using it and create topics as follows:

topics:
  my/base/topic/{t}/v1:
     subscribe: ...
  my/base/topic/{t}/v1/somethingElse:
     subscribe: ...

Hope this helps on clarification. Let me know if I'm not getting your proposal correctly.

Thanks!

from spec.

@fmvilas, there must be some misunderstanding. The variable can be introduced in a fully backwards-compatible way, simply by using the convention that, if it is not used, the baseTopic- & topics.topic values are composed as before to obtain the complete topic names.

baseTopic was conceived to avoid repetition, but if you want you can still avoid using it and create topics as follows: ...

We already thought that baseTopic was introduced to avoid duplication, and that's also the reason why we want to use it, just in a more flexible way. Our complete topic names follow a company-predefined pattern in which the topic-specific part is surrounded by service/API-specific parts. However, the way baseTopic is currently conceived doesn't allow us to document the service/API-specific parts separately from the topic-specific part and avoid duplication. Instead, it requires us to duplicate the service/API-specific suffix of the pattern for every topic, which is obviously not what we want to do. Hence our request for more flexibility and our solution proposal. The alternative that you propose doesn't avoid duplication and hence doesn't solve the issue.

How would you do it if you want to have my/base/topic/anEvent/v1 and my/base/topic/anEvent/v1/somethingElse?

The solution proposal allows you to document a common pattern for the API/service topics (e.g., my/base/topic/{t}) and to document the remainder on the topics level (e.g., anEvent/v1 and anEvent/v1/somethingElse).

from spec.

baseTopic: my/base/topic/{t}/v1
topics:
  anEvent:
    subscribe: ...

I would expect this to become my/base/topic/{t}/v1/anEvent and the only difference is that the baseTopic will contain a variable. Actually, this feature was already requested in the Slack channel. I understand your use case but I'm afraid we should come up with a better solution for it. If something can behave in very different ways we should aim for explicitness instead of conventions.

I was thinking one possible solution could be that baseTopic property allows an object, where you can describe the variables. Maybe there, we can indicate the "algorithm" used for baseTopic. For instance:

baseTopic:
  topic: my/base/topic/{t}/v1
  algorithm: pattern # Or "concat" (default) to behave as before.
  variables:
    t:
      ...

And/or maybe this could be indicated as a special variable type, using double curly brackets:

baseTopic: my/base/topic/{{t}}/v1

In any case, there should be a way to describe what t is.

Let me know if you come up with a better idea.

from spec.

I like the {{t}} notation to denote that t is a language-defined variable instead of a user-defined one.
For now, I have not been able to come up with a better solution. Using {{topic}} as the variable name might further clarify its intention.

from spec.

If there is still time for discussion around this I may have some suggestions.

from spec.

Sure, feel free to make suggestions. Version 2 development is stopped for now.

from spec.

@fmvilas What do you mean by stopped? Discontinued?

from spec.

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

from spec.

How about adding this feature to 2.x now?

from spec.

I don't think it's suitable anymore. We removed baseTopic because we decided not to have indirect modifiers of properties, i.e., if you read the channels map it is not clear that there will be something somewhere else in the document that will modify them. We came to the conclusion that it's useful for authors but not for consumers. And in the end, it's not super useful. Avoiding repetition is something tooling can solve.

from spec.