"It is not allowed to use external types in property definitions."


#1

Why is this the case? I don’t see why that is the case? Isn’t that what types are used for?

Example:

types:
  Person:
    type: object
    properties:
      name: string
      age: integer

/management:
  get:
    responses:
      200:
        application/json:
          type: object
          properties:
            boss: Person
            team: Person[]

Unless there is a clear reason why this is explicitly prohibited in the spec, I don’t see a reason to prohibit it. It seems arbitrarily chosen, while perfectly viable.


#2

Seems the snippet you posted is not valid as it misses the body node after 200.

#%RAML 1.0
title:

types:
  Person:
    type: object
    properties:
      name: string
      age: integer

/management:
  get:
    responses:
      200:
        body:
          application/json:
            type: object
            properties:
              boss: Person
              team: Person[]

The above is the correct example and does indeed validate correctly.


#3

(Yeah, sorry, typed that example manually.) It does not. Just updated my Atom api-workbench plugin and still get the same error:

I did notice that I’m not using it in a response but in a request. So more like this:

#%RAML 1.0
title:

types:
  Person:
    type: object
    properties:
      name: string
      age: integer

/management:
  post:
    body:
      application/json:
        type: object
        properties:
          boss:
            type: Person
            description: blabla
    responses:
      200:
        body:
          application/json:
            type: object
            properties:
              boss: Person
              team: Person[]

#4

The error code that raml2html gives (I guess it uses the RAML linter under the hood) is EXTERNAL_IN_PROPERTY_DEFINITION.


#5

Oh yeah, it’s a type that is included with a JSON schema. That’s probably why it says “external type”. How could that change anything?


#6

But you are not using any JSON schema in your example?! I am confused :smiley:

In general, you are not allowed to extend from an, what we call, external type. Which is either JSON, XSD, or anything else that’s not a RAML data type.

For example:

types:
  Person: !include person.json

In the example above, you are using JSON schema to define the structure of a Person. From here, you are not allowed to further add restrictions to Person (see example 1) or use it in inheritance and further restrict it (see example 2) using the RAML data type system.

example 1

types:
  Person:
    type: !include person.json
    properties: # invalid
      single: boolean

example 2

types:
  Person: !include person.json
  PersonNew:
    type: Person
    properties:
      single: boolean

What you are allowed is to add more documentation to your “external” type as it does not further add restrictions like the following:

types:
  Person:
    type: !include person.json
    description: this is a schema describing person

Hope that helps you!


#7

I’m sorry for the confusion. I understand you can’t change the type definitions of external types, but I’m using an external type in a resource definition, like my above example but with an external type, like this:

#%RAML 1.0

types:
  Person:
    type: !include schemas/person.json

/management:
  post:
    body:
      application/json:
        type: object
        properties:
          boss:
            type: Person  <---- this gives the mentioned error
            description: blabla
    responses:
      200:
        body:
          application/json:
            type: object
            properties:
              boss: Person   <---- this gives the mentioned error

#8

AH, that makes sense now :slight_smile:

No this is forbidden by the RAML specification. Any reason why you would do that vs using plain JSON schema?


#9

So yeah, my question is what that is forbidden :smiley:

We just have a specific format for an object that is specified in a JSON schema for usage across different applications. We use this schema in the API’s that we describe in our RAML files. In the beginning, we were just sending these objects raw as the top object, so we would have this:

body:
  application/json: 
    type: ExternalType`

But now, it turns out some of these calls need some additional information that is not relevant for the schema object, but more for the API call and what to do with the object. So we have something like this:

body:
  application/json:
    type: object
    properties:
      mainObject: ExternalType
      someExtraField: string
      otherExtraField: string

However, that is thus not legal. Instead I have to do something like this:

body:
  application/json:
    type: object
    properties:
      mainObject: 
        description: [...] Must adhere to schema of ExternalType
        type: object
      someExtraField: string
      otherExtraField: string

My question is thus primarily if there was a good reason for forbidding this, or if it’s just an oversight that somehow got forbidden but no one knows why anymore. Changing it is not a breaking change, since it makes the spec more permissive.


#10

The reason is that we found too many issues mixing XSD or JSON schema with RAML data types. You open the door for all sorts of weird combinations which will make it more difficult for tools to handle.