Raml

What is RAML Root of RAML Datatype Defining Datatypes

Defining Datatypes in RAML

Types can be declared inline at the root of the API or in an include library. It is recommended to declare any types definition a library as it can be reused. To declare a type, you use a map where the key represents the name of the type and its value is a type declaration.

types:
  Person: # key name
    # value is a type declaration

Type Declarations

A type declaration references another type, or wraps another type or extends another type by adding functional facets (e.g. properties) or non-functional facets (e.g. a description). Here are the facets list that all type declarations can have.

Remember when there is a '?' next to the key, then it is optional. 

Facet Description
default? This defines a default value for a type. When an API request/response is completely missing the instance of a type, then API must include default values as if it was sent by the request/response.

For example when a query parameter described by a type is entirely missing from the request, then the API must act as if the API client had sent an instance of that type with the instance value being the value in the default facet.
type? The type which the current type extends or just wraps. The value of a type node MUST be either

a) the name of a user-defined type or

b) the name of a built-in RAML data type (object, array, or one of the scalar types) or

c) an inline type declaration.
example? This type is used by documentation generators to generate sample values for an object of this type. The "example" facet MUST NOT be available when the "examples" facet is already defined.
examples? This type is used by documentation generators to generate sample values for an object of this type. The "example" facet MUST NOT be available when the "example" facet is already defined.
displayName? This defines an alternate display name.
description? This is used to describe the type in detail.
()? Annotations to be applied to this API. An annotation is a map having a key that begins with "(" and ends with ")" where the text enclosed in parentheses is the annotation name, and the value is an instance of that annotation.
facets? A map of additional, user-defined restrictions that will be inherited and applied by any extending subtype.
xml? XML Serialization of this type instance.
enum? An enumeration of all the possible values of instances of this type.

An example

#%RAML 1.0
title: My API With Types
types:
  Person:
    type: object
    properties:
      name:
        required: true
        type: string

In RAML there are 2 types of datatype. One is built-in and another is custom type. The RAML type system defines the following built-in types:

  • any
  • scalar
    • number
    • boolean
    • string
    • date-only
    • time-only
    • datetime-only
    • datetime
    • file
    • integer
    • nil
  • object
  • array
  • union
Previous