From 4e3a2a30976b6a98680b9dd2fb8755a444dfc577 Mon Sep 17 00:00:00 2001 From: Agustin Bettati Date: Fri, 12 Jun 2026 16:00:09 +0200 Subject: [PATCH] feat(ipa): Decouple property descriptions from API mechanics in IPA-117 Adds guidance that descriptions should be meaningful to API consumers rather than coupled to API mechanics (operation IDs, request/response object names, endpoint paths), and that a property's description should be consistent across oneOf variants, so downstream tooling does not need description overrides. CLOUDP-412565 --- ipa/general/0117.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/ipa/general/0117.md b/ipa/general/0117.md index d19b9f5..25aea2b 100644 --- a/ipa/general/0117.md +++ b/ipa/general/0117.md @@ -31,6 +31,29 @@ will promote clarity, completeness and consistency. - Descriptions **must** avoid company internal language conventions - Descriptions **should** prefer simple syntax that can easily be translated for non-English speakers +- Descriptions **should** describe fields in terms meaningful to API consumers, + not in terms of API mechanics. Referencing other API-specific constructs + couples the description to tooling context that is not visible to end users of + generated clients and forces downstream tooling to override the text. + + **Anti-pattern** (references an operation ID and endpoint path): + + > Unique 24-hexadecimal digit string that identifies the organization that + > contains your projects. Use the + > [`/orgs`](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Organizations/operation/listOrganizations) + > endpoint to retrieve all organizations to which the authenticated user has + > access. + + **Preferred** (consumer-facing, no API mechanics): + + > Unique 24-hexadecimal digit string that identifies the organization that + > contains your projects. + +- When the same property appears in multiple polymorphic variants unified by + `oneOf` with a discriminator (see [IPA-125](0125.md)), that property's + description **should** be identical across variants. Variant-specific context + **should** be documented in the variant schema's own `description`, not by + diverging the property's description between variants. - See [Description Object](https://www.learnjsonschema.com/2020-12/meta-data/description/) - Documentation **may** link to external documentation when more in-depth