From 2929fe893c313143375c16de62b0e9bc76d80af9 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Mon, 22 Jun 2026 13:17:06 -0700 Subject: [PATCH 1/5] feat(docs): document Resource Mapping Groups and FQN format Add Resource Mapping Groups section to the resource_mappings page covering group composition, FQN format (https:///resm/), CLI usage for creating groups and assigning mappings, and usage as synonym dictionaries. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/components/policy/resource_mappings.md | 56 ++++++++++++++++++++- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/docs/components/policy/resource_mappings.md b/docs/components/policy/resource_mappings.md index e6f14a20..a557198f 100644 --- a/docs/components/policy/resource_mappings.md +++ b/docs/components/policy/resource_mappings.md @@ -6,11 +6,63 @@ A Resource Mapping contains: 1. An associated `attribute value`. 2. A set of related `terms`. +3. An optional `group` (see [Resource Mapping Groups](#resource-mapping-groups) below). The primary consumer of a Resource Mapping is a Policy Decision Point (PDP), which processes data, applies logic using the known terms, and relies on them to map the data to Attribute Values. By mapping a set of terms to a given attribute value, a Policy Enforcement Point (PEP) can properly apply the TDF to the resource data using the appropriate attribute values. -# Examples +## Examples -Alice is a system administrator. She defines an Attribute definition called color with values like red, green, blue, purple, etc. For the Attribute Value `https://demo.com/attr/color/value/purple'`, she would define a Resource Mapping for processing data that may involve terms like `indigo`, `lilac`, `plum`, or `lavender`. +Alice is a system administrator. She defines an Attribute definition called color with values like red, green, blue, purple, etc. For the Attribute Value `https://demo.com/attr/color/value/purple`, she would define a Resource Mapping for processing data that may involve terms like `indigo`, `lilac`, `plum`, or `lavender`. Bob is a system administrator in the US Department of Defense (DoD). Bob defines a hierarchical attribute called classification with values of `topsecret`, `secret`, `confidential`, and `unclassified`. He needs to create a resource mapping that defines a normalization of the various short forms and acronyms that map to each of these classification levels. For the `topsecret` attribute value, he might include terms like `ts`, `top secret`, and `top-secret`. Whereas for unclassified he might include `u`, `uc`, or other variations. + +## Resource Mapping Groups + +Resource Mapping Groups organize multiple Resource Mappings into logical collections under a [Namespace](./attributes#namespaces). Groups allow you to manage sets of related mappings together, which is useful when resources share common access controls or need to be managed as a unit. + +A Resource Mapping Group contains: + +1. A **name** identifying the group. +2. A **namespace** that the group belongs to. +3. A **Fully Qualified Name (FQN)** derived from the namespace and group name. + +### FQN Format + +Each Resource Mapping Group has a unique FQN following this pattern: + +``` +https:///resm/ +``` + +For example, a group named `ntk` under the namespace `example.org` would have the FQN: + +``` +https://example.org/resm/ntk +``` + +Like other FQN'd objects in the platform, Resource Mapping Group FQNs are normalized to lower case. + +:::note FQN visibility in the CLI +The `otdfctl` CLI does not currently display the FQN when listing or getting Resource Mapping Groups. To determine a group's FQN, construct it from the namespace and group name using the format above. +::: + +### Creating a Group and Assigning Mappings + +Groups are created under a namespace, and individual Resource Mappings can be assigned to a group at creation or update time: + +```bash +# Create a resource mapping group +otdfctl policy resource-mapping-groups create \ + --namespace-id \ + --name my-group + +# Create a resource mapping assigned to the group +otdfctl policy resource-mappings create \ + --attribute-value-id \ + --terms "term1,term2,term3" \ + --group-id +``` + +### Using Groups as Synonym Dictionaries + +A Resource Mapping Group's FQN can be used as a synonym dictionary identifier in systems that resolve term-to-attribute-value mappings. When referenced by FQN, the system retrieves all Resource Mappings within that group from the policy database, enabling database-backed synonym resolution rather than inline configuration. From 0faf858b35b2cf9786a9c88a78ed3478f6c84199 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Mon, 22 Jun 2026 16:14:35 -0700 Subject: [PATCH 2/5] fix(docs): add .md extension to relative link and language specifiers Address Gemini and CodeRabbit review feedback: - Use ./attributes.md#namespaces for build-time link validation - Add text language specifier to FQN code blocks (MD040) Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/components/policy/resource_mappings.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/components/policy/resource_mappings.md b/docs/components/policy/resource_mappings.md index a557198f..2ba63271 100644 --- a/docs/components/policy/resource_mappings.md +++ b/docs/components/policy/resource_mappings.md @@ -18,7 +18,7 @@ Bob is a system administrator in the US Department of Defense (DoD). Bob defines ## Resource Mapping Groups -Resource Mapping Groups organize multiple Resource Mappings into logical collections under a [Namespace](./attributes#namespaces). Groups allow you to manage sets of related mappings together, which is useful when resources share common access controls or need to be managed as a unit. +Resource Mapping Groups organize multiple Resource Mappings into logical collections under a [Namespace](./attributes.md#namespaces). Groups allow you to manage sets of related mappings together, which is useful when resources share common access controls or need to be managed as a unit. A Resource Mapping Group contains: @@ -30,13 +30,13 @@ A Resource Mapping Group contains: Each Resource Mapping Group has a unique FQN following this pattern: -``` +```text https:///resm/ ``` For example, a group named `ntk` under the namespace `example.org` would have the FQN: -``` +```text https://example.org/resm/ntk ``` From ecc45fb304d5bf8757179f1176f8f98400e657b7 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 23 Jun 2026 07:57:13 -0700 Subject: [PATCH 3/5] chore: trigger surge preview rebuild From bf0b8c496cf0f92ec636e2d800ca5846f1dc8ea8 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 23 Jun 2026 08:14:32 -0700 Subject: [PATCH 4/5] fix(docs): use classification example in CLI snippet Tie the CLI example to Bob's DoD classification scenario from earlier in the page instead of using generic placeholders. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/components/policy/resource_mappings.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/components/policy/resource_mappings.md b/docs/components/policy/resource_mappings.md index 2ba63271..d58958c4 100644 --- a/docs/components/policy/resource_mappings.md +++ b/docs/components/policy/resource_mappings.md @@ -48,21 +48,23 @@ The `otdfctl` CLI does not currently display the FQN when listing or getting Res ### Creating a Group and Assigning Mappings -Groups are created under a namespace, and individual Resource Mappings can be assigned to a group at creation or update time: +Groups are created under a namespace, and individual Resource Mappings can be assigned to a group at creation or update time. Building on Bob's classification example from above: ```bash -# Create a resource mapping group +# Create a resource mapping group for classification terms under Bob's namespace otdfctl policy resource-mapping-groups create \ - --namespace-id \ - --name my-group + --namespace-id \ + --name classification -# Create a resource mapping assigned to the group +# Create a resource mapping for "topsecret" terms, assigned to the group otdfctl policy resource-mappings create \ - --attribute-value-id \ - --terms "term1,term2,term3" \ - --group-id + --attribute-value-id \ + --terms "ts,top secret,top-secret" \ + --group-id ``` +This group's FQN would be `https:///resm/classification`, and it can be referenced by that FQN to resolve all classification term mappings from the database. + ### Using Groups as Synonym Dictionaries A Resource Mapping Group's FQN can be used as a synonym dictionary identifier in systems that resolve term-to-attribute-value mappings. When referenced by FQN, the system retrieves all Resource Mappings within that group from the policy database, enabling database-backed synonym resolution rather than inline configuration. From 056bde4a9f3ca4ece3c8effc703fee2e92e3bdeb Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 23 Jun 2026 08:16:01 -0700 Subject: [PATCH 5/5] fix(docs): rename examples to Alex and Beth, fix pronouns Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/components/policy/resource_mappings.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/components/policy/resource_mappings.md b/docs/components/policy/resource_mappings.md index d58958c4..6cc64917 100644 --- a/docs/components/policy/resource_mappings.md +++ b/docs/components/policy/resource_mappings.md @@ -12,9 +12,9 @@ The primary consumer of a Resource Mapping is a Policy Decision Point (PDP), whi ## Examples -Alice is a system administrator. She defines an Attribute definition called color with values like red, green, blue, purple, etc. For the Attribute Value `https://demo.com/attr/color/value/purple`, she would define a Resource Mapping for processing data that may involve terms like `indigo`, `lilac`, `plum`, or `lavender`. +Alex is a system administrator. They define an Attribute definition called color with values like red, green, blue, purple, etc. For the Attribute Value `https://demo.com/attr/color/value/purple`, they would define a Resource Mapping for processing data that may involve terms like `indigo`, `lilac`, `plum`, or `lavender`. -Bob is a system administrator in the US Department of Defense (DoD). Bob defines a hierarchical attribute called classification with values of `topsecret`, `secret`, `confidential`, and `unclassified`. He needs to create a resource mapping that defines a normalization of the various short forms and acronyms that map to each of these classification levels. For the `topsecret` attribute value, he might include terms like `ts`, `top secret`, and `top-secret`. Whereas for unclassified he might include `u`, `uc`, or other variations. +Beth is a system administrator in the US Department of Defense (DoD). Beth defines a hierarchical attribute called classification with values of `topsecret`, `secret`, `confidential`, and `unclassified`. She needs to create a resource mapping that defines a normalization of the various short forms and acronyms that map to each of these classification levels. For the `topsecret` attribute value, she might include terms like `ts`, `top secret`, and `top-secret`. Whereas for unclassified she might include `u`, `uc`, or other variations. ## Resource Mapping Groups @@ -48,10 +48,10 @@ The `otdfctl` CLI does not currently display the FQN when listing or getting Res ### Creating a Group and Assigning Mappings -Groups are created under a namespace, and individual Resource Mappings can be assigned to a group at creation or update time. Building on Bob's classification example from above: +Groups are created under a namespace, and individual Resource Mappings can be assigned to a group at creation or update time. Building on Beth's classification example from above: ```bash -# Create a resource mapping group for classification terms under Bob's namespace +# Create a resource mapping group for classification terms under Beth's namespace otdfctl policy resource-mapping-groups create \ --namespace-id \ --name classification