docs: clarify permissive-in strict-out naming policy#581
docs: clarify permissive-in strict-out naming policy#581Rohan5commit wants to merge 1 commit intomicrosoft:vNextfrom
Conversation
There was a problem hiding this comment.
Pull request overview
Adds guidance to the Microsoft Graph naming section to document a “permissive-in / strict-out” approach when services accept multiple input variants but produce a single canonical output form.
Changes:
- Adds an “Input and output handling” subsection under Naming.
- Defines guidance for accepting equivalent input forms while emitting canonical outputs.
- Requires documentation to describe canonical outputs and accepted variants.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Services **MUST** emit a single canonical form in responses, notifications, and examples so customers see one stable shape on output. | ||
| - Documentation **SHOULD** call out both the canonical output form and any accepted input variants whenever the service intentionally accepts more than one form. |
There was a problem hiding this comment.
The bullet says services MUST emit a single canonical form "in responses, notifications, and examples". Services don’t emit documentation examples, so this mixes responsibilities. Consider limiting the service requirement to runtime outputs (responses/notifications) and moving the examples requirement to the documentation bullet below (or rephrasing it as "Documentation examples MUST use the canonical form").
| - Services **MUST** emit a single canonical form in responses, notifications, and examples so customers see one stable shape on output. | |
| - Documentation **SHOULD** call out both the canonical output form and any accepted input variants whenever the service intentionally accepts more than one form. | |
| - Services **MUST** emit a single canonical form in responses and notifications so customers see one stable shape on output. | |
| - Documentation **SHOULD** call out the canonical output form, use the canonical form in examples, and describe any accepted input variants whenever the service intentionally accepts more than one form. |
Summary
Add a short "Input and output handling" subsection to the Graph naming guidelines to document a permissive-in / strict-out policy for naming variants.
Related issue
Fixes #571
Guideline alignment
Read
CONTRIBUTING.mdand targeted thevNextbranch with a focused one-file documentation change.Validation
git diff --check