docs: tutorial validation of messages

[starlightknown]

Description

• new tutorial - validation of messages in runtime
• the tutorial outline in sync with the given template.

Related issue(s)

#881

[netlify[bot]]

❌ Deploy Preview for asyncapi-website failed.

Built without sensitive environment variables

Name	Link
🔨 Latest commit	2f7130068eea1965681a03c42bae332bc1519681
🔍 Latest deploy log	https://app.netlify.com/sites/asyncapi-website/deploys/6358968f3d03990008acccba

[github-actions[bot]]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🔴 Performance	34
🟠 Accessibility	88
🟠 Best practices	83
🟢 SEO	90
🔴 PWA	30

Lighthouse ran on https://deploy-preview-886--asyncapi-website.netlify.app/

[quetzalliwrites]

Hey @starlightknown, I just made this a Draft PR so that I would stop getting confused thinking it was ready to review 😀✌🏽

[starlightknown]

@alequetzalli Lot of steps in the starting are getting repeated in this tutorial like creating asyncapi file and generating the code. Am I going in the right direction? the validation part comes later. My concern is the tutorial shows repetitive steps as in streetlights

[derberg]

@starlightknown if you start seeing that more and more tutorials we get, we start repeating content, I think we might start thinking of content reuse. I'm fan of repeating, then adding link to separate page that people have to follow. I think we can achieve content reuse here pretty easily through React. In the end we use MDX, so we can in any place of the markdown file use react components. So we would just have to write reusable content with React 🤔 @magicmatatjahu thoughts?

aside from above. In regards to validation of payload in runtime, you want to write a tutorial on how to do that, or just explain the concept? I'm not sure tutorial is the right way, as in tutorial, if you want to do an explanation based on current code generator, it will be super similar to existing tutorial we have on Streetlight. I think we should more focus on explaining the concept

[magicmatatjahu]

@derberg

So we would just have to write reusable content with React 🤔 @magicmatatjahu thoughts?

It's one of possible solutions, but maybe better idea will be importing markdown content from another markdown file? I don't know if it's possible with MDX, but we should check that possibility, like:

foo bar

@import '../file.md'

- foo
- bar

[magicmatatjahu]

@derberg Yeah, it's possible - https://mdxjs.com/docs/using-mdx/#components

import License from './license.md' // Assumes an integration is used to compile MDX -> JS.
import Contributing from './docs/contributing.mdx'

# Hello world

<License />

---

<Contributing />

[derberg]

@magicmatatjahu oh man, this is soooo nifty ❤️ I had no idea 🍺

[starlightknown]

@starlightknown if you start seeing that more and more tutorials we get, we start repeating content, I think we might start thinking of content reuse. I'm fan of repeating, then adding link to separate page that people have to follow. I think we can achieve content reuse here pretty easily through React. In the end we use MDX, so we can in any place of the markdown file use react components. So we would just have to write reusable content with React thinking @magicmatatjahu thoughts?

aside from above. In regards to validation of payload in runtime, you want to write a tutorial on how to do that, or just explain the concept? I'm not sure tutorial is the right way, as in tutorial, if you want to do an explanation based on current code generator, it will be super similar to existing tutorial we have on Streetlight. I think we should more focus on explaining the concept

I had talked with Alejandra for the same, suggestions I got were to refer the code generator part in background context plus linking the tut related to that. I'll focus more on the concept

[starlightknown]

@derberg Yeah, it's possible - https://mdxjs.com/docs/using-mdx/#components

import License from './license.md' // Assumes an integration is used to compile MDX -> JS.
import Contributing from './docs/contributing.mdx'

# Hello world

<License />

---

<Contributing />

Is this something I have to use/ add while writing the tutorial?

[derberg]

@starlightknown most important I would say is 👇🏼

aside from above. In regards to validation of payload in runtime, you want to write a tutorial on how to do that, or just explain the concept? I'm not sure tutorial is the right way, as in tutorial, if you want to do an explanation based on current code generator, it will be super similar to existing tutorial we have on Streetlight. I think we should more focus on explaining the concept

what is the scope of this tutorial? as I wrote I think we should more focus on a use case concept description and share example implementations rather than focus on tutorial. But yeah, I'm not fully aware of the scope you have, what exactly do you want to show? how to use asyncapi-validator module in nodejs? or

[starlightknown]

@starlightknown most important I would say is 👇🏼

aside from above. In regards to validation of payload in runtime, you want to write a tutorial on how to do that, or just explain the concept? I'm not sure tutorial is the right way, as in tutorial, if you want to do an explanation based on current code generator, it will be super similar to existing tutorial we have on Streetlight. I think we should more focus on explaining the concept

what is the scope of this tutorial? as I wrote I think we should more focus on a use case concept description and share example implementations rather than focus on tutorial. But yeah, I'm not fully aware of the scope you have, what exactly do you want to show? how to use asyncapi-validator module in nodejs? or

Since we did nodejs in streetlights, we can continue that and use asyncapi validator with nodejs. I'm kinda stuck with the example, like what exactly can we show them

[derberg]

payload validation in the runtime is a concept that can be solved in many different ways. Impossible to show one good way, but a simple example, sure. But not in a form of a tutorial. Tutorial is step by step that anyone can follow and complete. Here it is more about the concept and general guide description of possible solutions that we know using open source AsyncAPI tools.

easier would be to show tutorials on validating payload schema, stuff I told you about on a call, JSON Schema nad Parser stuff, but even this is more about a guide than a replicable tutorial.

---

so from the docs navigation point of view, imho you need to have a document in Concepts section, like Event validation in runtime ?

• you say that in AsyncAPI, you can provide information about the payload schema of every event, and that you can do it using different formats, JSON, Avro and others (link to specific section in specification document)
• you say that the benefit of describing the contract of API this way, enable you to use asyncapi documents as sources of schema information in the runtime, on production
• and then you have sections of possible solutions on how you can use AsyncAPI file as a source of truth for message validation:
  • one section introduce asyncapi-validator package, that reads asyncapi document. You can show simple code snippet from them how this works (I can help with that). This is example where validation is done in the app described with AsyncAPI
  • another section introduce AsyncAPI event gateway. So another case of validation in runtime, but in this case it is not a library that you intergrate in an App, but validation is done before the message gets into the app, on a gateway. you can ping @Sergio Moya then in a PR on ideas how to share in docs more or less how it works, ask for some code snippet, or maybe a diagram

now that I think about it, best would be to have a simple mermaid diagram, to describe both possible solutions, in one you show that message validation happens in an app, in another that it happens in a gateway. I’m happy to help with it

[quetzalliwrites]

How're we doing on this one @starlightknown? do you feel you have enough context from Lukasz's latest feedback or do you feel blocked? Let us know how we can help you 😄

[starlightknown]

@derberg for gateway validation

[derberg]

@starlightknown for gateway based validation you need to check diagram with @smoya

in general, is this PR valid, or we continue with the other one, guide focused

[smoya]

@derberg for gateway validation

@starlightknown @derberg I've created a new PR on the event-gateway repository with a Mermaid flowchat representing the current behavior of the Event Gateway https://github.com/asyncapi/event-gateway/pull/137 I thought you want to take a look before our meeting on Tuesday 📞