Single source of truth

[char0n]

Sometimes there are situations when it is not clear if the source of truth should be the JSON Schema or the markdown specification. To remedy this situation, we can explicitly state following in main README file:

The human-readable markdown file is the source of truth for the specification.

Whenever there is a conflict, the specification itself is the source of truth before anything else.

[smoya]

I see and agree the source of truth of the spec can become unclear. In fact, I think it becomes less clear for contributors than for users. I can also agree we can need clarification. I would then like to suggest we do it on the spec document (additionally in the README, I don't mind), at the very beginning of the document, e.g. right before https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#disclaimer. A variation of your text could work:

This document represents the single source of truth for the AsyncAPI specification.

WDYT @char0n @fmvilas @derberg @dalelane ?

[char0n]

I would then like to suggest we do it on the spec document

I guess that's automatically implied that specification itself is the single source of truth. Would be quite uncommon to have this explicitly defined in the specification itself. IMHO having it in README suffice, but don't mind having it in specification itself as well, although as I mentioned it's uncommon.

[smoya]

I would then like to suggest we do it on the spec document

I guess that's automatically implied that specification itself is the single source of truth. Would be quite uncommon to have this explicitly defined in the specification itself. IMHO having it in README suffice, but don't mind having it in specification itself as well, although as I mentioned it's uncommon.

I believe most users (including potential ones) won't read the README file, but rather navigate through the AsyncAPI website.

[char0n]

I believe most users (including potential ones) won't read the README file, but rather navigate through the AsyncAPI website.

Just an idea: how about mentioning it in README and the website? I understand that the website is generated from the markdown document, so we just add the sentence to the website templates as well.

[smoya]

Just an idea: how about mentioning it in README and the website?

Sure, this is what I meant by:

additionally in the README, I don't mind

[char0n]

@smoya ahh sorry I misunderstood. I've issued a PR to the website adding the sentence there as well: https://github.com/asyncapi/website/pull/743

[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:

[fmvilas]

I think this has been done already. Let me know otherwise, @char0n.

[char0n]

I confirm, it's been merged into master as editorial change - https://github.com/asyncapi/spec/commit/02393d166a5c70481bd2f7f7f23d69c4f24b83b1