feat(ipa): Add sensitive fields guidance in IPA-111 and OpenAPI markings in IPA-117 by AgustinBettati · Pull Request #77 · mongodb/ipa

AgustinBettati · 2026-06-17T20:09:10Z

Formalizes how secret-carrying fields (passwords, API keys, credentials) are modeled.

IPA-111 — Sensitive Fields (new subsection): sensitive fields must follow the write-only or reveal-once pattern; a masked display (****, last-4) must be modeled as a separate read-only redacted sibling property, never sharing the raw field's name.
IPA-117 — Sensitive Field Markings (new subsection): use format: password on properties whose value is itself a secret; do not use it on redacted sibling properties.

…ngs in IPA-117 CLOUDP-412562

wtrocki · 2026-06-18T10:02:13Z

+
+Some resource fields carry secrets — passwords, API keys, private credentials.
+The API design **must** prevent accidental exposure of these values in
+responses. Sensitive fields **must** be marked in OpenAPI so that consumers and


[nit] Marked seems vague and not actionable. Do we want to introduce password format?

The new IPA-111-must-mark-sensitive-fields guideline now points to IPA-117 via dependsOn and shows format: password plus writeOnly: true in the examples, so the marking is concrete.

wtrocki · 2026-06-18T10:04:14Z

+the required annotations), and **must** follow one of the following
+information-flow patterns:
+
+- **Write-only.** The client submits the value on [Create](0106.mdx) (or


Can we change format to clearly indicate use cases:
Using given > then:

For use cases when when secret is set by client ... use Write-only....
For backend sent credentials...

Having those without entry conditions can lead to confusion as backend sent credentials (generated) are quite common and we do have active engagements where we will have more of those.

The patterns are now split into atomic guidelines, each stating its entry condition: client supplied secrets use write only, server generated secrets use create response only. (taking big reference from your PR)

wtrocki · 2026-06-18T10:05:47Z

+
+- **Write-only.** The client submits the value on [Create](0106.mdx) (or
+  [Update](0107.mdx)) and the server **must not** return it in any response.
+- **Reveal-once.** For values the client cannot retrieve later (e.g.


"Reveal" would apply more to UI rather than API.
If we handling credentials send by clients then we might not need it revealed (backend can return masked values if we want to). If backend generates password then it is only returned on create (POST) actions.

Renamed the pattern to create response only across the guideline id, body, and references, since it names the actual API behaviour (returned in the Create response, excluded from Get and List)

wtrocki · 2026-06-18T10:07:10Z

+  [Get](0104.mdx) or [List](0105.mdx) responses. Reveal-once is the sanctioned
+  exception to the [schema consistency rule](0101.mdx#resources).
+
+When a masked representation of a sensitive field (e.g. `****` or a last-4


This is likely handling case of updating user password? Can we introduce:

When updating user password..

Added a write only password on Update example to the write only guideline

wtrocki

We are working now on making IPA more friendly to AI agents.
For this IPA we would benefit from introducing the use cases (given, then) fornat.

CC @andmatei to share IPA creator documentaton with more details about format.

yelizhenden-mdb

General feedback: I noticed that most guidelines are currently written in paragraph form. We should structure them so they are lintable where applicable. Ideally, every sentence should function as a distinct, actionable guideline. Could you try refactoring this to follow that approach?

To echo @wtrocki's comment, using a 'Given $\rightarrow$ Then' format will make these guidelines easy to translate into Spectral rules. Even if a specific guideline isn't directly translatable, this structured approach ensures they can be effectively interpreted and applied by AI agents.

wtrocki

Let's hold off with merge for now as team is wrapping refactor to the new format

lovisaberggren · 2026-06-18T14:08:00Z

Just saw Yeliz/Wojciechs comments after I already approved, sorry about that!

The content is good, but I agree with the earlier comments that the format can be adjusted a bit to align with our efforts for the AI agent workflows

Migrate PR #77 content into structured <Guideline> components per CONTRIBUTING.md. Addresses review feedback: atomic guidelines, enforcement prop, correct/incorrect examples, workflows. IPA-111: mark sensitive fields, write-only / reveal-once patterns, redacted sibling properties. IPA-117: use format:password on secrets, not on redacted siblings.

wtrocki · 2026-06-19T12:14:37Z

Created #113 for your convinience.

…-117-sensitive-fields

- Rename reveal-once pattern to create-response-only (API-oriented term, avoids UI 'reveal' connotation) across guideline ID, body, and references. - Add a write-only password-on-Update example to illustrate the common user-credential case. - Set IPA-117 format:password guidelines to enforcement=review (secret identification is a semantic judgment, not deterministically lintable). CLOUDP-412562

AgustinBettati · 2026-06-19T16:02:39Z

@wtrocki thanks for #113. I rebased this PR onto main and adopted your component structure, so the two now carry the same atomic guidelines, examples, and workflows for IPA-111 and IPA-117. Differences on top of yours (besides address comments above):

I restored the create response only exception link to IPA-101 (round trip parity)
Set the two IPA-117 format: password guidelines to enforcement review since secret identification is a semantic judgment rather than a deterministic lint.
Fixed the create response only example, which was marked writeOnly: true. Since writeOnly excludes a field from every response including the Create one, the client could never capture the secret. It is now modeled as readOnly on the Create response schema and absent from the Get and List schemas.

I believe we can continue any adjustment on this PR (and close the related one).

…riteOnly writeOnly excludes a field from all responses, including the Create response, so it cannot express a server-generated secret returned once on creation. Model it as readOnly on the Create response schema and absent from the Get and List schemas instead. CLOUDP-412562

wtrocki

Awesome work!
Closed my PR as example.

[nit] I'm personally not 100% sure if we we need to have two separate IPA for similar terms, but I trust your judgement on this

This was referenced Jun 17, 2026

feat(ipa): Tighten standard method guarantees in IPA-101, IPA-106, IPA-107 and IPA-108 #78

Open

feat(ipa): Add IPA-131 declarative tooling extensions catalog with consuming rules in IPA-124 and IPA-111 #79

Open

feat(ipa): Add sensitive fields guidance in IPA-111 and OpenAPI marki…

c620d81

…ngs in IPA-117 CLOUDP-412562

AgustinBettati force-pushed the CLOUDP-412562-ipa-111-117-sensitive-fields branch from 00bb50c to c620d81 Compare June 17, 2026 20:27

AgustinBettati marked this pull request as ready for review June 18, 2026 09:35

AgustinBettati requested a review from a team as a code owner June 18, 2026 09:35

AgustinBettati requested review from andmatei, andreaangiolillo, drinkbird, maks-m-mongo-leaf, matt-condon, saisundar and wtrocki June 18, 2026 09:35

wtrocki reviewed Jun 18, 2026

View reviewed changes

yelizhenden-mdb reviewed Jun 18, 2026

View reviewed changes

lovisaberggren previously approved these changes Jun 18, 2026

View reviewed changes

wtrocki requested changes Jun 18, 2026

View reviewed changes

wtrocki dismissed lovisaberggren’s stale review via 5c0f635 June 19, 2026 12:05

wtrocki force-pushed the CLOUDP-412562-ipa-111-117-sensitive-fields branch from c620d81 to 5c0f635 Compare June 19, 2026 12:05

wtrocki changed the title ~~feat(ipa): Add sensitive fields guidance in IPA-111 and OpenAPI markings in IPA-117~~ feat(ipa): Add sensitive fields guidance to IPA-111 and IPA-117 Jun 19, 2026

wtrocki mentioned this pull request Jun 19, 2026

feat(ipa): Add sensitive fields guidance to IPA-111 and IPA-117 #113

Closed

AgustinBettati force-pushed the CLOUDP-412562-ipa-111-117-sensitive-fields branch from 5c0f635 to c620d81 Compare June 19, 2026 13:58

AgustinBettati changed the title ~~feat(ipa): Add sensitive fields guidance to IPA-111 and IPA-117~~ feat(ipa): Add sensitive fields guidance in IPA-111 and OpenAPI markings in IPA-117 Jun 19, 2026

AgustinBettati added 2 commits June 19, 2026 16:36

Merge remote-tracking branch 'origin/main' into CLOUDP-412562-ipa-111…

37fda90

…-117-sensitive-fields

wtrocki approved these changes Jun 19, 2026

View reviewed changes

Conversation

AgustinBettati commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wtrocki Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AgustinBettati Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

wtrocki Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AgustinBettati Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

wtrocki Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AgustinBettati Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wtrocki Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AgustinBettati Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

wtrocki left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yelizhenden-mdb left a comment

Choose a reason for hiding this comment

Uh oh!

wtrocki left a comment

Choose a reason for hiding this comment

Uh oh!

lovisaberggren commented Jun 18, 2026

Uh oh!

wtrocki commented Jun 19, 2026

Uh oh!

AgustinBettati commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wtrocki left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AgustinBettati commented Jun 17, 2026 •

edited

Loading

wtrocki Jun 18, 2026 •

edited

Loading

wtrocki Jun 18, 2026 •

edited

Loading

wtrocki Jun 18, 2026 •

edited

Loading

AgustinBettati Jun 19, 2026 •

edited

Loading

wtrocki Jun 18, 2026 •

edited

Loading

wtrocki left a comment •

edited

Loading

AgustinBettati commented Jun 19, 2026 •

edited

Loading