From a7aa89fe64a1b4913a0ea9e133773560da7e88a4 Mon Sep 17 00:00:00 2001
From: Jake Van Vorhis <83739412+jakedoublev@users.noreply.github.com>
Date: Wed, 14 Aug 2024 14:30:24 -0700
Subject: [PATCH] docs(core): provide subject condition set example (#284)

Resolves #196
---
 .../policy/subject-condition-sets/_index.md   | 12 ++++
 .../policy/subject-condition-sets/create.md   | 66 +++++++++++++++++++
 docs/man/policy/subject-mappings/_index.md    |  5 +-
 3 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/docs/man/policy/subject-condition-sets/_index.md b/docs/man/policy/subject-condition-sets/_index.md
index 2f89eeac..ea354384 100644
--- a/docs/man/policy/subject-condition-sets/_index.md
+++ b/docs/man/policy/subject-condition-sets/_index.md
@@ -7,3 +7,15 @@ command:
     - scs
     - subject-condition-set
 ---
+
+Subject Condition Sets are the logical resolvers of entitlement to attributes.
+
+An SCS contains AND/OR groups of conditions with IN/NOT_IN/CONTAINS logic to be applied against
+a Subject Entity Representation as either their OIDC Access Token claims or the platform's Entity
+Resolution Service (ERS).
+
+They are applied to Attribute Values via Subject Mappings to determine a Subject's entitlement to
+any given attribute on TDF'd data.
+
+For example structure and logical resolution, see `create` subcommand. For information about Subject
+Mappings, see the `subject-mappings` command.
diff --git a/docs/man/policy/subject-condition-sets/create.md b/docs/man/policy/subject-condition-sets/create.md
index a141ae5a..410a32b9 100644
--- a/docs/man/policy/subject-condition-sets/create.md
+++ b/docs/man/policy/subject-condition-sets/create.md
@@ -26,3 +26,69 @@ command:
       description: Destructively replace entire set of existing metadata 'labels' with any provided to this command
       default: false
 ---
+
+### Example Subject Condition Sets
+
+`--subject-sets` example input:
+
+```json
+[
+  {
+    "condition_groups": [
+      {
+        "conditions": [
+          {
+            "operator": 1,
+            "subject_external_values": ["CoolTool", "RadService", "ShinyThing"],
+            "subject_external_selector_value": ".team.name"
+          },
+          {
+            "operator": 2,
+            "subject_external_values": ["marketing"],
+            "subject_external_selector_value": ".org.name"
+          }
+        ],
+        "boolean_operator": 1
+      }
+    ]
+  }
+]
+```
+
+ConditionGroup `boolean_operator` is driven through the API `CONDITION_BOOLEAN_TYPE_ENUM` definition:
+
+| CONDITION_BOOLEAN_TYPE_ENUM | index value | comparison            |
+| --------------------------- | ----------- | --------------------- |
+| AND                         | 1           | all conditions met    |
+| OR                          | 2           | any one condition met |
+
+Condition `operator` is driven through the API `SUBJECT_MAPPING_OPERATOR_ENUM` definition,
+and is evaluated by applying the `subject_external_selector_value` to the Subject entity
+representation (token or Entity Resolution Service response) and comparing the logical operator
+against the list of `subject_external_values`:
+
+| SUBJECT_MAPPING_OPERATOR_ENUM | index value | subject value at selector MUST |
+| ----------------------------- | ----------- | ------------------------------ |
+| IN                            | 1           | be any of the values           |
+| NOT_IN                        | 2           | not be any of the values       |
+| IN_CONTAINS                   | 3           | contain one of the values      |
+
+In the example SCS above, the Subject entity MUST BE represented with a token claim or ERS response
+containing a field at `.team.name` identifying them as team name "CoolTool", "RadService", or "ShinyThing", AND THEY MUST ALSO have a field `org.name` that is NOT "marketing".
+
+This structure if their team name was "CoolTool" and they were entitled might look like:
+
+```json
+{
+  "team": {
+    "name": "CoolTool" // could alternatively be RadService or ShinyThing
+  },
+  "org": {
+    "name": "sales"
+  }
+}
+```
+
+If any condition in the group is not met (such as if `.org.name` were `marketing` instead),
+the condition set would not resolve to true, and the Subject would not be found to be entitled
+to the Attribute Value applicable to this Subject Condition Set via Subject Mapping between.
diff --git a/docs/man/policy/subject-mappings/_index.md b/docs/man/policy/subject-mappings/_index.md
index bd3007ae..3ae092dc 100644
--- a/docs/man/policy/subject-mappings/_index.md
+++ b/docs/man/policy/subject-mappings/_index.md
@@ -7,4 +7,7 @@ command:
     - sm
     - submap
     - subject-mapping
----
\ No newline at end of file
+---
+
+A Subject Mapping (SM) is the relation of a Subject Condition Set (SCS, see `subject-condition-sets` command)
+to an Attribute Value to determine a Subject's Entitlement.