docs: document new description field

Also, explain GECOS syntax requirements.

diff --git a/docs/GROUP_RECORD.md b/docs/GROUP_RECORD.md
index 2ea0b73a365173f29cd379e5b32230a42926ec0c..01800494da7de127f7f9609d6c4fe38742cf78a5 100644 (file)
--- a/docs/GROUP_RECORD.md
+++ b/docs/GROUP_RECORD.md
@@ -22,6 +22,10 @@ UNIX/glibc NSS `struct group`, or the shadow structure `struct sgrp`'s
 `realm` → The "realm" the group belongs to, conceptually identical to the same
 field of user records. A string in DNS domain name syntax.
 
 `realm` → The "realm" the group belongs to, conceptually identical to the same
 field of user records. A string in DNS domain name syntax.
 

+`description` → A descriptive string for the group. This is similar to the
+`realName` field of user records, and accepts arbitrary strings, as long as
+they follow the same GECOS syntax requirements as `realName`.
+

 `disposition` → The disposition of the group, conceptually identical to the
 same field of user records. A string.
 
 `disposition` → The disposition of the group, conceptually identical to the
 same field of user records. A string.
 

diff --git a/docs/USER_RECORD.md b/docs/USER_RECORD.md
index f6d22c217b0026dfd6f3a4cf83b05800b9f3322e..960a82d8949cb846024550f49ae7174736a6057f 100644 (file)
--- a/docs/USER_RECORD.md
+++ b/docs/USER_RECORD.md
@@ -221,12 +221,14 @@ optional, when unset the user should not be considered part of any realm. A
 user record with a realm set is never compatible (for the purpose of updates,
 see above) with a user record without one set, even if the `userName` field matches.
 
 user record with a realm set is never compatible (for the purpose of updates,
 see above) with a user record without one set, even if the `userName` field matches.
 

-`realName` → The real name of the user, a string. This should contain the user's
-real ("human") name, and corresponds loosely to the GECOS field of classic UNIX
-user records. When converting a `struct passwd` to a JSON user record this
-field is initialized from GECOS (i.e. the `pw_gecos` field), and vice versa
-when converting back. That said, unlike GECOS this field is supposed to contain
-only the real name and no other information.
+`realName` → The real name of the user, a string. This should contain the
+user's real ("human") name, and corresponds loosely to the GECOS field of
+classic UNIX user records. When converting a `struct passwd` to a JSON user
+record this field is initialized from GECOS (i.e. the `pw_gecos` field), and
+vice versa when converting back. That said, unlike GECOS this field is supposed
+to contain only the real name and no other information. This field must not
+contain control characters (such as `\n`) or colons (`:`), since those are used
+as record separators in classic `/etc/passwd` files and similar formats.

 
 `emailAddress` → The email address of the user, formatted as
 string. [`pam_systemd`](https://www.freedesktop.org/software/systemd/man/pam_systemd.html)
 
 `emailAddress` → The email address of the user, formatted as
 string. [`pam_systemd`](https://www.freedesktop.org/software/systemd/man/pam_systemd.html)