Defining Optional Properties and Nullable Values in RAML

man coding Optional-properties-nullable-values

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
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

plektonlabs partner with noname security
News

PlektonLabs Partners with Noname Security

Partnership seeks to solidify mutual commitment to ensuring API security Toronto, 8 April 2022: PlektonLabs and Noname Security announced today that the companies have entered

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
18 King Street E, Suite 1400, Toronto ON M5C 1C4, Canada

USA Office
5900 Balcones Dr, 100, Austin, Texas 78731, USA

Phone: +1(877) 855-8775
Email: info@plektonlabs.com

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