From c84066df89dcbee70d90f3931850bc80631ca39a Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Fri, 22 Jun 2018 14:30:24 +0100
Subject: [PATCH] do not use 'optional' in descriptions.

---
 meta/documentation_style.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst
index a67f25ff..a866d1eb 100644
--- a/meta/documentation_style.rst
+++ b/meta/documentation_style.rst
@@ -100,3 +100,7 @@ When writing OpenAPI specifications for the API endpoints, follow these rules:
 
   The description is also the place to define default values for optional
   properties. Use the wording "Defaults to X [if unspecified]."
+  
+  Some descriptions start with the workd "Optional" to explicitly mark optional 
+  properties and parameters. This is redundant. Instead, use the ``required``
+  property to mark those that are required.