RAML inheritance converted to OAS uses x-amf-merge instead of allOf

[postatum]

Using [email protected].

May be related to #571.

Consider this issue raml-org/webapi-parser#74. When using AMF it can be reproduced using the code below. The output is almost identical to the one reported in the mentioned issue, but described inheritance issue is easy to notice.

The code

const amf = require('amf-client-js')

const ramlStr = `
PUT SNIPPET FROM THE ISSUE HERE
`

async function main () {
  await amf.AMF.init()
  const model = await amf.AMF.raml10Parser().parseStringAsync(ramlStr)
  const ren = new amf.Oas30Renderer()
  console.log(await ren.generateString(model))
}

main()

[tomsfernandez]

Hi @postatum. Unfortunately RAML inheritance and JsonSchema allOf aren't the same construct and therefore cannot be migrated to each other.

RAML inheritance involves first resolving the type and then validating the resultant type. Here the types involved in the inheritance are aware of each other. On the other hand the JsonSchema spec states that types involved in the allOf aren't aware of each other. This is an important difference. I offer an example:

Suppose a RAML example similar as the one stated in the linked issue but instead the basetype overrides a supertype property with a different type. This is clearly an invalid raml as the onlyProperty property isn't specialized.

types:
  Foo:
    type: object
    properties:
      onlyProperty: integer
  Bar:
    type: Foo
    properties: 
      onlyProperty: boolean

With JsonSchema allOf your proposed transformation would be correct as both types are unaware of each other:

definitions:
  Foo:
    type: object
    properties:
      onlyProperty: integer
  Bar:
    allOf:
     - $ref: '#/definitions/Foo'
     - type: object
       properties: 
        onlyProperty: boolean

As seen in the examples RAML inheritance to allOf produces validation inconsistencies as the RAML construct isn't valid but the allOf construct is. That is why this "translation" is incorrect and why we opted to introduce an OAS extension to leave proof of the RAML inheritance

[tomsfernandez]

I'm closing this issue as this is not an AMF bug.

[skingreek]

Hi @tomsfernandez. It is issue was created based on my appeal. I understand that both specifications is not equvalent, but i not understand why equvalent part cann't be converted (valid RAML to valid OAS3). It is limited conversion area from one spec to other cover 80% usecases.
I encountered this problem when I tried to display inheritance in the API-Console. But this tool did not give the UX that open api viewer has.
And i not understand how good idea of RAML will be increase popularity among developers if area of conversion between specifications will be cut this way, becouse toolset for Open API is big now.

I want use RAML in my project, and my project use simple and standard inheritance use cases. Can you recommend tool for viewing inheritance with discriminator support if converting to OAS will be generate x-amf-merge?