Menu

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.
(<annotationName>)? 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