Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Rohan5commit wants to merge 1 commit into
base: vNext
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions graph/GuidelinesGraph.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,14 @@ Following is a short summary of the most often used conventions.
| :ballot_box_with_check: **SHOULD** prefix Boolean properties with `is`, unless this leads to awkward or unnatural sounding names for Boolean properties. | - **Right:** isEnabled or isResourceAccount <BR>- **Wrong:** enabled or allowResourceAccount <BR>- **Right:** hasChildren or hasSubscriptions <BR>- **Wrong:** isChildren or isSubscriptions <BR>- **Right:** allowNewTimeProposals or allowInvitesFrom (subjectively more natural than the following examples) <BR> - **Wrong:** isNewTimeProposalsAllowed or isInvitesFromAllowed (subjectively more awkward that the preceding examples) |
| :no_entry: **MUST NOT** use collection, response, or request suffixes. | - **Right:** addresses <BR> - **Wrong:** addressCollection |

#### Input and output handling

APIs sometimes need a permissive-in / strict-out policy during migrations or when preserving compatibility with older clients.

- Services **SHOULD** accept the documented set of equivalent input forms when compatibility requires it, such as a legacy alias or a case-insensitive variant.
- 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.
Comment on lines +127 to +128
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.

#### Tree and graph structures

When a tree or graph structure is being modeled, the direct sub-nodes are usually named `children` or `members`.
Expand Down
Loading