Emulate few spec breaking changes as acceptance criteria for the new Parser API

[smoya]

Emulating new spec major versions that introduce breaking changes will help us for:

• Validate the early design concepts at Define Parser(s) API #90.
• As acceptance criteria for tests at Implement a new JS Parser API #91

By emulating I mean just creating few spec documents where concepts are changed, such as split Operations, renaming fields, changing the deep level of some objects, reorder them, etc.

The outcome of this issue is a collection of either yaml or JsonSchema documents that introduce breaking changes.
They can be written here as a reference by now.

[asyncapi-bot]

Hey! You've labeled this issue as a Scope. Remember you can use the following command to inform about its progress:

/progress <percentage> [message]

or

/progress <percentage>

A mutiline message.
It supports **Markdown**.

Example:

/progress 40 We're still figuring out how to implement this. We have an idea but it is not yet confirmed it will work.

/progress 50

A few notes:

* We got this figured out :tada:
* We're going to use [this library](#link-to-website) to avoid losing time implementing this algorithm.
* We decided to go for the quickest solution and will improve it if we got time at the end of the cycle.

---

🏋️‍♀️ See the progress on the Shape Up Dashboard.

[smoya]

Based on #73, and modifying a bit the StreetLights tutorial example, I emulated a possible breaking change on channels:

Current version:

asyncapi: '2.0.0'
info:
  title: Streetlights API
  version: '1.0.0'
  description: |
    The Smartylighting Streetlights API allows you
    to remotely manage the city lights.
  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0'
servers:
  mosquitto:
    url: mqtt://test.mosquitto.org
    protocol: mqtt
channels:
  light/measured:
    publish:
      summary: Inform about environmental lighting conditions for a particular streetlight.
      operationId: onLightMeasured
      message:
        payload:
          type: object
          properties:
            id:
              type: integer
              minimum: 0
              description: Id of the streetlight.
            lumens:
              type: integer
              minimum: 0
              description: Light intensity measured in lumens.
            sentAt:
              type: string
              format: date-time
              description: Date and time when the message was sent.
  light/measured/changed:
    subscribe:
      summary: Receive an update every time a lighting condition changed.
      operationId: onLightMeasureChanged
      message:
        payload:
          type: object
          properties:
            id:
              type: integer
              minimum: 0
              description: Id of the streetlight.
            lumens:
              type: integer
              minimum: 0
              description: Light intensity measured in lumens.
            sentAt:
              type: string
              format: date-time
              description: Date and time when the message was sent.

New version:

asyncapi: '3.0.0-fake'
# ...
channels:
  light/measured:
    summary: Environmental lighting conditions for a particular streetlight
    operations: 
      # this could be a new component that could be referenced by #/components/operations/onLightMeasured
      onLightMeasured: 
        $ref: "#/components/messages/lightMeasured"
        operationType: publish
        summary: Inform about environmental lighting conditions for a particular streetlight.
 
     # this could be a new component that could be referenced by #/components/operations/onLightMeasureChanged
      onLightMeasureChanged: 
        $ref: "#/components/messages/lightMeasured"
        operationType: subscribe
        summary: Receive an update every time a lighting condition changed.
components:
   messages:
    lightMeasured:
      message:
        payload:
          type: object
          properties:
            id:
              type: integer
              minimum: 0
              description: Id of the streetlight.
            lumens:
              type: integer
              minimum: 0
              description: Light intensity measured in lumens.
            sentAt:
              type: string
              format: date-time
              description: Date and time when the message was sent.

[smoya]

/progress 25 Emulated breaking change based on #73

[smoya]

Another emualted version based on asyncapi/spec#434 supporting multiple message schemaFormat values.

asyncapi: '3.0.0-fake2'
# ...
channels:
  light/measured:
    publish:
      summary: Inform about environmental lighting conditions for a particular streetlight.
      operationId: onLightMeasured
      message:
        schemaFormat: 
         oneOf:
            - "application/vnd.apache.avro+json;version=1.9.0"
            - "application/vnd.oai.openapi;version=3.0.0"
        payload:
          type: object
          properties:
            id:
              type: integer
              minimum: 0
              description: Id of the streetlight.
            lumens:
              type: integer
              minimum: 0
              description: Light intensity measured in lumens.
            sentAt:
              type: string
              format: date-time
              description: Date and time when the message was sent.

[smoya]

/progress 65 Emulated breaking change based on asyncapi/spec#434

[smoya]

Taking a couple of new approaches based on #73:

1. Messages flow within a channel (still) through operations, but objects are decoupled.

asyncapi: '3.0.0-fake3'
# ...
channels:
  light/measured:
    summary: Lighting conditions for a particular streetlight.
operations:
  onLightMeasured:
    operationType: publish
    summary: Inform about environmental lighting conditions for a particular streetlight.
    withMessage: lightMeasured
    withinChannel: light/measured
  onLightMeasureChanged:
    operationType: subscribe
    summary: Receive an update every time a lighting condition changed.
    withMessage: lightMeasured
    withinChannel: light/measured
messages:
  lightMeasured:
    payload:
      type: object
      properties:
        id:
          type: integer
          minimum: 0
          description: Id of the streetlight.
        lumens:
          type: integer
          minimum: 0
          description: Light intensity measured in lumens.
        sentAt:
          type: string
          format: date-time
          description: Date and time when the message was sent.

2. Messages are independent of channels. Messages within a channel can (optionally) be related to operations. Compatible with asyncapi/parser-js#210

asyncapi: '3.0.0-fake4'
# ...
channels:
  light/measured:
    summary: Lighting conditions for a particular streetlight.
    messages:
      - message: lightMeasured # this should exist in `messages`
        operations: 
          onLightMeasured:
            operationType: publish
            summary: Inform about environmental lighting conditions for a particular streetlight.
          onLightMeasureChanged:
            operationType: subscribe
            summary: Receive an update every time a lighting condition changed.
messages:
  lightMeasured:
    payload:
      type: object
      properties:
        id:
          type: integer
          minimum: 0
          description: Id of the streetlight.
        lumens:
          type: integer
          minimum: 0
          description: Light intensity measured in lumens.
        sentAt:
          type: string
          format: date-time
          description: Date and time when the message was sent.

[smoya]

/progress 100 Emulated 2 new breaking changes. One based on #73 and another one based on asyncapi/parser-js#210.