You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Provide a simpler example of a primitive dictionary before dictionary of complex type.
Provide separate examples for defining a dictionary, using the dictionary in a type definition, and then querying/adding/updating/removing dictionary entries.
*The dictionary type provides the ability to create a set of primitives or objects of the same type where the API consumer can define a name for each value in the set.*
5
+
_The dictionary type provides the ability to create a set key/value pairs where the set of keys is dynamically specified by the API consumer._
6
6
7
7
## Problem
8
8
9
-
The API design requires a resource to include an unknown quantity of data elements of the same type that must be named by using values provided by the API consumer.
9
+
The API design requires a resource to include an unknown quantity of data values whose keys are defined by the API consumer.
10
10
11
11
## Solution
12
12
13
-
API designers use a JSON object to represent a dictionary in an `application/json` response payload. When describing the model in CSDL, a new complex type can be created that derives from `Org.OData.Core.V1.Dictionary` and then uses the `Org.OData.Validation.V1.OpenPropertyTypeConstraint` to constrain the type that can be used for the values in the dictionary as appropriate.
13
+
API designers use a JSON object to represent a dictionary in an `application/json` response payload. When describing the model in CSDL, a new complex type can be created that derives from `graph.Dictionary` and optionally uses the `Org.OData.Validation.V1.OpenPropertyTypeConstraint` to constrain the type that can be used for the values in the dictionary as appropriate.
14
14
15
-
Dictionary values can be added, removed, or modified via `PATCH` to the dictionary property. Values are removed by setting the property to `null`.
15
+
Dictionary entries can be added, removed, or modified via `PATCH` to the dictionary property. Entries are removed by setting the property to `null`.
16
16
17
17
## When to use this pattern
18
18
19
19
Before using a dictionary type in your API definition, make sure that your scenario fits the following criteria:
20
20
21
21
- The data values MUST be related to one another semantically as a collection.
22
-
- The value types MUST be a primitive type or a **ComplexType**. Mixed primitive types are not allowed.
22
+
- The values MUST be primitive or complex types.
23
23
- The client MUST define the keys of this type, as opposed to the service defining them in advance.
24
24
25
25
### Alternatives
@@ -31,81 +31,111 @@ Before using a dictionary type in your API definition, make sure that your scena
31
31
32
32
Dictionaries, sometimes called maps, are a collection of name-value pairs. They allow dynamic data sets to be accessed in a systematic manner and are a good compromise between a strictly defined-ahead-of-time structure with all its named properties and a loosely defined dynamic object (such as OData OpenTypes).
33
33
34
-
Because dictionary entries are removed by setting the value to `null`, dictionaries can only support values that are non-nullable.
35
-
36
-
Open questions:
37
-
38
-
- Can/should PUT be supported on the dictionary property and/or the entry value?
39
-
- Must an implementer support PATCH at both the dictionary level and the entry level?
40
-
- Should we also allow DELETE to a property to be equivalent to setting to null?
41
-
- Why do we not allow mixed primitives or mixed primitive/complex typed values? what about collections?
34
+
Because dictionary entries are removed by setting the value to `null`, dictionaries don't support null values.
42
35
43
36
For more information, see the [OData reference](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#dictionary).
44
37
45
38
## Examples
46
39
47
-
### JSON payload example
40
+
### Declaring a string dictionary
41
+
The following example demonstrates defining a dictionary that can contain string values.
48
42
49
-
The following example illustrates the resulting JSON for a property of dictionary type. The parent object has been omitted for brevity.
In this set of examples, we model a **roles** property of dictionary type on the user entity, which is exposed by the users entity set.
63
+
### Reading a dictionary
64
+
Dictionaries are represented in JSON payloads as a JSON object, where the property names are comprised of the keys and their values are the corresponding key values.
68
65
69
-
#### Get an entry from the dictionary
66
+
The following example shows reading an item with a dictionary property named "userTags":
70
67
71
68
```HTTP
72
-
GET https://graph.microsoft.com/v1.0/users/10/roles/author
69
+
GET /item
73
70
```
74
-
75
71
Response:
76
-
77
72
```json
78
73
{
79
-
"domain": "contoso"
74
+
...
75
+
"userTags":
76
+
{
77
+
"anniversary": "2002-05-19",
78
+
"favoriteMovie": "Princess Bride"
79
+
}
80
80
}
81
81
```
82
82
83
-
#### Get the dictionary
83
+
### Setting a dictionary value
84
+
The following example shows setting a dictionary value. If "hairColor" already exists, it is updated, otherwise it is added.
84
85
85
-
```HTTP
86
-
GET https://graph.microsoft.com/v1.0/users/10/roles
86
+
```http
87
+
PATCH /item/userTags
88
+
```
89
+
```json
90
+
{
91
+
"hairColor": "purple"
92
+
}
87
93
```
88
94
89
-
Response:
90
-
95
+
### Deleting a dictionary value
96
+
A dictionary value can be removed by setting the value to null.
97
+
```http
98
+
PATCH /item/userTags
99
+
```
91
100
```json
92
101
{
93
-
"author": {
94
-
"domain": "contoso"
95
-
},
96
-
"maintainer": {
97
-
"domain": "fabrikam"
98
-
},
99
-
"architect": {
100
-
"domain": "adventureWorks"
101
-
}
102
+
"hairColor": null
102
103
}
103
104
```
104
105
105
-
#### Get the entity with the dictionary
106
+
### Declaring a complex typed dictionary
107
+
Dictionaries can also contain complex types whose values may be constrained to a particular set of complex types.
108
+
109
+
The following example defines a complex type **roleSettings**, an **assignedRoleGroupDictionary** that contains **roleSettings**, and an **assignedRoles** property that uses the dictionary..
#### Setting an individual entry in the dictionary
200
+
The following examples shows updating the dictionary to set the value for the "author" entry. If the "author" entry does not exists it is added with the specified values; otherwise, if the "author" entry already exists, it is updated with the specified values (unspecified values are left unchanged).
#### Deleting an individual entry from the dictionary
214
+
The following example shows deleting the "author" entry by setting its value to null.
186
215
187
-
The following example defines a complex type **roleSettings** as well as a dictionary of which the key will be a string and the value a **roleSettings**.
216
+
```HTTP
217
+
PATCH /users/10/assignedRoles
218
+
```
219
+
```json
220
+
{
221
+
"author": null
222
+
}
223
+
```
188
224
189
-
```xml
190
-
<ComplexTypeName="roleSettings">
191
-
<Property Name ="domain"Type="Edm.String"Nullable="false" />
192
-
</ComplexType>
225
+
#### Setting multiple dictionary entries
226
+
The following example sets values for the "author", "maintainer" and "viewer" entries, and removes the "architect" entry by setting it to null.
0 commit comments