Decide what to do with OAS schema properties

[Pakisan]

I want to propose to decide what to do with OpenAPI Schema properties which users are using in our schema.

This thread begun here - https://github.com/asyncapi/spec/issues/1031

In JAsyncAPI I have implemented strict validation, that's why I have enfaced with multiple questions from users.

For example, last questions, from folks at Specmatic:

• https://github.com/asyncapi/jasyncapi/issues/163
• https://github.com/asyncapi/jasyncapi/issues/164

This is strange situation for me, when de jure, strict specification implementation must interpret them as specification error, but de facto, users can use them

Let's decide what to do and how to sync validation process in different tools

@fmvilas @derberg @dalelane @smoya @char0n @GreenRover

upd: task for new validation process: https://github.com/asyncapi/spec/issues/957

[fmvilas]

@Pakisan if they're using OpenAPI Schemas, they should specify so in the schemaFormat field, i.e., it should be application/vnd.oai.openapi;version=3.0.0.

Example with v3:

asyncapi: 3.0.0
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups
channels:
  userSignedup:
    address: user/signedup
    messages:
      UserSignedUp:
        $ref: '#/components/messages/UserSignedUp'
operations:
  sendUserSignedup:
    action: send
    channel:
      $ref: '#/channels/userSignedup'
    messages:
      - $ref: '#/channels/userSignedup/messages/UserSignedUp'
components:
  messages:
    UserSignedUp:
      payload:
        schemaFormat: application/vnd.oai.openapi;version=3.0.0
        schema:
          type: object
          properties:
            displayName:
              type: string
              description: Name of the user
            email:
              type: string
              format: email
              description: Email of the user

This is the schema parser in charge of interpreting it for the JS/TS parser: https://github.com/asyncapi/openapi-schema-parser.

[Pakisan]

@Pakisan if they're using OpenAPI Schemas, they should specify so in the schemaFormat field, i.e., it should be application/vnd.oai.openapi;version=3.0.0.

Example with v3:

asyncapi: 3.0.0
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups
channels:
  userSignedup:
    address: user/signedup
    messages:
      UserSignedUp:
        $ref: '#/components/messages/UserSignedUp'
operations:
  sendUserSignedup:
    action: send
    channel:
      $ref: '#/channels/userSignedup'
    messages:
      - $ref: '#/channels/userSignedup/messages/UserSignedUp'
components:
  messages:
    UserSignedUp:
      payload:
        schemaFormat: application/vnd.oai.openapi;version=3.0.0
        schema:
          type: object
          properties:
            displayName:
              type: string
              description: Name of the user
            email:
              type: string
              format: email
              description: Email of the user

This is the schema parser in charge of interpreting it for the JS/TS parser: https://github.com/asyncapi/openapi-schema-parser.

Hi, Fran. Thanks for schemaFormat example.

~Where I can find all supported formats?~ I found - multiFormatSchemaFormatTable

I agree with you, that in case of provided schemaFormat we can interpret is as Avro, OAS, ...

But I want to clarify validation behavior when users didn't provide any schemaFormat so it must be interpreted as AAS schema

asyncapi: 3.0.0
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups
channels:
  userSignedup:
    address: user/signedup
    messages:
      UserSignedUp:
        $ref: '#/components/messages/UserSignedUp'
operations:
  sendUserSignedup:
    action: send
    channel:
      $ref: '#/channels/userSignedup'
    messages:
      - $ref: '#/channels/userSignedup/messages/UserSignedUp'
components:
  messages:
    UserSignedUp:
      payload:
        schema:
          type: object
          properties:
            displayName:
              type: string
              description: Name of the user
              example: Pavel
              nullable: true
              readOnly: true
              examples:
                - Pavel
                - Peter
            email:
              type: string
              format: email
              description: Email of the user
              example: pavel@address.domain
              readOnly: true
              examples: 
                - email@host.domain

[fmvilas]

But I want to clarify validation behavior when users didn't provide any schemaFormat so it must be interpreted as AAS schema

The behaviour should be to fail. The examples you mentioned are not valid AsyncAPI schemas. Just because they're similar it doesn't mean we have to behave differently.

[Pakisan]

But I want to clarify validation behavior when users didn't provide any schemaFormat so it must be interpreted as AAS schema

The behaviour should be to fail. The examples you mentioned are not valid AsyncAPI schemas. Just because they're similar it doesn't mean we have to behave differently.

Roger that.

Looks like I have implemented strict validation correctly. Now it's time to dive into #957 to actualize specifications validation and bring new version to studio to reject specification which I was using as example, above

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart: