[📑 Docs]: NEW tutorial, "How to validate AsyncAPI documents"

[quetzalliwrites]

What Dev Docs changes are you proposing?

Write NEW tutorial, "How to validate AsyncAPI documents", using the below outline template.

---

NEW agnostic tutorials outline template

Introduction

In this AsyncAPI tutorial, we're going to learn about...

Background context

(add info on technologies used, why it matters, etc.)

Installation guide

Before you proceed to the next stage, you'll need to download a few things:

• Install Node.js (v15 or newer).
• Install Git on your Operating System (OS):
  • Install Git on MacOs
  • Install Git on Windows
  • Install Git on Linux

Tutorial step 1

In this step, we will...

Tutorial step 2

In this step, we will...

Tutorial step 3

In this step, we will...

Summary:

In this tutorial, we built...

Next steps:

Now that you've completed this tutorial, why don't you check out how to do ABC with our ABC tutorial? You may also want to check out the XYZ tutorial to learn how to XYZ.

Code of Conduct

• I agree to follow this project's Code of Conduct

[quetzalliwrites]

Here's the new docs issue for your other tutorial, @starlightknown. 😄✌🏽

Let me know what you need to keep going! 🎉🎉🎉

[derberg]

@starlightknown maybe you could update this issue with the notes that I shared during our validation-related meeting. Where I described different topics related to "validation". This issue is for AsyncAPI file validation so I guess we need to create separate one for Message validation using AsyncAPI file

[starlightknown]

Notes

• validation against the specification
  • using AsyncAPI tools
    • core -> AsyncAPI Parser JS
      2 step validation:
      - validation against AsyncAPI JSON Schema document
      - custom validation
    • AsyncAPI Parser by default supports AsyncAPI Schema / JSON Schema -> format for messages
      - custom schema formats https://github.com/asyncapi/avro-schema-parser
    • CLI - AsyncAPI CLI - "asyncapi validate"
  • not using AsyncAPI tools - then use AsyncAPI JSON Schema and write your own custom validation
  • validation against the company best practices or so called governance (linting) validation
    • https://www.asyncapi.com/blog/creating-consistency-announcing-asyncapi-spectral-together
    • for nodejs just use Spectral and https://meta.stoplight.io/docs/spectral/1e63ffd0220f3-async-api-rules that AsyncAPI maintainers also maintain

[starlightknown]

@starlightknown maybe you could update this issue with the notes that I shared during our validation-related meeting. Where I described different topics related to "validation". This issue is for AsyncAPI file validation so I guess we need to create separate one for Message validation using AsyncAPI file

#881 I created it

[derberg]

fyi, this PR asyncapi/spec-json-schemas#243 is almost merged. I gives you more details on AsyncAPI JSON Schema

[starlightknown]

https://youtu.be/7RQT6EEXzBw recording about validation

[quetzalliwrites]

Hey @Annysah, like we spoke offline in Slack with Karuna, let's go ahead and give this tutorial to you. 😄✌🏽

She has added context and a YouTube recording from her talk w/ Lukasz about this topic to help get you started. Please let me know what else you may need to get started and how I can best support you! ❤️✨✨

[Annysah]

Thanks @alequetzalli. I will get to work!

[quetzalliwrites]

Heyooo @Annysah, we're actually going to give this tutorial to @starlightknown because she will turn it into a Studio tutorial. 😄

You may remember this change is because of what we're talking about in Slack:

We're going to update the Streetlights tutorial by converting it into 4 separate NEW tutorials:

• create AsyncAPI document
• validate AsyncAPI document
• generate code
• validate code messages/events

From the above list, I am going to assign you @Annysah the following tutorials instead:

• create AsyncAPI document
• generate code

We already have the content for those two mini tutorials from our current Streetlights tutorial so it should be easy for your to flesh out the rest of the new docs. :)

[github-actions]

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

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 ❤️