Should Async API use JSON or YAML for code snippets?

[kakabisht]

In AsyncAPI version 3, the code snippets are in both formats. However, using a single format would be more consistent.

[mhmohona]

I did some research on which code format would be better for AsyncAPI spec 3's official documentation. Here I am jotting down my findings -

	JSON	YAML
Readability	Uses brackets for structure which can be harder to read for large data structures.	Uses indentation to denote structure which is generally considered more human-readable.
Comments	Does not support comments.	Supports comments, which can provide extra context or explanation.
Speed and Interoperability	Generally faster and more widely interoperable than YAML.	Despite being slower than JSON, YAML could still perform sufficiently depending on the use case.
Tooling and Libraries	Has robust tooling and libraries.	Also has robust libraries and is even included by default in some packages.
Data Types	Supports basic data types like strings, numbers, booleans, arrays, and objects.	Supports all JSON data types, plus additional types like dates.
Block Literals and Comments	Does not support block literals or comments.	Supports block literals and comments, adding to its readability.
Support for Complex Data Structures	Limited support for complex data structures.	Supports complex data structures, making it more flexible.
Use of Whitespace	Doesn't use whitespace for formatting.	Uses whitespace for formatting, which can lead to errors if not done correctly.
Memory Efficiency	Similar to YAML in terms of memory efficiency.	Similar to JSON in terms of memory efficiency, though the efficiency of the parser can vary.
Preference Among Developers	Preferred by JavaScript developers due to its native support and speed.	Preferred by Python developers due to its use of indentation to denote hierarchy.

I will vote for YMAL format mainly because of its readability and comment support.

[quetzalliwrites]

good work, @mhmohona.. excellent addition to this community discussion!

[derberg]

I think it is good to provide just YAML, but later in the website, I don't see why wouldn't we in automated way show JSON version too 🤔

but yeah, I don't know anyone who would write JSON by hand really

btw, just to confirm, you mean the main AsyncAPI specification document, reference doc?

[quetzalliwrites]

He was trying to propose that we only use JSON code snippets throughout the entire documentation (not only reference section) and not YAML. I told him I didn't think that made sense for our audience, but that he could open a discussion and see what the community voted.

[quetzalliwrites]

@kakabisht, since no votes were received for using JSON only in docs, let's close this discussion. Moving forward, we'll continue to prioritize using YAML code snippets in your gsod work. 😄