Skip to content

Commit b136f08

Browse files
OlgaPodoOlgaPodo
committed
alignment to top-level categories
1 parent 2e62547 commit b136f08

File tree

1 file changed

+70
-21
lines changed

1 file changed

+70
-21
lines changed

‎graph/patterns/namespace.md

Lines changed: 70 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -9,34 +9,38 @@ Microsoft Graph API Design Pattern
99
When building a complex offering API designers may need to model many different
1010
resources and their relationships. For better user experience and
1111
discoverability related API definitions need to be grouped together. Large API
12-
surface may need to be partitioned to generate light-weight client SDKs and libraries.
12+
surface may need to be partitioned to generate light-weight client SDKs and
13+
libraries.
1314

1415
## Solution
1516

16-
API designers can use the Namespace attribute of the CSDL schema to
17-
declare a namespace and logically bundle related API entities in the Graph
18-
metadata.
19-
```XML
17+
API designers can use the Namespace attribute of the CSDL schema to declare a
18+
namespace and logically bundle related API entities in the Graph metadata.
19+
20+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ XML
2021
<Schema Namespace="microsoft.graph.{namespace}">
2122
...
2223
</Schema>
23-
```
24+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2425

25-
All resources declared within the namespace will be grouped together in the public
26-
Graph metadata and may be used for partitioning.
26+
All resources declared within the namespace will be grouped together in the
27+
public Graph metadata and may be used for partitioning.
2728

2829
A public namespace must have "microsoft.graph.” prefix and be presented in camel
2930
case, i.e microsoft.graph.myNamespace.
3031

31-
When type casting is required in the API query, request or response a fully-qualified type name is represented as concatenation of a namespace and a type name. Consequently namespace should be aligned with API category
32-
path segment.
32+
When type casting is required in the API query, request or response a fully
33+
qualified type name is represented as concatenation of a namespace and a type
34+
name. Consequently namespace should be aligned with API category path segment.
3335

3436
## When to Use this Pattern
3537

3638
API resource grouping creates a user-friendly experience keeping all resources
37-
for a specific use case close together. It also allows generating smaller SDKs
39+
for a specific feature close together. It also allows generating smaller SDKs
3840
and libraries and limits length of IDE prompts such as Intellisense.
3941

42+
We recommend creating a new namespace when a new top-level API category is
43+
introduced.
4044

4145
## Issues and Considerations
4246

@@ -47,33 +51,78 @@ and libraries and limits length of IDE prompts such as Intellisense.
4751

4852
2. Namespace must be consistent with API navigation path.
4953

50-
3. When type name is ambiguous and requires a namespace qualifier changing namespace is a breaking change.
51-
54+
3. When type name is ambiguous and requires a namespace qualifier, changing
55+
namespace is a breaking change.
5256

5357
4. To extend a type in a different schema, a service must declare that schema
5458
and the type in it. This is conceptually similar to .NET partial types.
5559

5660
5. To reference a type in a different schema, simply refer to that type by
5761
fully qualified name (namespace + type name).
58-
6. Microsoft Graph has heuristic rules for declared namespaces:
5962

60-
- All public namespaces must have a prefix ‘microsoft.graph’
63+
6. Cyclical references between namespaces are not allowed as many
64+
object-oriented languages don’t support a cycle in inheritance.
65+
66+
7. Microsoft Graph has heuristic rules for declared namespaces:
6167

62-
- If a namespace does not begin with ‘microsoft.graph’ prefix, all types in
63-
the schema will be coerced into the main ‘microsoft.graph’ namespace.
68+
1. All public namespaces must have a prefix ‘microsoft.graph’
69+
70+
2. If a namespace does not begin with ‘microsoft.graph’ prefix, all types
71+
in the schema will be coerced into the main ‘microsoft.graph’ namespace.
6472

6573
## Example
6674

67-
Namespace and type declarations:
68-
```XML
75+
### Namespace and type declarations:
6976

77+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ XML
7078
<Schema Namespace="microsoft.graph.search" xmlns=”<http://docs.oasis-open.org/odata/ns/edm>”\>
7179
…
7280
<EntityType Name="bookmark" …
7381
</EntityType>
7482
…
7583
</Schema>
76-
77-
```
84+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7885

7986
Fully qualified type name: microsoft.graph.search.bookmark
87+
88+
### Managing multiple schemas:
89+
90+
Workloads must define schemas in their csdl using the Edmx format.
91+
[Microsoft.IC3.DataPlatform](https://dev.azure.com/msazure/One/_git/AD-AggregatorService-Workloads?path=%2FWorkloads%2FMicrosoft.IC3.DataPlatform%2Foverride%2Fschema-Prod-beta.csdl)
92+
is an example of a workload that exposes multiple namespaces.
93+
94+
**Tip:** As with schemas that exist in the microsoft.graph namespace, defining an
95+
entity type is optional, AGS will transform your schema to make all entity types
96+
derive from microsoft.graph.entity.
97+
98+
**Warning:** Do not deviate from the general structure in the example below.
99+
Schema validation tool expects the XML structure (including xml namespace
100+
declarations) to match the example below.
101+
```XML
102+
<?xml version="1.0" encoding="utf-8"?>
103+
<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" xmlns:ags="http://aggregator.microsoft.com/internal" xmlns:odata="http://schemas.microsoft.com/oDataCapabilities">
104+
<edmx:DataServices>
105+
<Schema Namespace="microsoft.graph.callRecords" xmlns="http://docs.oasis-open.org/odata/ns/edm" xmlns:ags="http://aggregator.microsoft.com/internal" xmlns:odata="http://schemas.microsoft.com/oDataCapabilities">
106+
<EntityType Name="callRecord" ags:IsOwner="true" ags:AddressUrl="https://plat.teams.microsoft.com">
107+
<Key>
108+
<PropertyRef Name="id" />
109+
</Key>
110+
<Property Name="version" Type="Edm.Int64" Nullable="false" />
111+
<Property Name="id" Type="Edm.String" Nullable="false" />
112+
</EntityType>
113+
</Schema>
114+
<Schema Namespace="microsoft.graph" xmlns="http://docs.oasis-open.org/odata/ns/edm">
115+
<EntityContainer Name="defaultContainer">
116+
<Singleton Name="communications" Type="microsoft.graph.cloudCommunications" />
117+
</EntityContainer>
118+
<EntityType Name="cloudCommunications">
119+
<Key>
120+
<PropertyRef Name="id" />
121+
</Key>
122+
<Property Name="id" Type="Edm.String" Nullable="false" />
123+
<NavigationProperty Name="callRecords" Type="Collection(microsoft.graph.callRecords.callRecord)" ContainsTarget="true" />
124+
</EntityType>
125+
</Schema>
126+
</edmx:DataServices>
127+
</edmx:Edmx>
128+
```

0 commit comments

Comments
 (0)