asyncapi/spec

Decide what to do with OAS schema properties

Pakisan opened this issue · 5 comments

Pakisan commented

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

This thread begun here - #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:

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: #957

fmvilas commented

@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 commented

@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
image
fmvilas commented

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 commented

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

  • 👍1