Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revert "feat!: add 3.0.0 validation support (#208)" #460

Merged
merged 1 commit into from
Nov 30, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 1 addition & 13 deletions CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,4 @@

# The default owners are automatically added as reviewers when you open a pull request unless different owners are specified in the file.

* @fmvilas @derberg @dalelane @smoya @char0n @asyncapi-bot-eve

/bindings/anypointmq/ @mboss37 @GeraldLoeffler
/bindings/ibmmq/ @rcoppen
/bindings/jms/ @rcoppen @SrfHead
/bindings/kafka/ @lbroudoux @dalelane
/bindings/googlepubsub/ @whitlockjc
/bindings/solace/ @damaru-inc @CameronRushton
/bindings/pulsar/ @VisualBean
/bindings/sns/ @dpwdec @iancooper
/bindings/sqs/ @dpwdec @iancooper

/bindings/*.json @KhudaDad414
* @fmvilas @derberg @dalelane @smoya @char0n @asyncapi-bot-eve
35 changes: 9 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,24 @@
![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)

## Overview
# AsyncAPI

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

### Two types of schemas

This repository contains [JSON Schema](https://json-schema.org) files for all the versions of AsyncAPI specification. There are two types of JSON Schema files, with and without **$id** feature. We need two versions of schemas because of the differences it tooling implementation of JSON Schema `$ref` and `$id` keywords. Some implementations treat `$id` by default as prefix reference for `$ref` and require it, therefore it is needed to properly correlate `$ref` and `$id` values. Unfortunately other tools do not understand `$id` values and fail dereferencing. This is why we need two different versions of schemas, with and without the `$id`.

### Releases and pre-releases

This repository contains JSON Schema files for official AsyncAPI releases and also for release candidates. Before you decide to use a specific JSON Schema file in production, make sure a corresponding [official release of AsyncAPI specification](https://github.com/asyncapi/spec/releases) is produced, not a release candidate.

JSON Schema which describes a version of AsyncAPI specification that is not yet officially released is considered an unstable pre-release that can change anytime and is not considered to be a breaking-change.

If you want to make sure you only use stable schemas, you have to make sure that you use only certain schema versions, not all by default.

### JSON Schema vs AsyncAPI specification

These JSON Schema files do not reflect 1:1 the specification and shouldn't be treated as specification itself but rather as a tool (e.g., for validation).

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

### Libraries
## Overview

In addition, this repo provides JavaScript and Go modules that make it easier to access JSON Schema files through code. These packages provide access only to schemas with version larger or equal 2.0.0.
* This repository contains [JSON Schema](https://json-schema.org) files for all the versions of AsyncAPI specification. There are two types of JSON Schema files, with and without **$id** feature. We need two versions of schemas because of the differences it tooling implementation of JSON Schema `$ref` and `$id` keywords. Some implementations treat `$id` by default as prefix reference for `$ref` and require it, therefore it is needed to properly correlate `$ref` and `$id` values. Unfortunately other tools do not understand `$id` values and fail dereferencing. This is why we need two different versions of schemas, with and without the `$id`.
* These JSON Schema files do not reflect 1:1 the specification and shouldn't be treated as specification itself but rather as a tool (e.g., for validation).
* These JSON Schema files shouldn't be used as the only tool for validating AsyncAPI documents because some rules described in the AsyncAPI specification can't be described with JSON Schema.
* In addition, this repo provides JavaScript and Go modules that make it easier to access JSON Schema files through code. These packages provide access only to schemas with version larger or equal 2.0.0.

## Custom Validation Needs

If you decide to validate AsyncAPI documents only with the JSON Schema files provided in this repo, your AsyncAPI documents will not be properly validated.
It's recommended to use [AsyncAPI JavaScript Parser](https://github.com/asyncapi/parser-js) that uses the AsyncAPI JSON Schema files for validation but also implements additional custom validations.

The following additional custom validations need to be provided for documents prior to `3.0.0`:
The following additional custom validations need to be provided:

* Variables provided in the `url` property have a corresponding variable object defined and its example is correct.
* Variables provided in the URL property have a corresponding variable object defined and its example is correct.
* `operationId`s are not duplicated in the document.
* `messageId`s are not duplicated in the document.
* Server security is declared properly and the name has a corresponding `securitySchemes` definition in `components` with the same name.
Expand Down Expand Up @@ -123,8 +108,6 @@ func Do() {

If you are currently using version 2, check out [migration guideline to version 3](./migrations/migrate-to-version-3.md).
If you are currently using version 3, check out [migration guideline to version 4](./migrations/migrate-to-version-4.md).
If you are currently using version 4, check out [migration guideline to version 5](./migrations/migrate-to-version-5.md).
If you are currently using version 5, check out [migration guideline to version 6](./migrations/migrate-to-version-6.md).

## Repository structure

Expand Down Expand Up @@ -200,7 +183,7 @@ Whenever a Breaking Change is introduced, the following steps should be taken in

## SchemaStore compatibility testing

AsyncAPI JSON Schema is referenced in [SchemaStore](https://www.schemastore.org/json/). In many IDEs, like VSCode, some extensions integrate with SchemaStore, like [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). This way we enable autocompletion, validation and tooltips that help write AsyncAPI documents.
AsyncAPI JSON Schema is referenced in [SchemaStore](https://www.schemastore.org/json/). In many IDEs, like VSCode, some extensions integrate with SchemaStore, like [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). This way we enable autocompletion, validation and tooltips that helps writing AsyncAPI documents.

Whenever you make changes in AsyncAPI JSON Schema, you should always manually verify that the schema is still supported by [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) and that it will be able to fetch and dereference it.

Expand Down
136 changes: 0 additions & 136 deletions bindings/amqp/0.2.0/channel.json

This file was deleted.

37 changes: 0 additions & 37 deletions bindings/amqp/0.2.0/message.json

This file was deleted.

89 changes: 0 additions & 89 deletions bindings/amqp/0.2.0/operation.json

This file was deleted.

Loading
Loading