chore(docs): restructure Policy page and extract Obligations#281
Merged
marythought merged 4 commits intomainfrom Apr 8, 2026
Merged
chore(docs): restructure Policy page and extract Obligations#281marythought merged 4 commits intomainfrom
marythought merged 4 commits intomainfrom
Conversation
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (9)
📝 WalkthroughWalkthroughStandardized and simplified multiple policy-code MDX docs: added Signature/Parameters/Returns sections, replaced full client-setup examples with concise per-language call-site snippets for create/list operations, and added a new comprehensive Obligations API documentation page. All changes are documentation-only. Changes
Sequence Diagram(s)(Skipped — documentation-only changes; no new multi-component control flow to visualize.) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~18 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request standardizes the documentation for policy-related operations by introducing a consistent structure for signatures, parameters, examples, and return values across multiple MDX files. It also adds a comprehensive new guide for the Obligations service. The review feedback identifies several instances where Go and Java code snippets are missing essential imports, such as context, log, and java.util.Collections, which are required for the examples to be self-contained and executable.
Contributor
|
📄 Preview deployed to https://opentdf-docs-pr-281.surge.sh |
Contributor
Author
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
code_samples/policy_code/list_attributes.mdx (1)
68-70:⚠️ Potential issue | 🟠 MajorImported Java example doesn't match documented parameters.
The parameter table documents
namespaceId(UUID),state,pagination.limit, andpagination.offset, but the Java example uses.setNamespace(namespaceName)with a string name instead of a UUID and doesn't demonstrate pagination or state filtering. Update the Java example to align with the documented parameter contract, or update the parameter table to match what the example actually uses.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@code_samples/policy_code/list_attributes.mdx` around lines 68 - 70, The imported Java example (ListAttributesExample in `@site/code_samples/java/list-attributes.mdx`) doesn't match the documented params—replace the current .setNamespace(namespaceName) usage with the UUID-based parameter (e.g., .setNamespaceId(UUID.fromString(...)) or the method that accepts a UUID), and add examples showing state filtering and pagination (use the request builder/methods for state and pagination.limit/pagination.offset) so the Java sample demonstrates namespaceId (UUID), state, pagination.limit, and pagination.offset as documented; alternatively, if the Java client API truly lacks UUID/ pagination/state params, update the parameter table to reflect the actual Java method names/types instead.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@code_samples/policy_code/create_attribute.mdx`:
- Line 40: The `values` field description is a sentence fragment; update the
`values` entry (type `[]string`) so it reads as a complete sentence—for example:
state that these are the initial values to create with the attribute and end
with a period, and follow with a separate complete sentence noting that values
can also be added later via the "Create an Attribute Value" link; update the
line in create_attribute.mdx for the `values` description accordingly so it
conforms to Vale prose style.
In `@code_samples/policy_code/create_subject_condition_set.mdx`:
- Around line 35-38: Update the parameter table to match the actual request
shape used in the examples by changing the top-level parameter name from
`subjectSets` to `subjectConditionSet.subjectSets` (or `subjectConditionSet`
with a nested `subjectSets` row if you prefer), and ensure the description and
"Required" flag reflect that `subjectSets` is nested under
`subjectConditionSet`; update the Parameter column entry and any example links
referencing `subjectSets` so they reference the nested path used by the examples
(look for `subjectConditionSet` and `subjectSets` in the file to locate where to
change).
In `@code_samples/policy_code/create_subject_mapping.mdx`:
- Around line 39-40: Update the parameter table so that both
`existingSubjectConditionSetId` and `newSubjectConditionSet` are marked as
conditional-required (e.g., change their "Yes*" status to indicate "Yes*" for
both), and adjust the description for each to state they are mutually exclusive
and required only when the other is absent (e.g., for
`existingSubjectConditionSetId` add "Required unless `newSubjectConditionSet` is
provided" and for `newSubjectConditionSet` add "Required unless
`existingSubjectConditionSetId` is provided; mutually exclusive"). Ensure the
symbols `existingSubjectConditionSetId` and `newSubjectConditionSet` are updated
in the table and descriptions to reflect this conditional-required semantics.
- Around line 67-70: The snippet assigns to err without declaration; change the
assignment to use a short variable declaration so Go compiles — replace the
current call to SubjectMapping.CreateSubjectMapping (the line with _, err =
client.SubjectMapping.CreateSubjectMapping(context.Background(),
subjectMapping)) with a short-declare form (using := for the returned values,
e.g., assigning the first return to _ and err via :=) so CreateSubjectMapping
and err are declared correctly before the subsequent log.Fatal(err) check.
In `@code_samples/policy_code/list_namespaces.mdx`:
- Around line 113-115: The example call to platform.v1.namespace.listNamespaces
uses the wrong enum string; change the state property in the object passed to
platform.v1.namespace.listNamespaces from 'ACTIVE_STATE_ENUM_INACTIVE' to one of
the documented values ('ACTIVE', 'INACTIVE', or 'ANY') so it matches the table
convention (e.g., set state: 'INACTIVE').
In `@docs/sdks/obligations.mdx`:
- Line 331: The `values` parameter description is a sentence fragment; update
the `values` row in the obligations table so the fragment becomes a full
sentence—e.g., change "Can also be added later via [Create Obligation
Value](`#create-obligation-value`)." to a complete sentence such as "They can also
be added later via [Create Obligation Value](`#create-obligation-value`)." Ensure
the `values` cell reads as one or two complete sentences and passes Vale linting
for docs.
---
Outside diff comments:
In `@code_samples/policy_code/list_attributes.mdx`:
- Around line 68-70: The imported Java example (ListAttributesExample in
`@site/code_samples/java/list-attributes.mdx`) doesn't match the documented
params—replace the current .setNamespace(namespaceName) usage with the
UUID-based parameter (e.g., .setNamespaceId(UUID.fromString(...)) or the method
that accepts a UUID), and add examples showing state filtering and pagination
(use the request builder/methods for state and
pagination.limit/pagination.offset) so the Java sample demonstrates namespaceId
(UUID), state, pagination.limit, and pagination.offset as documented;
alternatively, if the Java client API truly lacks UUID/ pagination/state params,
update the parameter table to reflect the actual Java method names/types
instead.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 4df1c091-3551-4005-8d6e-63605a7760c1
📒 Files selected for processing (9)
code_samples/policy_code/create_attribute.mdxcode_samples/policy_code/create_namespace.mdxcode_samples/policy_code/create_subject_condition_set.mdxcode_samples/policy_code/create_subject_mapping.mdxcode_samples/policy_code/list_attributes.mdxcode_samples/policy_code/list_namespaces.mdxcode_samples/policy_code/list_subject_mapping.mdxdocs/sdks/obligations.mdxdocs/sdks/policy.mdx
- Add Setup section with client init for Go, Java, JS - Add shared type docs: Metadata, Pagination, Action, Condition Structure - Strip SDK init boilerplate from all examples and imported code samples - Add Signature/Parameters/Example/Returns to all 28 Policy operations - Add type reference tables: Namespace, Attribute, Attribute Value, Subject Condition Set (with full condition tree), Subject Mapping, Action, SubjectProperty - Extract Obligations into own page with full structured docs for all 14 operations and 3 type references Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Use full ActiveStateEnum values in parameter tables (ACTIVE_STATE_ENUM_*) - Fix subjectSets parameter path to subjectConditionSet.subjectSets - Mark newSubjectConditionSet as Yes* (conditionally required) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
marythought
force-pushed
the
chore/274-c-policy-restructure
branch
from
34521e7 to
4b11b22
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Major restructure of the Policy SDK page and extraction of Obligations.
preview:
https://opentdf-docs-pr-281.surge.sh/sdks/policy
https://opentdf-docs-pr-281.surge.sh/sdks/obligations
Policy Page
Obligations Page (new)
Part of #274 (task 4)
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit