RAML 1.0: Using Types Within a Type


#1

Hi All,

We’re working on an API design project, and have been attempting to wrap our heads fully around RAML 1.0. One of the issues we’ve come across is that we are attempting to separate larger types into separate files, primarily for readability reasons. A couple of questions:

a) Should we not be doing this? Is the RAML recommendation that all types for example be defined within a single library and/or file?

b) If it’s OK that we want to separate types into separate files, how do we reference a type within a type? IE, let’s say we include a DataType with the following definition:

#%RAML 1.0 DataType
type: object
   parameters:
      simpleParam:
        type: typesLibrary.neededType   

The only way we have found to do the above would be to create the above not as a DataType but instead as a Library, which then references another library (in the example above, typesLibrary. This doesn’t seem to make much sense (though, perhaps it is what libraries are intended for) - and we are trying to figure out whether we are approaching this problem wrong by trying to break types into files, or what the best approach is.

As an aside, once we get into DataTypes being libraries, that also seems to introduce the concept of a “complex” data type (IE, one that depends on other data types) vs. a “simple” data type (IE, one that only depends on itself).

I figure that types depending on other types is a common problem (and indeed is referenced in the RC 1.0 docs), so I wanted to find out what we are doing wrong here :slight_smile:


#2

OK - nevermind. I think I’ve solved this - instead of using libraries, it seems that here we should be using !include syntax for both items as well as type definitions. So, to confirm, I would use the following:

#%RAML 1.0 DataType
type: object
   parameters:
      simpleParam:
        type: !include neededType.raml

And, in the case of a collection I could use the include as part of items: []. Is this correct?


#3

Hi @Trevor_White,

both options are valid and really depends on how granular you want to define your types. Option a) using a library could be used to define types in a specific domain - the library being the domain; and option b) is to have the most granular option. Be aware though that you can easily do option b) and re-use them in option a), but not the other way around as you might already have realised. So both are valid, but I would prefer using DDD and define types inside libraries.

As for collections and using DataType. Here is an example:

#%RAML 1.0 DataType

type: object
properties:
  name: string
  chapters:
    type: array
    items: !include chapter.raml
    required: false