From c41dc6f0362b4ca003c3cb26c23aeb1f779ae99e Mon Sep 17 00:00:00 2001
From: Gage Hugo <gagehugo@gmail.com>
Date: Thu, 9 Aug 2018 13:34:34 -0500
Subject: [PATCH] Add details and clarify examples on casing

This change adds some more detail to the roles section of the
casing documentation for keystone, as well as clarifying the
examples given for users and projects. Also added project tags
casing.

Change-Id: I55447c8b599ab48021bd95204c4bf3c5bc7e690c
---
 .../admin/identity-case-insensitive.rst       | 37 +++++++++++++++++--
 1 file changed, 34 insertions(+), 3 deletions(-)

diff --git a/doc/source/admin/identity-case-insensitive.rst b/doc/source/admin/identity-case-insensitive.rst
index 194b8041ca..defc31dd3f 100644
--- a/doc/source/admin/identity-case-insensitive.rst
+++ b/doc/source/admin/identity-case-insensitive.rst
@@ -25,7 +25,15 @@ which creates a new user by the name of "myuser" will return a
 
 .. code-block:: console
 
-    POST /v3/users {name: myuser}
+    POST /v3/users
+
+.. code-block:: json
+
+    {
+        "user": {
+            "name": "myuser"
+        }
+    }
 
 Projects
 --------
@@ -36,7 +44,22 @@ which creates a new project by the name of "foobar" will return a
 
 .. code-block:: console
 
-    POST /v3/projects {name: foobar}
+    POST /v3/projects
+
+.. code-block:: json
+
+    {
+        "project": {
+            "name": "foobar"
+        }
+    }
+
+Project Tags
+^^^^^^^^^^^^
+
+While project names are case-insensitive, project tags are case-sensitive.
+A tag with the value of ``mytag`` is different than ``MyTag``, and both values
+can be stored in the same project.
 
 Roles
 -----
@@ -47,6 +70,14 @@ roles, it creates "admin", "member", and "reader". If another role, "Member"
 since it considers the name "Member" equivalent to "member". Note that case
 is preserved in this event.
 
+.. note::
+  As of the Rocky release, keystone will create three default roles when
+  `keystone-manage bootstrap` is run: (``admin``, ``member``, ``reader``). For
+  existing deployments, this can cause issues if an existing role matches one
+  of these roles. Even if the casing is not an exact match
+  (``member`` vs ``Member``), it will report an error since roles are
+  considered case-insensitive.
+
 Backends
 ========
 
@@ -78,4 +109,4 @@ LDAP
 ----
 
 By default, LDAP DNs are case-insensitive, so the example with users under
-MySQL will apply here as well.
\ No newline at end of file
+MySQL will apply here as well.