How to Define Optional Properties and Nullable Values in RAML

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.

DescriptionRAML definitionValid JSON objectsInvalid JSON objects
Required property
(Property must be
present in the
payload and value
cannot be null)
name:
  type: string
OR
name:

  type: string
  required: true
{
  "name": "Plekton"
}
{
}

and
{
  "name": null
}
Optional property
(Property can be
omitted in the
payload and if present,
value cannot be null)
name?:
  type: string

OR
name:
  type: string
  required: false

 
{
  "name": "Plekton"
}


and

{
}

 
{
  "name": null
}
Nullable value
(property must be present
and allows null value)
name:
  type: string | nil

 
{
  "name": "Plekton"
}


and

{
  "name": null
}

 
{
}

 
Optional property and
nullable value
(property can be omitted
and allows null value)
name?:
  type: string | nil


 OR

name:
  type: string | nil
  required: false
{
  "name": "Plekton"
}


and

{
  "name": null
}


and

{
}
 
 

Share This Post

Share on facebook
Share on linkedin
Share on twitter
Share on email

More To Explore

How can we help?

A little about yourself and we're ready to go

We pride ourselves on swift communication and prompt responses. Let us know what you're thinking and how we can help you.

Contact Information​

Head Office
75 Cornwall Drive, Ajax ON L1T3G2

Toronto Office
602 – 8133 Warden Ave, Markham, ON L6G 1B3, Canada

Phone: +14168902757
Email: info@plektonlabs.com

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.