When declaring request parameters, path parameters, request body, response body, … in RAML, we need to declare the data type of these information. RAML defines many different data types that help us to meet our needs. In this tutorial, we will learn about data types in RAML!
First, look at the image below, in general, RAML defines the hierarchical data types as follows:
As you can see, at the top of the diagram above, we have a data type of any. Information defined with type any will have no restrictions at all, you can define numbers, letters, objects, whatever data types you want.
Underneath any data type, we have more detailed, specific data types that are more restrictive if the information is defined by these data types. As you can see, we have scalar types, array, object, union, XSD schema and even JSON schema.
Scalar types
In short, scalar types are simple data types that are not defined from other data types, such as boolean, string, null, file,… Values of information are defined with scalars types are single, boolean has only true, false; string then the values are just strings…
Date-only
We only declare the date and year for this data type and follow the format defined by the Internet standard for time RFC 3339.
Eg:
|
1 2 3 4 |
types: birthday: type: date-only example: 1987-06-24 |
Time-only
In contrast to date-only, this data type only allows us to define hours, minutes, seconds, it does not support days, months, and years with timezone and it also follows RFC 3339 format!
Eg:
|
1 2 3 4 |
types: lunchtime: type: time-only example: 12:30:00 |
Datetime
There are 2 supported formats for datetime data type, RFC 3339 and RFC 2616. By default, if we don’t tell the format, the format used will be RFC 3339.
Eg:
|
1 2 3 4 |
types: created: type: datetime example: 2021-11-30T16:41:41.090Z |
Datetime-only
Many of you may wonder if there is a datetime data type, what does the datetime-only data type mean? Actually, datetime-only is a combination of date-only and time-only guys, they are separated by the letter “T” and this data type does not support timezone!
Eg:
|
1 2 3 4 |
types: pickup: type: datetime-only example: 2021-10-04T21:00:00 |
Number
Number is a data type common to all data types related to numbers. It allows us to define the minimum value, the maximum value, what the format is: int, int8, int16, int32, int64, long, float, double.
Eg:
|
1 2 3 4 5 6 |
types: weight: type: number minimum: -1.1 maximum: 20.9 format: float |
Integer
This is a data type that inherits the number data type with an integer value.
Eg:
|
1 2 3 4 5 6 |
types: age: type: integer minimum: -3 maximum: 5 format: int8 |
Boolean
The value of the data type is just true or false, representing correctness.
Eg:
|
1 2 3 |
types: isMarried: type: boolean |
String
We can define String according to the pattern with minLength and maxLength, for example like this:
|
1 2 3 4 5 6 |
types: name: type: string pattern: ^.+@.+\..+$ minLength: 10 maxLength: 50 |
Null
This is the data type that allows the field to be undefined.
For example, if you define a Student object with a field name that cannot be null as follows:
|
1 2 3 4 5 6 |
types: Student: type: object properties: name: string comment: string |
then you cannot define example as follows:
|
1 2 3 4 5 6 7 8 9 |
types: Student: type: object properties: name: string comment: string example: name: Khanh comment: |
We can define the Student object as follows:
|
1 2 3 4 5 6 |
types: Student: type: object properties: name: comment: nil | string |
then we can define example as follows:
|
1 2 3 4 5 6 7 8 9 |
types: Student: type: object properties: name: comment: nil | string example: name: Khanh comment: |
File
This data type is for the management of file-related information. We can specify the file format, minLength and maxLength size in bytes for this data type.
Eg:
|
1 2 3 4 5 |
types: avatar: type: file fileTypes: ['image/jpeg', 'image/png'] maxLength: 307200 |
Array
The array data type helps us define an array of data, which can be a string array, a number array or even an array of objects, just like in Java!
You need to specify which data type the item in the array is, whether it needs to be unique or not, and you can also specify the limit on the number of items in the array by minItems and maxItems.
Eg:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
types: Student: type: object properties: name: string Students: type: Student[] minItems: 1 uniqueItems: true example: - name: Khanh - name: Phuc |
Object
Object helps us define information about the object, with many properties belonging to this object. In the above examples, I have defined the object data type for Student.
Eg:
|
1 2 3 4 5 |
types: Student: type: object properties: name: string |
Union
Union is a data type that allows us to define values using many different data types.
For example, the properties name in the following Student object can be null or string.
|
1 2 3 4 5 |
types: Student: type: object properties: name: nil | string |
XSD and JSON schema
XSD and JSON schema help us define data types using XML and JSON schema.
