Skip to content

Commit e782372

Browse files
authored
Update GuidelinesGraph.md
1 parent c834ec3 commit e782372

File tree

1 file changed

+12
-0
lines changed

1 file changed

+12
-0
lines changed

graph/GuidelinesGraph.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Table of contents
1414
- [Behavior modeling](#behavior-modeling)
1515
- [Error handling](#error-handling)
1616
- [Enums](#enums)
17+
- [External Standards](#external-standards)
1718
- [API contract and non-backward compatible changes](#api-contract-and-non-backward-compatible-changes)
1819
- [Versioning and deprecation](#versioning-and-deprecation)
1920
- [Recommended API design patterns](#recommended-api-design-patterns)
@@ -328,6 +329,17 @@ For a complete mapping of error codes to HTTP statuses, see
328329

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

332+
## External standards
333+
334+
For ease of client use and interoperatibility, some APIs should implement a standard that is defined external to Microsoft Graph and OData.
335+
Workloads should follow these standards exactly, even if they conflict with the OData standard and/or the Microsoft Graph guidelines.
336+
Workloads must define these standards in their CSDL model if they do not conflict with the OData standard.
337+
Standards that *do* conflict with the OData standard may be defined in the CSDL in one of two ways:
338+
1. Using `Edm.Untyped` only and support for the external standard will come directly from the service implementation; OR
339+
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
340+
341+
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.
342+
331343
## API contract and non-backward compatible changes
332344

333345
The Microsoft Graph definition of breaking changes is based on the

0 commit comments

Comments
 (0)