From f32b6bfa85497568734770d85ae8a26ab8e496b0 Mon Sep 17 00:00:00 2001
From: Christian Heimes <cheimes@redhat.com>
Date: Thu, 9 Nov 2023 08:24:16 +0100
Subject: [PATCH] doc: RDN values and create-only attributes

Add notes which fields are the primary keys / RDN values (relative
distinguised names) of objects. IPA does not support `modrdn` for
servers, certificates, and DNS locations. That means the entries cannot
be renamed and an RDN value identifies an entry.

Also note that domain name and realm name cannot be modified by an
update.

Signed-off-by: Christian Heimes <cheimes@redhat.com>
---
 public.openapi.json | 14 +++++++++-----
 public.openapi.yaml | 16 +++++++++++++---
 2 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/public.openapi.json b/public.openapi.json
index 1226712..7852e18 100644
--- a/public.openapi.json
+++ b/public.openapi.json
@@ -603,7 +603,7 @@
             "example": "O=DOMAIN.EXAMPLE, CN=Certificate Authority"
           },
           "nickname": {
-            "title": "Internal nick name in LDAP",
+            "title": "Internal nick name in LDAP (RDN cn)",
             "type": "string",
             "example": "DOMAIN.EXAMPLE CA"
           },
@@ -640,7 +640,8 @@
         },
         "x-rh-ipa-hcc": {
           "type": "defs"
-        }
+        },
+        "x-rh-rdn-value": "nickname"
       },
       "Domain": {
         "title": "Base type for domain objects",
@@ -683,6 +684,7 @@
         "x-rh-ipa-hcc": {
           "type": "defs"
         },
+        "x-rh-rdn-value": "domain_name",
         "example": {
           "description": "My awesome domain description.",
           "auto_enrollment_enabled": true,
@@ -823,6 +825,7 @@
           "name": "IPAServer",
           "type": "defs"
         },
+        "x-rh-rdn-value": "fqdn",
         "example": {
           "ca_server": true,
           "fqdn": "ipaserver.mydomain.example",
@@ -835,7 +838,7 @@
       },
       "DomainName": {
         "title": "Fully qualified domain name",
-        "description": "A name of a domain (all lower-case)",
+        "description": "A name of a domain (all lower-case). The domain name can only be set during initial registration and not be modified by updates.\n",
         "type": "string",
         "format": "idn-hostname",
         "maxLength": 253,
@@ -1329,7 +1332,8 @@
         },
         "x-rh-ipa-hcc": {
           "type": "defs"
-        }
+        },
+        "x-rh-rdn-value": "name"
       },
       "LocationName": {
         "title": "Location identifier (IPA location, AD site)",
@@ -1418,7 +1422,7 @@
       },
       "RealmName": {
         "title": "Kerberos realm name",
-        "description": "A Kerberos realm name (usually all upper-case domain name)",
+        "description": "A Kerberos realm name (usually all upper-case domain name). The realm can only be set during initial registration and not be modified by updates.\n",
         "type": "string",
         "format": "realm",
         "maxLength": 253,
diff --git a/public.openapi.yaml b/public.openapi.yaml
index 7e30c4f..2576b8d 100644
--- a/public.openapi.yaml
+++ b/public.openapi.yaml
@@ -381,7 +381,7 @@ components:
                     format: cert-issuer
                     example: O=DOMAIN.EXAMPLE, CN=Certificate Authority
                 nickname:
-                    title: Internal nick name in LDAP
+                    title: Internal nick name in LDAP (RDN cn)
                     type: string
                     example: DOMAIN.EXAMPLE CA
                 not_after:
@@ -411,6 +411,7 @@ components:
                     example: O=DOMAIN.EXAMPLE, CN=Certificate Authority
             x-rh-ipa-hcc:
                 type: defs
+            x-rh-rdn-value: nickname
         Domain:
             title: Base type for domain objects
             description: A domain resource
@@ -442,6 +443,7 @@ components:
                     $ref: '#/components/schemas/DomainIpa'
             x-rh-ipa-hcc:
                 type: defs
+            x-rh-rdn-value: domain_name
             example:
                 description: My awesome domain description.
                 auto_enrollment_enabled: true
@@ -559,6 +561,7 @@ components:
             x-rh-ipa-hcc:
                 name: IPAServer
                 type: defs
+            x-rh-rdn-value: fqdn
             example:
                 ca_server: true
                 fqdn: ipaserver.mydomain.example
@@ -569,7 +572,10 @@ components:
                 subscription_manager_id: 03965a2c-bd24-11ed-968d-482ae3863d30
         DomainName:
             title: Fully qualified domain name
-            description: A name of a domain (all lower-case)
+            description: >
+                A name of a domain (all lower-case). The domain name can only
+                be set during initial registration and not be modified by
+                updates.
             type: string
             format: idn-hostname
             maxLength: 253
@@ -943,6 +949,7 @@ components:
                     type: string
             x-rh-ipa-hcc:
                 type: defs
+            x-rh-rdn-value: name
         LocationName:
             title: Location identifier (IPA location, AD site)
             description: A location identifier (lower-case DNS label)
@@ -1014,7 +1021,10 @@ components:
                 offset: 0
         RealmName:
             title: Kerberos realm name
-            description: A Kerberos realm name (usually all upper-case domain name)
+            description: >
+                A Kerberos realm name (usually all upper-case domain name).
+                The realm can only be set during initial registration and not
+                be modified by updates.
             type: string
             format: realm
             maxLength: 253