From 9d70a64e02882d8aa63ed3cd05350b788c801bab Mon Sep 17 00:00:00 2001
From: badra001 <donald.e.badrak.ii@census.gov>
Date: Thu, 28 Aug 2025 16:52:57 -0400
Subject: [PATCH] add sample yaml file docs (start)

---
 group-assignment/sample.md  | 102 ++++++++++++++++++++++++++++++++++++
 group-assignment/sample.yml |   2 +
 2 files changed, 104 insertions(+)
 create mode 100644 group-assignment/sample.md

diff --git a/group-assignment/sample.md b/group-assignment/sample.md
new file mode 100644
index 0000000..a83161d
--- /dev/null
+++ b/group-assignment/sample.md
@@ -0,0 +1,102 @@
+# AWS Identity Center Group YAML File
+
+This describe the format of the YAML file used in setting up AWS Identity Center (IDC, aka, SSO) groups.
+This is used by the [aws-sso//group-assignment](.) submodule.
+
+```yaml
+group: NAME
+description: string
+permissionset_name: string
+usage:
+documentation_url:
+all: false
+account_names: []
+account_ids: []
+auto_policy_count: null
+org_ous: []
+user_mapping: {}
+users: []
+```
+
+## group
+
+This is of type _string_.  The group field is the name for IDC group display. It should be in lowercase with dashes and follow the format
+similar to the [Base Label Format](https://github.e.it.census.gov/terraform/cloud-information/tree/master/aws/documentation/naming-tagging-standard#base-label-format):
+
+{business-label]-{application-label}-[{environmenat-label}-]{function}-[t{tier}]
+
+The environment label is generally stripped from the group, as we want there to be a single group applying to multiple AWS accounts with the same
+set of permissions.
+
+* TBD
+  * environemnt
+  * function
+  * tier
+  * sc- groups
+
+Examples:
+
+* adsd-dapps-sc-dba
+* csvd-servicecatalog-admin-t2
+* tco-iac-cloudflare-dns
+
+## description
+
+This is of type _string_.  It is a short description of the group, and should include (properly cased) the same primary
+fields in the group name with additional wording. This goes into the `description` field in the SSO group, and will added to the 
+created LDAP group.
+
+## permissionset_name
+
+This is of type _string_.
+
+## usage
+
+This is of type _string_. This is a description of the audience for whom the group is intended.  It is expected to be a short sentence, but
+could also be several sentences.  You can use a multi-line YAML to enable such a thing.
+
+Examples
+
+```yaml
+usage: "Intended for developer access to common permissions"
+
+usage: |
+  This is for level 3 administrators to the product, and not intended for general purpose end users.
+  This grants extra permissions over the level 2 administrators.
+```
+
+## documentation_url
+
+This is of type _string_.  This is the URL where one can find additional documentation on the specific group.
+
+## all
+
+This is of type _boolean_.
+
+## account_names
+
+This is of type _list of strings_.
+
+## account_ids
+
+This is of type _list of strings_.
+
+## auto_policy_count
+
+null or number
+
+## org_ous
+
+This is of type _list of strings_.
+
+## user_mapping
+
+
+## users
+
+This is of type _list of strings_.
+
+# CHANGELOG
+
+* 1.0.0 -- 2025-08-28
+  - initial
diff --git a/group-assignment/sample.yml b/group-assignment/sample.yml
index 8765789..8e4439f 100644
--- a/group-assignment/sample.yml
+++ b/group-assignment/sample.yml
@@ -1,6 +1,8 @@
 group: NAME
 description: string
 permissionset_name: string
+usage: string
+documentation_url: URL
 all: true
 account_names: []
 account_ids: []