feat(docs): expand TDF documentation by marythought · Pull Request #225 · opentdf/docs

marythought · 2026-03-04T01:13:19Z

Preview: https://opentdf-docs-pr-225.surge.sh/sdks/tdf

Summary

Restructures the TDF page as a proper API reference with signature, parameter table, returns, errors, and working code example per method
Adds a Quick Start section with SDK initialization and end-to-end encrypt/decrypt in Go, Java, and JavaScript
Adds a page intro with a linked map of all sections
Methods documented: CreateTDF, LoadTDF, IsValidTdf, BulkDecrypt / PrepareBulkDecrypt (Go), and all TDF Reader methods
Adds Type Reference section grouping KASInfo, PolicyObject, and Manifest Object with field tables — clearly separated from callable methods in the TOC
Improves prose throughout: explains KAS with a link to the component docs, clarifies what key wrapping and ephemeral session keys mean, expands assertion examples from STANAG-only to generic JSON with signing key code
Replaces example attribute FQNs (classification/secret) with clearance/executive across all SDK pages
Adds complete imports to all code blocks across tdf.mdx, encrypt_options.mdx, decrypt_options.mdx

Test plan

Page intro renders with working anchor links to all sections
Quick Start renders with working tabs for Go, Java, JavaScript
All method sections render with signature tabs, parameter table, returns, errors, and example
Type Reference section renders with field tables for KASInfo, PolicyObject, Manifest Object
Encrypt Options and Decrypt Options import and render correctly
TOC shows only method names and Type Reference — not Signature/Parameters/Returns/Errors
No broken anchors or MDX errors in build output

🤖 Generated with Claude Code

gemini-code-assist · 2026-03-04T01:13:54Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the TDF documentation, providing developers with comprehensive guidance on encrypting and decrypting data using the Trusted Data Format. It clarifies various configuration options across Go, Java, and TypeScript SDKs and introduces a new section on inspecting TDF metadata without requiring full decryption, making it easier for users to understand and implement TDF functionalities.

Highlights

Expanded TDF Documentation Introduction: An introductory paragraph was added to explain the TDF structure and the content covered on the page, providing a clearer starting point for users.
Comprehensive Encrypt Options: The documentation now includes a full set of encrypt options across Go, Java, and TypeScript SDKs, detailing various configurations for TDF creation.
Comprehensive Decrypt Options: The documentation now includes a full set of decrypt options across Go, Java, and TypeScript SDKs, outlining how to control TDF opening and validation.
New 'Inspecting a TDF Without Decrypting' Section: A new section was added that demonstrates how to read a TDF's manifest, policy, and attributes without requiring a key access request or full decryption.
Prerequisites Tip Added: A 'Prerequisites' tip was included, linking directly to the SDK Quickstart guide to ensure users have the necessary setup before proceeding with TDF examples.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

code_samples/tdf/decrypt_options.mdx
- Added comprehensive documentation for TDF decryption options, covering KAS allowlist, assertion verification, session key types, fulfillable obligations, max manifest size, and methods for reading decrypted payload and metadata.
code_samples/tdf/encrypt_options.mdx
- Added comprehensive documentation for TDF encryption options, detailing data attributes, KAS configuration, autoconfigure, key splitting, metadata, MIME type, segment size, assertions, wrapping key algorithm, and TDF spec version.
docs/sdks/tdf.mdx
- Updated the main TDF documentation page by adding an introductory explanation, integrating new encrypt and decrypt options, including a prerequisites tip, and introducing sections for inspecting TDFs without decryption and bulk decryption for Go.

Activity

No human activity (comments, reviews, etc.) has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request significantly expands the TDF documentation, which is a great improvement. The new content on encrypt and decrypt options, as well as inspecting TDFs, will be very helpful for users. My review focuses on improving the clarity and correctness of the new documentation by pointing out some formatting issues with Docusaurus admonitions and several inconsistencies or errors in the code samples, such as incorrect method capitalization in Java examples and missing imports in Go examples. Addressing these points will make the documentation more polished and easier for developers to use.

code_samples/tdf/decrypt_options.mdx

code_samples/tdf/encrypt_options.mdx

docs/sdks/tdf.mdx

jp-ayyappan

Maybe my feedback is a big fat nothing-burger. I am not sure I have a good opinion on whether we should really expose the fact that implementation of features varies between SDKs

I am ok with hiding that information for now.

code_samples/tdf/encryption.mdx

docs/sdks/tdf.mdx

jp-ayyappan · 2026-03-05T17:26:46Z

docs/sdks/tdf.mdx

+        System.out.println("Attribute: " + attr.attribute);
+    }
+}
+```


Do we not have this implemented in JS /TS? Maybe call that out?

it looks like we do -- added

- Adds intro paragraph explaining TDF structure and page scope - Imports and displays encrypt options and decrypt options sections - Adds "Inspecting a TDF Without Decrypting" section (Go, Java, TypeScript) - Adds Prerequisites tip linking to SDK Quickstart Closes DSPX-2427 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ction Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…meter tables Add method signatures, parameter tables, return values, and error descriptions for CreateTDF, LoadTDF, IsValidTdf, BulkDecrypt, and TDF Reader methods. Replace the top-level narrative structure with per-method API reference blocks followed by the existing encrypt and decrypt options detail sections. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…rypt examples - Remove unused client.open() from JavaScript metadata example in decrypt_options.mdx - Add ctx := context.Background() to BulkDecrypt and PrepareBulkDecrypt Go snippets Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Link prose mentions of TDF reader, TDFReader, PolicyObject, and Manifest Object to their respective reference sections - Fix broken anchor #manifest--getmanifest--... → #manifest - Fix HTML entities for List<Type> in PolicyObject table to prevent MDX JSX parse errors Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Signature, Parameters, Returns, Errors, Example, and type-reference field headings were ### headings, polluting the TOC and visually competing with method names. Changed to bold text so only method names and TDF Reader sub-methods appear in the page outline. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

HTML entities inside backtick code spans render literally. Real angle brackets inside backticks are safe from MDX JSX parsing. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Both sections previously said "wrap the data encryption key" or "ephemeral session key" without explaining the underlying mechanism. Added plain-language explanations of the DEK wrapping flow and the ephemeral key exchange, and what rsa:2048 means as an identifier. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…oss SDK pages Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

decrypt_options.mdx included a full Reading the Decrypted Payload section (Payload, Unencrypted Metadata, Policy Object, Data Attributes, Manifest) that was already covered by TDF Reader in tdf.mdx. Removing it eliminates 3 duplicate heading anchors on the composed page. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Add Quick Start section with SDK initialization and end-to-end encrypt/decrypt example in Go, Java, and JavaScript - Add JavaScript source type table (buffer, stream) to LoadTDF parameters - Replace unhelpful Java IOException table with a plain note - Replace STANAG 5636 assertion example with generic application/json - Add signing key code examples for assertions (Go, Java, JavaScript) - Add KAS link and explanation to KAS Configuration option description - Group KASInfo, PolicyObject, Manifest Object under ## Type Reference to clearly distinguish types from callable methods in the TOC Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Add **Errors** sub-section to IsValidTdf (was missing) - Fix broken anchor: #validate-attributes → #validateattributes - Correct CreateTDF Go signature: io.Reader → io.ReadSeeker, *Manifest → *TDFObject (matches actual sdk/tdf.go:139) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Cross-checked all documented signatures against the Go, Java, and JS SDK source. Fixed the following discrepancies: - Go: BulkDecrypt/PrepareBulkDecrypt receivers (client *SDK → s SDK) - Go: PrepareBulkDecrypt return type (*PreparedBulkDecrypt → *BulkDecryptPrepared) - Go: Reader.Manifest() return type (*Manifest → Manifest, value not pointer) - Java: createTDF return type (void → Manifest) - Java: createTDF exceptions (AutoConfigureException → SDKException) - Java: loadTDF/isTDF channel type (ReadableByteChannel → SeekableByteChannel) - Java: isTDF removes throws IOException (method doesn't declare it) - Java: readPolicyObject removes throws IOException (method doesn't declare it) - JS: createZTDF return type (Promise<ReadableStream> → Promise<DecoratedStream>) Also updated the Java createTDF example to capture the Manifest return value. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Re-verified all TDF SDK method signatures against the main branch of each SDK repository (opentdf/platform, opentdf/java-sdk, opentdf/web-sdk) via gh api. Fixed remaining discrepancies: - Go Reader.Policy(): *policy.PolicyObject → PolicyObject (SDK-local value type, not a pointer to the protobuf type from protocol/go/policy) - Java createTDF: TDFConfig → Config.TDFConfig (inner class, not top-level) - Java loadTDF: TDFReaderConfig → Config.TDFReaderConfig (inner class) - Java reader.readPayload: add SDK.SegmentSignatureMismatch to throws clause (declared in source alongside IOException) Skipped parameter-name differences (w vs writer, opts vs options, etc.) as these do not affect callers and the documented names are more descriptive. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Adds compile-only type-assertion tests for the OpenTDF Go (v0.13.0) and TypeScript (v0.4.0) SDKs, plus a GitHub Actions workflow that runs them on every PR touching docs/sdks/ or the test files themselves. A type mismatch in a documented signature produces a build error, making future SDK API drift detectable before publishing. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Remove "ztdf" from the filename per reviewer feedback. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

File was never imported anywhere in the docs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Clarify IsValidTdf description: validates ZIP structure + manifest schema; no HMAC check, no KAS contact, no payload decryption - Retitle the manifest-inspection note to be SDK-neutral - Add JS/TS equivalent showing TDFReader.manifest() / .attributes() work without triggering decryption (per jp-ayyappan feedback) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

marythought requested review from a team as code owners March 4, 2026 01:13

gemini-code-assist bot reviewed Mar 4, 2026

View reviewed changes

pflynn-virtru previously approved these changes Mar 5, 2026

View reviewed changes

jp-ayyappan reviewed Mar 5, 2026

View reviewed changes

marythought dismissed pflynn-virtru’s stale review via bd0bc31 March 5, 2026 19:58

marythought requested a review from a team as a code owner March 6, 2026 00:19

marythought and others added 22 commits March 5, 2026 16:43

Remove OpenTDF brand reference from tdf.mdx prose for DSP import

94f3007

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Remove prerequisites callout; add intro to Basic Encrypt & Decrypt se…

e4660f4

…ction Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

add necessary imports to all Go, Java, and TypeScript code blocks

8bdd08d

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

add Manifest Object reference section with field tables and example

a56664a

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

add KASInfo and PolicyObject type reference sections

e3e17b8

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix: use real angle brackets inside backtick spans in PolicyObject table

3f7bb32

HTML entities inside backtick code spans render literally. Real angle brackets inside backticks are safe from MDX JSX parsing. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: replace classification/secret FQNs with clearance/executive acr…

0549343

…oss SDK pages Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(tdf): add page intro with section map and remove auth guide link

1dd72ea

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

rename: code_samples/tdf/encryption_ztdf.mdx → encryption.mdx

5983771

Remove "ztdf" from the filename per reviewer feedback. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

remove: delete unused code_samples/tdf/encryption.mdx

a7b7729

File was never imported anywhere in the docs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

marythought force-pushed the docs/DSPX-2427-expand-tdf-documentation branch from 96b41d0 to 2b5883e Compare March 6, 2026 00:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docs): expand TDF documentation#225

feat(docs): expand TDF documentation#225
marythought wants to merge 23 commits intomainfrom
docs/DSPX-2427-expand-tdf-documentation

marythought commented Mar 4, 2026 •

edited

Loading

Uh oh!

gemini-code-assist bot commented Mar 4, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jp-ayyappan left a comment

Uh oh!

Uh oh!

Uh oh!

jp-ayyappan Mar 5, 2026

Uh oh!

marythought Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

marythought commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

gemini-code-assist bot commented Mar 4, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jp-ayyappan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jp-ayyappan Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

marythought Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

marythought commented Mar 4, 2026 •

edited

Loading