docs: update readme.md with overview and custom validation sections #243

Dindihub · 2022-07-19T15:17:27Z

Description

Resolves ISSUE_NUMBER [📑 Docs]: Write down all the custom validation rules that are not in JSON Schema #240

Related issue(s)
#240

github-actions

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

derberg

@Dindihub thanks so much for taking the time to submit this PR 🙏🏼

I left some feedback.

In additional:

please update description, you need to explicitly write Resolves ISSUE_NUMBER to make sure automated closing after merge will work
please move these 2 sections up in the structure of the readme, they should be the first sections that user sees

derberg · 2022-07-21T08:11:59Z

README.md

@@ -106,3 +106,25 @@ The manual process of creating a new version is to:
       ]
    }
    ```
+
+## Overview
+* This repository contains JSON Schema files for all the versions of AsyncAPI specification. You can link to https://json-schema.org/ for reference.


Suggested change

* This repository contains JSON Schema files for all the versions of AsyncAPI specification. You can link to https://json-schema.org/ for reference.

* This repository contains [JSON Schema](https://json-schema.org/ for reference) files for all the versions of AsyncAPI specification.

derberg · 2022-07-21T08:12:34Z

README.md

+## Overview
+* This repository contains JSON Schema files for all the versions of AsyncAPI specification. You can link to https://json-schema.org/ for reference.
+* These JSON Schema files do not reflect 1:1 the specification and shouldn't be treated as specification itself but rather as a tool for things like validation e.t.c
+* These JSON Schema files should'nt be used as the only tool for validation of AsyncAPI documents because some rules described in the AsyncAPI specification are not described here.


Suggested change

* These JSON Schema files should'nt be used as the only tool for validation of AsyncAPI documents because some rules described in the AsyncAPI specification are not described here.

* These JSON Schema files shouldn't be used as the only tool for validating AsyncAPI documents because some rules described in the AsyncAPI specification are not described with JSON Schema.

derberg · 2022-07-21T08:13:20Z

README.md

+* These JSON Schema files should'nt be used as the only tool for validation of AsyncAPI documents because some rules described in the AsyncAPI specification are not described here.
+
+## Custom Validation Needs
+* The JSON Schema does not cover all validation cases, and if a user decides to validate AsyncAPI tools with only JSON Schema provided in this repo, they risk having the AsyncAPI documents not working in tandem with all AsyncAPI tools and this will affect validation.


Suggested change

* The JSON Schema does not cover all validation cases, and if a user decides to validate AsyncAPI tools with only JSON Schema provided in this repo, they risk having the AsyncAPI documents not working in tandem with all AsyncAPI tools and this will affect validation.

* The JSON Schema does not cover all validation cases, and if you decide to validate AsyncAPI tools with only JSON Schema provided in this repo, you risk having the AsyncAPI documents not working in tandem with all AsyncAPI tools, and this will affect validation.

derberg · 2022-07-21T08:15:01Z

README.md

+
+## Custom Validation Needs
+* The JSON Schema does not cover all validation cases, and if a user decides to validate AsyncAPI tools with only JSON Schema provided in this repo, they risk having the AsyncAPI documents not working in tandem with all AsyncAPI tools and this will affect validation.
+* It's recommended to use the custom validation tool provided at https://github.com/asyncapi/parser-js as we look on implementing a comprehensive validation tool.


Suggested change

* It's recommended to use the custom validation tool provided at https://github.com/asyncapi/parser-js as we look on implementing a comprehensive validation tool.

* It's recommended to use [AsyncAPI JavaScript Parser](https://github.com/asyncapi/parser-js) that not only uses AsyncAPI JSON Schema file for validation but also implements additional custom validations.

derberg · 2022-07-21T08:16:24Z

README.md

+    6. Validate if parameters specified in the channel name have corresponding parameters object defined and if name does not contain url parameters.
+    7. Validate if all servers listed for a channel in servers property are declared in the top-level servers object.
+    8. Validate if tags specified in the objects have no duplicates. Check is done for: root, operations, operation traits, channels, messages and message traits.
+* At the moment, Parser-js do not cover all validation cases yet,all test cases and parsers coverage can be found here -> https://asyncapi.github.io/tck/


Suggested change

* At the moment, Parser-js do not cover all validation cases yet,all test cases and parsers coverage can be found here -> https://asyncapi.github.io/tck/

* At the moment, AsyncAPI JavaScript parser do not cover all validation cases yet

* All test cases and parsers coverage can be found [here](https://asyncapi.github.io/tck/)

derberg · 2022-07-21T08:16:51Z

README.md

+* It's recommended to use the custom validation tool provided at https://github.com/asyncapi/parser-js as we look on implementing a comprehensive validation tool.
+
+* The following additional custom validations need to be provided:
+    1. Validate if variables provided in the url property have corresponding variable object defined and if the example is correct


this should be the bullet list as the order doesn't matter.

ordering by number should be used only if the order makes a difference

derberg · 2022-07-21T08:19:30Z

README.md

+    8. Validate if tags specified in the objects have no duplicates. Check is done for: root, operations, operation traits, channels, messages and message traits.
+* At the moment, Parser-js do not cover all validation cases yet,all test cases and parsers coverage can be found here -> https://asyncapi.github.io/tck/
+
+All names of objects/properties can be double-checked with https://www.asyncapi.com/docs/reference/specification/v2.4.0


this was just a note for you in my input, so when you write this readme doc, you use proper names, and put them in code and capitalize them when needed. This is why in my input I for example wrote operationId and not operationId. It matters a lot in tech content, because it indicates that it is not just a word to describe something but actually technical term used in technology you describe.

I hope that makes sense 😅 let me know if you have some doubts
please address this type of highlighting in the list of custom validations

Noted. Let me review and make a new PR.

derberg · 2022-07-25T12:05:10Z

README.md

+* At the moment, AsyncAPI JavaScript parser do not cover all validation cases yet
+* All test cases and parsers coverage can be found [here](https://asyncapi.github.io/tck/)


this should not be part of bullet list of custom validations cases. There should be a separate paragraph below the bullet list

derberg · 2022-07-25T12:06:18Z

README.md

 ![npm](https://img.shields.io/npm/v/@asyncapi/specs?style=for-the-badge) ![npm](https://img.shields.io/npm/dt/@asyncapi/specs?style=for-the-badge)

 > If you are currently using version 2, check out [migration guideline to version 3](./migrations/Migrate%20to%20version%203.md). You might be able to update it without any change.
 # AsyncAPI

 This is a mono repository, which provides all the JSON Schema documents for validating AsyncAPI documents.

+## Overview
+*  This repository contains [JSON Schema](https://json-schema.org/ for reference) files for all the versions of AsyncAPI specification.


I always recommend to check the preview of the markdown and trying to click links, this one is a broken link

Suggested change

* This repository contains [JSON Schema](https://json-schema.org/ for reference) files for all the versions of AsyncAPI specification.

* This repository contains [JSON Schema](https://json-schema.org) files for all the versions of AsyncAPI specification.

Noted.Let me check on the suggestions. Thanks

README.md

derberg

@Dindihub I made some final comments

@dalelane @fmvilas any concerns with the message that we pass to the user?

derberg

I left some additional comments,

I think one problem here is that you make changes only on local, but sometimes it is easier to do it directly in PR when I prepare for you exact solution

have a look at https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request

derberg · 2022-07-25T13:54:01Z

README.md

@@ -106,3 +133,6 @@ The manual process of creating a new version is to:
       ]
    }
    ```
+


some not needed empty spaces

Hi. I have worked on the changes suggested. And thanks for the reference Doc. It helped. Please review.

derberg · 2022-07-25T13:54:05Z

README.md

@@ -1,10 +1,37 @@
+


some not needed empty spaces

README.md

derberg · 2022-07-25T13:54:51Z

README.md

+* Validate if parameters specified in the channel name have corresponding parameters object defined and if name does not contain url parameters.
+* Validate if all servers listed for a channel in servers property are declared in the top-level servers object.
+* Validate if tags specified in the objects have no duplicates. Check is done for: root, operations, operation traits, channels, messages and message traits.
+* At the moment, AsyncAPI JavaScript parser do not cover all validation cases yet


this also should not be a bullet list element as it is not one of custom validations that user have to provide

@Dindihub I think you missed this comment, line 24 should not be part of bullet list

Done. Sorry missed that one. Thnaks

Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com>

Changed line 24 from bullet ist to paragraph.

derberg

@fmvilas @dalelane

Anything from your side. For me it is ready to merge, but I want to make sure you are ok with the messaging we share here.

I'm out next week, so feel free to merge if you also approve folks

fmvilas

Left some comments, hope they help!

README.md

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

Dindihub · 2022-07-29T07:07:11Z

Left some comments, hope they help!

I have committed the new suggestions. Thanks for the input

fmvilas

LGTM 👍

Requesting another review from @derberg since there were lots of changes.

Dindihub · 2022-07-29T07:15:13Z

LGTM +1

Requesting another review from @derberg since there were lots of changes.

Sure

dalelane

This looks good to me - adds useful clarifications

sonarqubecloud · 2022-07-29T10:57:02Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

derberg

Thanks so much @Dindihub 🙇🏼

derberg · 2022-07-29T12:03:53Z

/rtm

asyncapi-bot · 2022-09-20T17:50:01Z

🎉 This PR is included in version 3.2.0-next-major-spec.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

asyncapi-bot · 2022-09-28T13:03:11Z

🎉 This PR is included in version 3.2.0-next-spec.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

asyncapi-bot · 2022-09-29T07:05:08Z

🎉 This PR is included in version 3.2.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

docs:Update README.md with overview and custom validation sections

a754665

Dindihub requested review from fmvilas, derberg, dalelane and asyncapi-bot-eve as code owners July 19, 2022 15:17

github-actions bot reviewed Jul 19, 2022

View reviewed changes

Dindihub changed the title ~~docs:Update README.md with overview and custom validation sections~~ docs: update readme.md with overview and custom validation sections Jul 19, 2022

Merge branch 'master' into updateREADME.md

4a3c27e

derberg requested changes Jul 21, 2022

View reviewed changes

docs:make revisions on readme

f9372a1

derberg reviewed Jul 25, 2022

View reviewed changes

README.md Show resolved Hide resolved

derberg requested changes Jul 25, 2022

View reviewed changes

Dindihub added 2 commits July 25, 2022 15:38

docs: Correct link typo

8ddf475

docs:Correct link typo

7eb2a1e

derberg reviewed Jul 25, 2022

View reviewed changes

Dindihub and others added 4 commits July 25, 2022 21:12

Add spacing

45aef8a

Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com>

Update README.md

4c37ef6

Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com>

Update README.md

f48859d

Update README.md

a5165d8

derberg mentioned this pull request Jul 28, 2022

[📑 Docs]: NEW tutorial, "How to validate AsyncAPI documents" asyncapi/website#872

Closed

1 task

Update README.md

25e9a30

Changed line 24 from bullet ist to paragraph.

derberg previously approved these changes Jul 28, 2022

View reviewed changes

fmvilas requested changes Jul 29, 2022

View reviewed changes

Dindihub dismissed derberg’s stale review via 92a20ae July 29, 2022 06:57

Dindihub and others added 4 commits July 29, 2022 09:57

Update README.md

92a20ae

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

Update README.md

bd98240

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

Update README.md

8d6bbf3

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

Update README.md

ebd2e14

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

Dindihub and others added 8 commits July 29, 2022 10:00

Update README.md

be0197f

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

Update README.md

9a3f08b

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

Update README.md

2e92c06

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

Update README.md

c50bbc9

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

Update README.md

d9c9053

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

Update README.md

1d47076

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

Update README.md

08ba891

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

Update README.md

4e15da8

Co-authored-by: Fran Méndez <fmvilas@gmail.com>

fmvilas requested a review from derberg July 29, 2022 07:08

fmvilas approved these changes Jul 29, 2022

View reviewed changes

dalelane approved these changes Jul 29, 2022

View reviewed changes

Merge branch 'master' into updateREADME.md

27c1474

derberg approved these changes Jul 29, 2022

View reviewed changes

asyncapi-bot added the ready-to-merge label Jul 29, 2022

asyncapi-bot merged commit 1b104ec into asyncapi:master Jul 29, 2022

derberg mentioned this pull request Sep 6, 2022

[📑 Docs]: Write down all the custom validation rules that are not in JSON Schema #240

Closed

1 task

asyncapi-bot added the released on @next-major-spec label Sep 20, 2022

asyncapi-bot added the released on @next-spec label Sep 28, 2022

asyncapi-bot added the released label Sep 29, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update readme.md with overview and custom validation sections #243

docs: update readme.md with overview and custom validation sections #243

Dindihub commented Jul 19, 2022 •

edited

Loading

github-actions bot left a comment

derberg left a comment

derberg Jul 21, 2022

derberg Jul 21, 2022

derberg Jul 21, 2022

derberg Jul 21, 2022

derberg Jul 21, 2022

derberg Jul 21, 2022

derberg Jul 21, 2022

Dindihub Jul 21, 2022

derberg Jul 25, 2022

derberg Jul 25, 2022

Dindihub Jul 25, 2022

derberg left a comment

derberg left a comment

derberg Jul 25, 2022

Dindihub Jul 25, 2022

derberg Jul 25, 2022

derberg Jul 25, 2022

derberg Jul 28, 2022

Dindihub Jul 28, 2022

derberg left a comment

fmvilas left a comment

Dindihub commented Jul 29, 2022

fmvilas left a comment

Dindihub commented Jul 29, 2022

dalelane left a comment

sonarqubecloud bot commented Jul 29, 2022

derberg left a comment

derberg commented Jul 29, 2022

asyncapi-bot commented Sep 20, 2022

asyncapi-bot commented Sep 28, 2022

asyncapi-bot commented Sep 29, 2022

	* This repository contains JSON Schema files for all the versions of AsyncAPI specification. You can link to https://json-schema.org/ for reference.
	* This repository contains [JSON Schema](https://json-schema.org/ for reference) files for all the versions of AsyncAPI specification.

	* These JSON Schema files should'nt be used as the only tool for validation of AsyncAPI documents because some rules described in the AsyncAPI specification are not described here.
	* These JSON Schema files shouldn't be used as the only tool for validating AsyncAPI documents because some rules described in the AsyncAPI specification are not described with JSON Schema.

	* The JSON Schema does not cover all validation cases, and if a user decides to validate AsyncAPI tools with only JSON Schema provided in this repo, they risk having the AsyncAPI documents not working in tandem with all AsyncAPI tools and this will affect validation.
	* The JSON Schema does not cover all validation cases, and if you decide to validate AsyncAPI tools with only JSON Schema provided in this repo, you risk having the AsyncAPI documents not working in tandem with all AsyncAPI tools, and this will affect validation.

	* It's recommended to use the custom validation tool provided at https://github.com/asyncapi/parser-js as we look on implementing a comprehensive validation tool.
	* It's recommended to use [AsyncAPI JavaScript Parser](https://github.com/asyncapi/parser-js) that not only uses AsyncAPI JSON Schema file for validation but also implements additional custom validations.

	* At the moment, Parser-js do not cover all validation cases yet,all test cases and parsers coverage can be found here -> https://asyncapi.github.io/tck/
	* At the moment, AsyncAPI JavaScript parser do not cover all validation cases yet
	* All test cases and parsers coverage can be found [here](https://asyncapi.github.io/tck/)

@@ @@ -106,3 +133,6 @@ The manual process of creating a new version is to: @@
                      ]
                   }
                   ```

docs: update readme.md with overview and custom validation sections #243

docs: update readme.md with overview and custom validation sections #243

Conversation

Dindihub commented Jul 19, 2022 • edited Loading

github-actions bot left a comment

Choose a reason for hiding this comment

derberg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

derberg left a comment

Choose a reason for hiding this comment

derberg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

derberg left a comment

Choose a reason for hiding this comment

fmvilas left a comment

Choose a reason for hiding this comment

Dindihub commented Jul 29, 2022

fmvilas left a comment

Choose a reason for hiding this comment

Dindihub commented Jul 29, 2022

dalelane left a comment

Choose a reason for hiding this comment

sonarqubecloud bot commented Jul 29, 2022

derberg left a comment

Choose a reason for hiding this comment

derberg commented Jul 29, 2022

asyncapi-bot commented Sep 20, 2022

asyncapi-bot commented Sep 28, 2022

asyncapi-bot commented Sep 29, 2022

Dindihub commented Jul 19, 2022 •

edited

Loading