RAML designs are key to having a fluid and effective integration experience. And two of the most important concepts of RAML design are – optional properties and nullable type properties.
A nullable type T allows values of type T and as well as the null value. If T is a string type, we can represent nullable T in RAML as type: string | nil
.
A property is required if the presence of the property is mandatory in the JSON payload. Thus, an optional property is a property that can be omitted in the JSON payload.
Now that the semantics are out of the way, let’s define that in RAML. In Fig 1 (a and b), we define two RAML data types that are equivalent. In both types, name
is a required property and country
is an optional property. In Fig 1.a. we define the country
property optional using a trailing ? and in Fig 1.b we use required: false
facet to make it optional. As shown in this example, we can use a trailing ? or a required
facet to define an optional property.
#%RAML 1.0 DataType
properties:
name:
type: string
country?:
type: string
a. Using a trailing ?
#%RAML 1.0 DataType
properties:
name:
type: string
required: true
country:
type: string
required: false
b. Using required
facet
Fig 1. RAML data types with optional properties
The JSON objects shown in Fig. 2 (a and b) are valid for data types defined in Fig 1. Note that in the second JSON object (Fig 2.b), the country
property is missing.
{
"name": "PlektonLabs",
"country": "Canada"
}
a. With country
property
{
"name": "PlektonLabs"
}
b. Without country
property
Fig 2. Valid JSON objects for data types defined in Fig 1.
What would happen if we use a trailing ? and required: false
facet together as shown in Fig. 3? In that case, the property is optional as it has a required: false
facet. However, the question mark (?) becomes a part of the property name. Thus, the property name becomes “phone?”
. A valid JSON object for this data type is shown in Fig 4.
#%RAML 1.0 DataType
properties:
name:
type: string
required: true
phone?:
type: string
required: false
Fig 3. RAML data type using a trailing ? and required
facet.
{
"name": "PlektonLabs",
"phone?": "123456780"
}
Fig 4. Valid JSON object for data type defined in Fig 3.
Let’s see how to define a property that allows null value. To do this, we can add the nil
type when we define the property type. In Fig 5, the country
property has nil
type. Thus, this property allows null value as shown in Fig 6.
#%RAML 1.0 DataType
properties:
name:
type: string
country:
type: string | nil
Fig 5. RAML data type with nil
property type.
{
"name": "PlektonLabs",
"country": null
}
Fig 6. Valid JSON object for data type defined in Fig 5.
Now, let’s see how to define a property that is optional and allows null values. We can use a trailing ? (or required: false
facet) and nil type as shown in Fig 7. Two valid JSON objects are shown in Fig 8.
#%RAML 1.0 DataType
properties:
name:
type: string
country?:
type: string | nil
Fig 7. RAML data type with an optional property that allows null value.
{
"name": "PlektonLabs"
}
a. Without country
property
{
"name": " PlektonLabs",
"country": null
}
b. Country
value is null
Fig 8. Valid JSON objects for data type defined in Fig 7.
Let’s summarize these concepts in the following table.
Description | RAML definition | Valid JSON objects | Invalid JSON objects |
Required property (Property must be present in the payload and value cannot be null) |
name: type: string type: string required: true |
{ |
{ and { |
Optional property (Property can be omitted in the payload and if present, value cannot be null) |
name?: OR name: |
and
|
{ |
Nullable value (property must be present and allows null value) |
name: |
and
|
{ |
Optional property and nullable value (property can be omitted and allows null value) |
OR
|
and
and { |