docs: clarify permissive-in strict-out naming policy - #581
Conversation
Sorry, something went wrong.
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.
Sorry, something went wrong.
| - 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. |
Copilot
AI
Apr 26, 2026
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. |
Sorry, something went wrong.
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.md and targeted the vNext branch with a focused one-file documentation change.
Validation