Skip to content
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.

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

Add guidance for implementing an external standard on graph #503

Draft
wants to merge 112 commits into
base: corranrogue9/externalstandards
Choose a base branch
from
Draft
Changes from 3 commits
Commits
Show all changes
112 commits
Select commit Hold shift + click to select a range
9f5ef0e
New default properties pattern
Aug 30, 2023
76c4458
Update product name guidance to include the caveat about the /admin s…
corranrogue9 Sep 5, 2023
e782372
Update GuidelinesGraph.md
corranrogue9 Oct 25, 2023
5bedf7c
Update GuidelinesGraph.md
corranrogue9 Oct 25, 2023
d156bc7
Update navigation-property.md
corranrogue9 Oct 25, 2023
50ee71f
Update navigation-property.md
corranrogue9 Oct 25, 2023
17e9b00
Update GuidelinesGraph.md
corranrogue9 Oct 25, 2023
c00f2a2
Update Guidelines.md
artificial-paul Oct 30, 2023
956726c
Remove extraneous backticks around filter (#502)
heaths Nov 6, 2023
62b0153
Create graph-structure.md
corranrogue9 Nov 16, 2023
22b9686
Delete graph/patterns/graph-structure.md
corranrogue9 Nov 16, 2023
90e9ca6
Add http-query-names-casing rule
mikekistler Nov 19, 2023
8c25785
fix link for breaking change documentation vanity link
troy0820 Jul 20, 2023
f2c9d83
small updates for versioning
annelo-msft Aug 30, 2022
e114751
Update azure/Guidelines.md
annelo-msft Aug 30, 2022
eb46156
Update Etag guideline for collection values
JeffreyRichter Apr 18, 2023
e18b48c
Update azure/Guidelines.md
JeffreyRichter Apr 18, 2023
83568c5
Update Repeatability headers section
JeffreyRichter Apr 21, 2023
32bbde2
Update azure/Guidelines.md
mikekistler Dec 6, 2023
5c64328
Update graph/GuidelinesGraph.md
corranrogue9 Dec 8, 2023
d7daa0b
Update GuidelinesGraph.md
corranrogue9 Dec 8, 2023
6ca5135
Update GuidelinesGraph.md
corranrogue9 Dec 8, 2023
62a5b44
Updated based on feedback and triage with Olga.
dkershaw10 Dec 18, 2023
bbaaa3f
Merge pull request #496 from microsoft/dkershaw-selectAndDefaultPrope…
dkershaw10 Dec 18, 2023
039b8cf
deprecating REST
OlgaPodo Dec 18, 2023
20f2d18
merging with REST
OlgaPodo Dec 18, 2023
2ad6aed
merging RESt
OlgaPodo Dec 18, 2023
1a7a6ed
Update GuidelinesGraph.md
OlgaPodo Dec 19, 2023
92241e2
url updates
OlgaPodo Dec 19, 2023
a6cc17c
branding
OlgaPodo Dec 19, 2023
3ff1be6
Update GuidelinesGraph.md
OlgaPodo Dec 19, 2023
7b1557f
casing
OlgaPodo Dec 19, 2023
27ee3ea
Update GuidelinesGraph.md
OlgaPodo Dec 19, 2023
49923da
Update GuidelinesGraph.md
OlgaPodo Dec 19, 2023
8f218a6
Merge branch 'olgapo-movingREST' of https://github.com/microsoft/api-…
OlgaPodo Dec 20, 2023
bfb1a8b
error article
OlgaPodo Dec 21, 2023
630aecd
Merge branch 'olgapo-movingREST' of https://github.com/microsoft/api-…
OlgaPodo Dec 21, 2023
568d6c0
updated naming article
OlgaPodo Dec 21, 2023
388b4ce
updated collections
OlgaPodo Dec 21, 2023
1615278
server-side pagination reasoning
OlgaPodo Dec 21, 2023
ea22528
updated nextLink
OlgaPodo Dec 21, 2023
b3b6b5e
Merge branch 'olgapo-movingREST' of https://github.com/microsoft/api-…
OlgaPodo Dec 21, 2023
3c4dacf
deprecation note
OlgaPodo Dec 21, 2023
7653778
formatting
OlgaPodo Dec 21, 2023
8448e5d
Merge pull request #513 from microsoft/olgapo-movingREST
OlgaPodo Dec 21, 2023
e8499d8
fixed files
OlgaPodo Dec 21, 2023
0437156
Update Guidelines-deprecated.md
OlgaPodo Dec 21, 2023
f373897
Merge pull request #514 from microsoft/olgapo-movingREST
OlgaPodo Dec 21, 2023
4f8698e
date format
OlgaPodo Dec 21, 2023
21c018c
fixed inner error message
OlgaPodo Dec 22, 2023
7c7544d
Merge pull request #515 from microsoft/olgapo-movingREST
OlgaPodo Dec 22, 2023
84a7143
Update naming guidance for id properties, transitiveChildren properti…
corranrogue9 Jan 23, 2024
f90d48a
Update CODEOWNERS
OlgaPodo Jan 31, 2024
641a29e
Update CODEOWNERS
OlgaPodo Jan 31, 2024
8ac2a81
Update dictionary.md
corranrogue9 Jan 31, 2024
8ff72bb
Update dictionary.md
corranrogue9 Jan 31, 2024
5579a9d
Update dictionary.md
corranrogue9 Jan 31, 2024
22a90f9
Update dictionary.md
corranrogue9 Jan 31, 2024
b845104
Update dictionary.md
corranrogue9 Jan 31, 2024
6529085
Merge branch 'vNext' into corranrogue9/admin
OlgaPodo Feb 1, 2024
8c40492
Merge pull request #497 from microsoft/corranrogue9/admin
OlgaPodo Feb 1, 2024
3431e24
Add guidelines on returning string offsets & lengths
mikekistler Jan 28, 2024
e465ea1
Address PR review feedback
mikekistler Feb 4, 2024
7136424
fixed example in markdown
bart1024 Feb 7, 2024
c77d6cc
Merge pull request #523 from bart1024/patch-1
mikepizzo Feb 7, 2024
7250558
Update ConsiderationsForServiceDesign.md
mikekistler Feb 9, 2024
194adeb
Add reference to String Offsets & Lengths topic in Considerations for…
mikekistler Feb 9, 2024
6066d21
Fix links to ARM RPC repo
mikekistler Feb 27, 2024
7482838
Clarify that casting is not required in order to see default properti…
mikepizzo Mar 12, 2024
3fdf426
Add links to all guidelines in the Considerations for Service Design …
mikekistler Jan 22, 2024
9fbcaa5
Update dictionary.md
corranrogue9 Mar 20, 2024
a50a52c
Update dictionary.md
corranrogue9 Mar 20, 2024
ab0700f
Update dictionary.md
corranrogue9 Mar 20, 2024
ddeed9f
Update graph/patterns/dictionary.md
OlgaPodo Mar 21, 2024
67f30db
Merge pull request #522 from microsoft/corranrogue9/dictionary2
OlgaPodo Mar 21, 2024
5f97b29
Update graph/patterns/navigation-property.md
OlgaPodo Mar 21, 2024
011dd3c
Merge pull request #504 from microsoft/corranrogue9/navprops
OlgaPodo Mar 21, 2024
55e2ef0
Create coreTypes.md
tylercleveland2 Mar 21, 2024
57e6d71
Update GuidelinesGraph.md
tylercleveland2 Mar 21, 2024
5818436
Update coreTypes.md
tylercleveland2 Mar 21, 2024
cc8a934
Update coreTypes.md
tylercleveland2 Mar 22, 2024
2ca37ff
Update GuidelinesGraph.md
tylercleveland2 Mar 22, 2024
6aa47c1
Update graph/articles/coreTypes.md
tylercleveland2 Apr 3, 2024
c9405c4
Update graph/articles/coreTypes.md
tylercleveland2 Apr 3, 2024
34b9192
Update graph/articles/coreTypes.md
tylercleveland2 Apr 3, 2024
af4e80a
Update graph/articles/coreTypes.md
tylercleveland2 Apr 3, 2024
c7d483c
Updated LRO guidelines (#517)
JeffreyRichter May 6, 2024
c6331c4
Update link to Azure RPC (#543)
abatishchev May 8, 2024
75385be
Merge pull request #532 from microsoft/ImproveSubtypes
mikepizzo May 16, 2024
076732d
Update enums.md
corranrogue9 May 27, 2024
f47f452
Update GuidelinesGraph.md
tylercleveland2 May 30, 2024
50ab124
Update coreTypes.md
tylercleveland2 May 30, 2024
33faa27
Update coreTypes.md
tylercleveland2 May 30, 2024
5d907fc
Update coreTypes.md
tylercleveland2 May 30, 2024
f9d8f70
Update coreTypes.md
tylercleveland2 May 30, 2024
1982472
Update coreTypes.md
tylercleveland2 May 30, 2024
59e0cd7
Update coreTypes.md
tylercleveland2 May 30, 2024
36e6d85
Merge pull request #537 from microsoft/tcleveland/core-type-restrictions
tylercleveland2 Jun 4, 2024
170a899
fix namespace guidance:
mikepizzo Jun 20, 2024
165393e
Merge pull request #547 from microsoft/Namespace-clarifications
mikepizzo Jun 24, 2024
400d7ca
Update graph/patterns/enums.md
OlgaPodo Jun 27, 2024
b736b80
Merge pull request #546 from microsoft/corranrogue9/flagsenum
OlgaPodo Jun 27, 2024
955e9ec
Update GuidelinesGraph.md
corranrogue9 Jul 5, 2024
b7fb275
Update enums.md
corranrogue9 Jul 5, 2024
9c93e8c
Update enums.md
corranrogue9 Jul 5, 2024
978d847
Update enums.md
corranrogue9 Jul 5, 2024
685e493
Merge pull request #552 from microsoft/corranrogue9/enumnaming
mikepizzo Jul 8, 2024
0674b4c
Merge pull request #505 from artificial-paul/patch-1
OlgaPodo Jul 11, 2024
00c5e08
Fixed wording
apiarya Aug 15, 2024
724b5f7
Merge pull request #556 from apiarya/patch-1
OlgaPodo Aug 16, 2024
aded31f
Updated naming rule for Booleans
dkershaw10 Sep 12, 2024
a60faaa
Merge pull request #561 from microsoft/dkershaw-update-boolean-naming…
OlgaPodo Sep 24, 2024
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
14 changes: 14 additions & 0 deletions graph/GuidelinesGraph.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Table of contents
- [Behavior modeling](#behavior-modeling)
- [Error handling](#error-handling)
- [Enums](#enums)
- [External Standards](#external-standards)
- [API contract and non-backward compatible changes](#api-contract-and-non-backward-compatible-changes)
- [Versioning and deprecation](#versioning-and-deprecation)
- [Recommended API design patterns](#recommended-api-design-patterns)
Expand Down Expand Up @@ -328,6 +329,19 @@ For a complete mapping of error codes to HTTP statuses, see

<a name="api-contract-and-non-backward-compatible-changes"></a>

## External standards

For ease of client use and interoperatibility, some APIs should implement a standard that is defined external to Microsoft Graph and OData.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

From Mike, I should be clear what APIs "conflict with odata stnadrad/graph guidelines"

Workloads should follow these standards exactly, even if they conflict with the OData standard and/or the Microsoft Graph guidelines.
Workloads must define these standards in their CSDL model if they do not conflict with the OData standard.
Standards that *do* conflict with the OData standard may be defined in the CSDL in one of two ways:
1. Using `Edm.Untyped` only and support for the external standard will come directly from the service implementation; OR
2. Adding CSDL elements to model the external standard using `Edm.String` for `EnumType`s that conflict with the OData standard and `Edm.Untyped` wherever any other conflict with the OData standard occurs
Copy link
Contributor Author

@corranrogue9 corranrogue9 Nov 6, 2023

Choose a reason for hiding this comment

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

From Mike: The structuring of the conjunction makes this sentence seem like it's only about enums

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The allowed values annotaiton should be used for strings


In either case, any use of `Edm.String` instead of an `EnumType` or any use of `Edm.Untyped` must provide a [description annotation](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.xml#L105) to document references to the standard that the client is expected to follow.
The benefit of the second approach is that strongly-typed models have SDK support for clients and also have significant tooling support for both the workload and clients.
Note that it is backwards compatible for a workload to migrate from the second approach to the first approach in case the external standard is *initially* compliant with the OData standard and *later* conflicts with the OData standard.

## API contract and non-backward compatible changes

The Microsoft Graph definition of breaking changes is based on the
Expand Down