Essential building blocks: Vision for each tool

[jonaslagoni]

Setting a vision for each of these:

• JSON Schema files for AsyncAPI
• Parser
• Code first tool
• schema registry
• Integration into existing frameworks
• Code generators

[jonaslagoni]

JSON Schema files for AsyncAPI

Is the single source of truth for what is a valid AsyncAPI document (no matter what the specification says). With the exception of dynamic governance rules such as "examples must match the payload type".

Features include:

• Can validate partial AsyncAPI documents, i.e. only validate Message Object
• Can be used across all programming languages
• Can validate bindings
• Can validate common extensions

Parser

Does not matter which language you build a tool in, you should be able to parse an AsyncAPI document, validate it (or not), and programmably interact with the document to get (or change?) the information.

Features include:

• Can handle all possible references, including private registries, local files, non-JSON/YAML references i.e. protobuf etc (might need spec change)
• Enable me to iterate over an AsyncAPI document
• Production-level interaction that separates the AsyncAPI version and how you get information
• Validate bindings
• Can validate custom extensions
• Can handle custom schemaFormat's both parsing them and validating them
• Has great documentation so the users know how to use the tool
• Can be used across multiple languages that all contain the same level of quality

Code first tool

Engineers should always easily be able to use code to document their application, and get an AsyncAPI document out in the other end, so they don't have to deal with design first approach. No matter what language they use.

Features include:

• Can annotate anything in code that AsyncAPI specification allows
• Can output AsyncAPI documents from code
• Can document an application through code in any language
• Can output "client" AsyncAPI documents from code

Schema registry

You can store a full AsyncAPI document, or partial documents in a schema store, either privately or publically, that each tool will be able to use.

Features include:

• Can be used as part of all parsers and therefore all subsequent tools
• Exposes an API so it can be used as part of a larger integration
• Can be used as part of a platform
• Can handle multiple versions of schemas in an intuitive way

Integration into existing frameworks

It should be easy to use AsyncAPI in your existing (any) framework and development workflow, so as a developer you can reap all the benefits with AsyncAPI instantly.

Features include:

• Enable beyond documentation
• Making it easier to handle message payloads based on the AsyncAPI document
• Making it easier to handle headers based on the AsyncAPI document
• Making it easier to handle topics/channels/paths based on the AsyncAPI document

Code generators

Should be easy to save time, help catch bugs, and improve code in the development process by using AsyncAPI documents to generate code from the AsyncAPI document.

Features include:

• Typed models for AsyncAPI Message payloads
• Typed models for AsyncAPI headers
• Typed models topic/message matrix
• Helper functions for interacting with defined channels through the provided client
• Full library generation that "externals" can use to interact with a specific application/system

[lorenzsimon]

JSON Schema:

• source of truth
• good IDE support (autocomplete and validation)
• distributed documentation (reusable components) -> references

Parser:

• Serialize and deserialize to most common languages
• Language idiomatic builders
• Included JSON Schema generation (if possible)

Code first tools:

• Application Framework integration
• Message Broker integration
• Flexibility

Schema registry:

• Provides public api to store and retrieve documents
• has version history

Integration into existing frameworks: (is part of code first tools and code generators)

Code generators:

• Application Framework integration
• Follows best practices of the language and framework
• Can generate projects and add components
• Is customisable (community can add their own templates)

[Souvikns]

JSON Schema for validating AsyncAPI Documents

• (Must Have) Make sure json-schema validating tools across languages produce close results.
• (Must Have) Validating bindings.

Parsers

• (Must Have) Load AsyncAPI documents from file, url and supported data structure.
• (Must Have) Validate AsyncAPI file according to the spec.
• (Must Have) Show meaningful and helpful error messages if invalid spec.
• (Must Have) Provide an interface to access 1 to 1 representation of data in AsyncAPI file.
• (Must Have) Provide helpful functions to access parts of the AsyncAPI file.
• (Must Have) Resolve references while parsing.
• (Should Have)Support for circular reference.
• (Must Have) A set of minimum tests required to maintain standards for parsers in different languages.

Code first tools

• (Must Have) Able to generate AsyncAPI spec from code.
• (Must Have) Create asycnapi plugins for frameworks. example

Schema registry

• (Must Have) Store different schema formats
• (Could Have) use parser-api to have schema formats.

Code generators

• (Must Have) Improve templates for code generators.
• (Must Have) improve documentation for template developers.
• (Must Have) better discovery for templates.

Integrating with existing frameworks

• (Could Have) Make plugins for existing web frameworks
• (Must Have) Better documentation for creating plugins

[VisualBean]

JSON Schema files for AsyncAPI

Single source of truth for the AsyncAPI specification. Used by parsers and other tools to validate whether they got it right or not. TCK is a good example of what i'm thinking.

Parser

Parse the asyncapi specification, into language specific models and back again.

• Any, JsonSchema and perhaps even Avro support (not to sure about the necesity for this.)
• Full reference resolution (We will probably need to find or make an actual RFC for this.. (that is valid).
• Should follow validity rules like "Must have at least 1 channel" or "server must be a uri".
• Bindings.
• Follow language specific conventions, but have the same look and feel across languages.

Code first tool

Saunter like tooling for main languages. Generating asyncapi specs, from a code first approach. Would be great with a framework for this, to make it better integrated with code side broker setup, than simply chaining methods that do nothing except define the specification.

Schema registry

Integration into existing frameworks

Code generators

• Broker integrations through bindings.

[jonaslagoni]

Current merged visions

JSON Schema files for AsyncAPI

Is the single source of truth for what is a valid AsyncAPI document (no matter what the specification says).

With the exception of dynamic governance rules such as "examples must match the payload type".

Features include:

• Are "well tested" to ensure we don't accidentally break stuff
• Can validate partial AsyncAPI documents, i.e. only validate Message Object
• Can be used across all programming languages
• Can validate all official bindings and compatible versions
• Integrated with various IDE's (autocomplete and validation)
• Distributed documentation (reusable components) -> references
• Should follow validity rules like "server must be a uri".

Parser

Does not matter which language you build a tool in, you should be able to parse an AsyncAPI document, validate it (or not), and programmable interact with the document to get (or change?) the information.

Features include:

• Can handle all possible references, including private registries, local files, non-JSON/YAML references i.e. protobuf etc (might need spec change)
  • Should be able to handle circular references.
• Provide an interface to access 1 to 1 representation of the AsyncAPI structure
• Production-level interaction that separates the AsyncAPI version and how you get information
• Load AsyncAPI documents from file, url and supported data structure.
• Can validate AsyncAPI documents, including bindings, extensions, and different schema formats
• Can handle custom schemaFormat's both parsing them and validating them
• Has great documentation so the users know how to use the tool
• Ensure we have proper testing kits across parser implementations
• Follow language specific conventions, but have the same look and feel across languages.
• Serialize and deserialize the AsyncAPI documents
• Show meaningful and helpful error messages if an invalid specification

Code first tool

Engineers should always easily be able to use code to document their application and get an AsyncAPI document out in the other end, so they don't have to deal with design first approach.

Features include:

• Can annotate anything in code that AsyncAPI specification allows
• Can output AsyncAPI documents from code
• Can output the reverse perspective ("client") AsyncAPI documents from code
• Can document an application through code in any language
• Can be integrated into existing frameworks
• Can easily be integrated into broker interaction
• Generate JSON Schema (or others) from message payload types

Schema registry

You can store a full AsyncAPI document, or partial documents in a schema registry, either privately or publicly, that each tool will be able to use.

Features include:

• Can be used as part of all parsers and therefore all subsequent tools
• Provides an API to store and retrieve documents, so it can be used as part of a larger integration
• Can be used as part of a platform
• Can handle multiple versions of schemas in an intuitive way
• Can add full AsyncAPI document
• Can add partial AsyncAPI documents (anything that can be a component)

Code generators

Should be easy to save time, help catch bugs, and improve code in the development process by using the AsyncAPI documents to generate code.

Features include:

• Typed models for AsyncAPI Message payloads
• Typed models for AsyncAPI headers
• Typed models topic/message matrix
• Helper functions for interacting with defined channels through the provided client
• Can generate full libraries that "externals" can use to interact with a specific application/system
• Follows best practices of the language and framework
• Is customizable so users can create their own code generators
• Can be integrated into any existing framework

[lorenzsimon]

Priorities

JSON Schema files for AsyncAPI

(must have) - Are "well tested" to ensure we don't accidentally break stuff (must have) - Can validate partial AsyncAPI documents, i.e. only validate Message Object (must have) - Integrated with various IDE's (autocomplete and validation) (should have) - Can be used across all programming languages (should have) - Distributed documentation (reusable components) -> references (should have) - Should follow validity rules like "server must be a uri". (can have) - Can validate all official bindings and compatible versions

Parser

(must have) - Provide an interface to access 1 to 1 representation of the AsyncAPI structure (must have) - Load AsyncAPI documents from file, url and supported data structure. (must have) - Has great documentation so the users know how to use the tool (must have) - Serialize and deserialize the AsyncAPI documents (must have) - Show meaningful and helpful error messages if an invalid specification (should have) - Ensure we have proper testing kits across parser implementations (should have) - Follow language specific conventions, but have the same look and feel across languages. (should have) - Can validate AsyncAPI documents, including bindings, extensions, and different schema formats (should have) - Production-level interaction that separates the AsyncAPI version and how you get information (can have) - Can handle all possible references, including private registries, local files, non-JSON/YAML references i.e. protobuf etc (might need spec change) (can have) - Can handle custom schemaFormat's both parsing them and validating them

Code first tool

(must have) - Can output AsyncAPI documents from code (must have) - Can document an application through code in any language (must have) - Can be integrated into existing frameworks (must have) - Generate JSON Schema (or others) from message payload types (should have) - Can annotate anything in code that AsyncAPI specification allows (can have) - Can output the reverse perspective ("client") AsyncAPI documents from code (can have) - Can easily be integrated into broker interaction

Schema registry

(must have) - Can be used as part of all parsers and therefore all subsequent tools (must have) - Provides an API to store and retrieve documents, so it can be used as part of a larger integration (must have) - Can handle multiple versions of schemas in an intuitive way (must have) - Can add full AsyncAPI document (must have) - Can add partial AsyncAPI documents (anything that can be a component) (can have) - Can be used as part of a platform

Code generators

(must have) - Typed models for AsyncAPI Message payloads (must have) - Typed models for AsyncAPI headers (must have) - Typed models topic/message matrix (must have) - Follows best practices of the language and framework (must have) - Can be integrated into any existing framework (should have) - Is customizable so users can create their own code generators (can have) - Helper functions for interacting with defined channels through the provided client (can have) - Can generate full libraries that "externals" can use to interact with a specific application/system

[jonaslagoni]

Priority list

JSON Schema files for AsyncAPI

MUST HAVE;

• Are "well tested" to ensure we don't accidentally break stuff
• Can be used across all programming languages
• Can validate all official bindings and compatible versions
• Integrated with various IDE's (autocomplete and validation)

SHOULD HAVE;

• Should follow validity rules like "server must be a uri".
• Can validate partial AsyncAPI documents, i.e. only validate Message Object

CAN HAVE;

• Distributed documentation (reusable components) -> references

Parser

MUST HAVE;

• Can handle all possible references, including private registries, local files, non-JSON/YAML references i.e. protobuf etc (might need spec change)
  • Should be able to handle circular references.
• Provide an interface to access 1 to 1 representation of the AsyncAPI structure
• Load AsyncAPI documents from file, url and supported data structure.
• Can validate AsyncAPI documents, including bindings, extensions, and different schema formats
• Can handle custom schemaFormat's both parsing them and validating them
• Follow language specific conventions, but have the same look and feel across languages.
• Show meaningful and helpful error messages if an invalid specification

SHOULD HAVE;

• Production-level interaction that separates the AsyncAPI version and how you get information
• Has great documentation so the users know how to use the tool
• Ensure we have proper testing kits across parser implementations
• Serialize and deserialize the AsyncAPI documents

CAN HAVE;

Code first tool

MUST HAVE;

• Can annotate anything in code that AsyncAPI specification allows
• Can output AsyncAPI documents from code
• Can document an application through code in any language

SHOULD HAVE;

• Can output the reverse perspective ("client") AsyncAPI documents from code

CAN HAVE;

• Can be integrated into existing frameworks
• Can easily be integrated into broker interaction
• Generate JSON Schema (or others) from message payload types

Schema registry

MUST HAVE;

• Can be used as part of all parsers and therefore all subsequent tools
• Can handle multiple versions of schemas in an intuitive way
• Can add full AsyncAPI document
• Can add partial AsyncAPI documents (anything that can be a component)

SHOULD HAVE;

• Provides an API to store and retrieve documents, so it can be used as part of a larger integration

CAN HAVE;

• Can be used as part of a platform

[jonaslagoni]

Proposed priority list from @Souvikns @lorenzsimon and me:

JSON Schema files for AsyncAPI

(must have) - Are "well tested" to ensure we don't accidentally break stuff (must have) - Can be used across all programming languages (must have) - Can validate partial AsyncAPI documents, i.e. only validate Message Object (must have) - Integrated with various IDE's (autocomplete and validation) (should have) - Should follow validity rules like "server must be a URI" (should have) - Can validate all official bindings and compatible versions (should have) - Distributed documentation (reusable components) -> references

Parser

(must have) - Provide an interface to access 1 to 1 representation of the AsyncAPI structure (must have) - Load AsyncAPI documents from file, url and supported data structure. (must have) - Has great documentation so the users know how to use the tool (must have) - Serialize and deserialize the AsyncAPI documents (must have) - Show meaningful and helpful error messages if an invalid specification (should have) - Ensure we have proper testing kits across parser implementations (should have) - Follow language specific conventions, but have the same look and feel across languages. (should have) - Can validate AsyncAPI documents, including bindings, extensions, and different schema formats (should have) - Production-level interaction that separates the AsyncAPI version and how you get information (can have) - Can handle all possible references, including private registries, local files, non-JSON/YAML references i.e. protobuf etc (might need spec change) (can have) - Can handle custom schemaFormat's both parsing them and validating them

Code first tool

(must have) - Can output AsyncAPI documents from code (Generate JSON Schema (or others) from message payload types) (must have) - Can document an application through code in any language (must have) - Can be integrated into existing frameworks (should have) - Can annotate anything in code that AsyncAPI specification allows (can have) - Can output the reverse perspective ("client") AsyncAPI documents from code (can have) - Can easily be integrated into broker interaction

Schema registry

(must have) - Can be used as part of all parsers and therefore all subsequent tools (must have) - Provides an API to store and retrieve documents, so it can be used as part of a larger integration (must have) - Can handle multiple versions of schemas in an intuitive way (must have) - Can add full AsyncAPI document (must have) - Can add partial AsyncAPI documents (anything that can be a component) (can have) - Can be used as part of a platform

Code generators

(must have) - Typed models for AsyncAPI Message payloads (must have) - Typed models for AsyncAPI headers (must have) - Typed models topic/message matrix (must have) - Follows best practices of the language and framework (must have) - Can be integrated into any existing framework (should have) - Is customizable so users can create their own code generators (can have) - Helper functions for interacting with defined channels through the provided client (can have) - Can generate full libraries that "externals" can use to interact with a specific application/system