Skip to content

docs: clarify permissive-in strict-out naming policy#581

Open
Rohan5commit wants to merge 1 commit intomicrosoft:vNextfrom
Rohan5commit:docs/permissive-in-strict-out-20260426
Open

docs: clarify permissive-in strict-out naming policy#581
Rohan5commit wants to merge 1 commit intomicrosoft:vNextfrom
Rohan5commit:docs/permissive-in-strict-out-20260426

Conversation

@Rohan5commit
Copy link
Copy Markdown

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

  • git diff --check

Copilot AI review requested due to automatic review settings April 26, 2026 03:07
@Rohan5commit Rohan5commit requested a review from a team as a code owner April 26, 2026 03:07
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread graph/GuidelinesGraph.md
Comment on lines +127 to +128
- 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.
Copy link

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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").

Suggested change
- 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.

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clarify Permissive-In / Strict-Out Naming Policy in Guidelines

3 participants