|
| 1 | +# Enumeration documentation |
| 2 | + |
| 3 | +This shared reference covers all enumeration documentation tasks across scenarios: creating new enumerations (Scenario 1), promoting enumerations (Scenario 2), updating existing enumerations, and deprecating enumerations (Scenario 3). |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## Creating new enumerations |
| 8 | + |
| 9 | +**Important:** There are three options for documenting enumerations depending on the complexity and use case. Choose the appropriate option based on the decision guide below. |
| 10 | + |
| 11 | +### Quick decision guide |
| 12 | + |
| 13 | +| Criteria | Recommended Option | |
| 14 | +|----------|-------------------| |
| 15 | +| Self-explanatory member names | Option 1: Enum file | |
| 16 | +| Need member descriptions | Option 2: Parent resource OR Option 3: Separate topic | |
| 17 | +| Single feature/related resources in same namespace | Option 2: Parent resource | |
| 18 | +| Enum with many members requiring descriptions or multiple resources use enum | Option 3: Separate topic | |
| 19 | + |
| 20 | +**Auto-selection heuristics** — use these to select an option automatically when the Documentation Plan doesn't specify: |
| 21 | +1. If the doc stub defines the enum in `enums.md` or `enums-{subnamespace}.md` → **Option 1** |
| 22 | +2. If the Documentation Plan says "with descriptions" and the enum has ≤10 members → **Option 2** |
| 23 | +3. If the Documentation Plan says "with descriptions" and the enum has >10 members → **Option 3** |
| 24 | +4. If multiple unrelated resources reference the same enum → **Option 3** |
| 25 | +5. When uncertain, default to **Option 1** (simplest) and flag for author review |
| 26 | + |
| 27 | +### Option 1: Use global enum file (Preferred for simple enums) |
| 28 | + |
| 29 | +**For microsoft.graph namespace:** |
| 30 | +- Use existing `api-reference/beta/resources/enums.md` or `api-reference/v1.0/resources/enums.md` |
| 31 | + |
| 32 | +**For subnamespaces:** |
| 33 | +- Create `enums-{subnamespace-name}.md` (e.g., `enums-security.md` for `microsoft.graph.security` namespace) |
| 34 | + |
| 35 | +**Steps:** |
| 36 | + |
| 37 | +1. **Add to enums file:** |
| 38 | + - Add an H3 section titled "{enum-type} values" (e.g., "eventType values") |
| 39 | + - Include a table with column header **Member** only |
| 40 | + - List members without numeric values or descriptions |
| 41 | + - For evolvable enums: Include `unknownFutureValue` in member list |
| 42 | + |
| 43 | +2. **Update parent resource Properties table:** |
| 44 | + - Specify the enum as the property's return type |
| 45 | + - For subnamespaces: Use fully qualified name (e.g., `microsoft.graph.security.alertStatus`) |
| 46 | + |
| 47 | +3. **Update property description:** |
| 48 | + - List all possible values in the description |
| 49 | + - **For flagged enums:** Add "This flagged enumeration allows multiple members to be selected simultaneously." before listing the possible values |
| 50 | + - **For evolvable enums (if unknownFutureValue is last member):** |
| 51 | + - Format: "The possible values are: `value1`, `value2`, `unknownFutureValue`." |
| 52 | + - **For evolvable enums (if members follow unknownFutureValue):** |
| 53 | + - Format: "The possible values are: `value1`, `value2`, `unknownFutureValue`, `value3`. Use the `Prefer: include-unknown-enum-members` request header to get the following value or values in this evolvable enum: `value3`." |
| 54 | + |
| 55 | +4. **JSON representation:** |
| 56 | + - Define the property as type **String**, not the enum type |
| 57 | + |
| 58 | +**When to use:** |
| 59 | +- Member names are self-explanatory |
| 60 | +- No or minimal descriptions needed |
| 61 | + |
| 62 | + Example where minimal descriptions are needed: |
| 63 | + ```markdown |
| 64 | + The possible values are: <br/><li>`none`: No cross-tenant access. Indicates a single-tenant, non-B2B scenario. </li> <li>`b2bCollaboration`: The connection involves B2B collaboration across tenants. </li> <li>`unknownFutureValue`: Evolvable enumeration sentinel value. Do not use.</li> |
| 65 | + ``` |
| 66 | + |
| 67 | +**Note:** enums.md and enums-{subnamespace}.md files are not customer-facing (they're for API Doctor validation only). |
| 68 | + |
| 69 | +### Option 2: Document in parent resource topic |
| 70 | + |
| 71 | +Document within the **Properties** section of the resource that uses the enum. This option is customer-facing. |
| 72 | + |
| 73 | +**Steps:** |
| 74 | + |
| 75 | +1. **Create H3 section after Properties table:** |
| 76 | + - Title: "{enum-type} values" |
| 77 | + |
| 78 | + - **For evolvable enums (if members follow unknownFutureValue):** |
| 79 | + - Add introductory text before the table: |
| 80 | + ```markdown |
| 81 | + The following table lists the members of an [evolvable enumeration](/graph/best-practices-concept#handling-future-members-in-evolvable-enumerations). |
| 82 | + Use the `Prefer: include-unknown-enum-members` request header to get the following members in this evolvable enum: `value3`. |
| 83 | + ``` |
| 84 | + - **For flagged enums:** |
| 85 | + - Append the following boilerplate text to the introductory text before the table: |
| 86 | + ```markdown |
| 87 | + The following table lists the members of an [evolvable enumeration](/graph/best-practices-concept#handling-future-members-in-evolvable-enumerations). |
| 88 | + Use the `Prefer: include-unknown-enum-members` request header to get the following members in this evolvable enum: `value3`. This flagged enumeration allows multiple members to be selected simultaneously. |
| 89 | + ``` |
| 90 | + |
| 91 | +2. **Create table:** |
| 92 | + - Columns: **Member** and **Description** |
| 93 | + - List members in ascending order by numeric value (without exposing numeric values) |
| 94 | + - **For evolvable enums:** |
| 95 | + - Include `unknownFutureValue` member |
| 96 | + - Description for `unknownFutureValue`: "Evolvable enumeration sentinel value. Do not use." or "Evolvable enumeration sentinel value. Don't use." |
| 97 | + |
| 98 | +3. **Update Properties table:** |
| 99 | + - Specify enum as property's return type and link to the H3 section |
| 100 | + - For subnamespaces: Use fully qualified name |
| 101 | + - Optionally list values inline in description (can omit to avoid duplication) |
| 102 | + |
| 103 | +4. **JSON representation:** |
| 104 | + - Define property as type **String**, not the enum type |
| 105 | + |
| 106 | +5. **If multiple related resources use this enum:** |
| 107 | + - Define the table once and link from other topics |
| 108 | + |
| 109 | +**When to use:** |
| 110 | +- Need descriptions for enum members |
| 111 | +- Enum and resources are in the same namespace |
| 112 | +- Resources are part of the same feature |
| 113 | +- Enum is only used by one resource or a few related resources |
| 114 | + |
| 115 | +**Important:** More content increases page scroll length. If the enum has many members, consider Option 3. |
| 116 | + |
| 117 | +### Option 3: Create separate enum topic |
| 118 | + |
| 119 | +Create a dedicated topic for the enumeration. This option is rarely applicable. |
| 120 | + |
| 121 | +**File naming:** |
| 122 | +- microsoft.graph namespace: `{enum-name}.md` |
| 123 | +- Subnamespaces: `{subnamespace-name}-{enum-name}.md` (e.g., `callrecords-servicerole.md`) |
| 124 | + |
| 125 | +**Steps:** |
| 126 | + |
| 127 | +1. **Create enum topic:** |
| 128 | + - Title: "{enum-type} enum type" |
| 129 | + - Single sentence describing the enum's purpose |
| 130 | + - **For flagged enums:** Append "This flagged enumeration allows multiple members to be selected simultaneously." to the introductory text. |
| 131 | + - **For evolvable enums:** Mention it's an evolvable enumeration |
| 132 | + |
| 133 | +2. **Add Members H2 section:** |
| 134 | + - **For evolvable enums (if members follow unknownFutureValue):** |
| 135 | + - Add introductory text before the table (same as Option 2) |
| 136 | + - Table with columns: **Member** and **Description** |
| 137 | + - List members in ascending order by numeric value (without exposing values) |
| 138 | + - **For evolvable enums:** |
| 139 | + - Include `unknownFutureValue` member |
| 140 | + - Description: "Evolvable enumeration sentinel value. Do not use." or "Evolvable enumeration sentinel value. Don't use." |
| 141 | + |
| 142 | +3. **Update parent resource Properties table:** |
| 143 | + - Specify enum as property's return type and link to the enum topic |
| 144 | + - For subnamespaces: Use fully qualified name |
| 145 | + - Avoid listing values inline to prevent duplication |
| 146 | + |
| 147 | +4. **JSON representation:** |
| 148 | + - Define property as type **String**, not the enum type |
| 149 | + |
| 150 | +5. **For subnamespaces:** |
| 151 | + - Add namespace attribute in page annotation at bottom of topic: |
| 152 | + ```json |
| 153 | + { |
| 154 | + "type": "#page.annotation", |
| 155 | + "namespace": "microsoft.graph.{subnamespace}" |
| 156 | + } |
| 157 | + ``` |
| 158 | + |
| 159 | +**When to use:** |
| 160 | +- Need descriptions for enum members and Option 2 isn't suitable |
| 161 | +- Multiple resources use the enum |
| 162 | +- Enum has many members requiring detailed descriptions that might reduce scannability in Options 1 or 2 |
| 163 | + |
| 164 | +**Important:** Use only when necessary. Prefer Option 1 or 2 whenever possible. |
| 165 | + |
| 166 | +--- |
| 167 | + |
| 168 | +## Evolvable enumerations - Special handling |
| 169 | + |
| 170 | +**All evolvable enumerations:** |
| 171 | +- Include `unknownFutureValue` sentinel member |
| 172 | +- This member demarcates known members (defined initially) from unknown members (added later or to be defined in future) |
| 173 | +- Must always be documented to allow developers to handle future enum updates |
| 174 | + |
| 175 | +**Two scenarios:** |
| 176 | + |
| 177 | +**Scenario 1: unknownFutureValue is the last defined member** |
| 178 | +- List all values with `unknownFutureValue` last |
| 179 | +- No special header required |
| 180 | +- Example inline format: "The possible values are: `success`, `failure`, `timeout`, `unknownFutureValue`." |
| 181 | + |
| 182 | +**Scenario 2: Members follow unknownFutureValue** |
| 183 | +- Must include note about `Prefer: include-unknown-enum-members` request header |
| 184 | +- Example inline format: "The possible values are: `none`, `b2bCollaboration`, `unknownFutureValue`, `passthrough`. Use the `Prefer: include-unknown-enum-members` request header to get the following value or values in this evolvable enum: `passthrough`." |
| 185 | +- For Options 2 & 3: Add introductory text before the table explaining the header requirement |
| 186 | +- Optionally in GET API topics: Add note about optional request header in **Request headers** section |
| 187 | + |
| 188 | +--- |
| 189 | + |
| 190 | +## Updating existing enumerations |
| 191 | + |
| 192 | +**When adding new members to existing enumerations:** |
| 193 | + |
| 194 | +1. **Locate all places where the enum is documented:** |
| 195 | + |
| 196 | + The enum has a **definition** in exactly one of three locations, and may also have an **inline listing** in property descriptions. Search the version-appropriate `resources/` folder for the enum type name to identify which locations apply. |
| 197 | + |
| 198 | + | Location type | Where to look | How to identify | |
| 199 | + |---------------|---------------|-----------------| |
| 200 | + | **Global enums file** (Option 1) | `enums.md` or `enums-{subnamespace}.md` | H3 section titled "{enumType} values" with a Member-only table | |
| 201 | + | **H3 in parent resource** (Option 2) | Resource file that uses the enum | H3 section titled "{enumType} values" with a Member + Description table | |
| 202 | + | **Separate enum topic** (Option 3) | `{enum-name}.md` or `{subnamespace}-{enum-name}.md` | Dedicated file with Members H2 section | |
| 203 | + | **Inline in property description** (any option) | Resource files where a property declares the enum as its return type | Property description that lists values (e.g., "The possible values are: `value1`, `value2`…") | |
| 204 | + |
| 205 | + > **Important:** The inline property description is independent of the enum definition. When the enum definition uses Option 2 or 3, the property's Type column in the Properties table links to the H3 table or separate topic instead of listing values inline in the description — in that case, no inline update is needed. When Option 1 is used, the property description lists values inline (because the global enums file is not customer-facing) and must be updated. |
| 206 | + |
| 207 | +2. **Update the enum definition** (whichever location from step 1 applies): |
| 208 | + - Add the new members to the table |
| 209 | + - Maintain the order from the Documentation Plan or the author's prompt |
| 210 | + - Do not change the order of existing members unless specified |
| 211 | + |
| 212 | +3. **Update inline property descriptions** (only if values are listed inline — see step 1): |
| 213 | + - Search for all resource files that reference the enum type as a property return type |
| 214 | + - Add the new member to the list of possible values, maintaining the order from the Documentation Plan or the author's prompt |
| 215 | + - If the property uses evolvable enum syntax with `Prefer: include-unknown-enum-members`, add the new member to both the main list AND the evolvable members list |
| 216 | + - Ensure consistency across all properties that reference the same enumeration |
| 217 | + - Ensure consistent formatting with backticks around enum values |
| 218 | + |
| 219 | +4. **For evolvable enums with new members after unknownFutureValue:** |
| 220 | + - Update introductory text (for Options 2 & 3) to list the new members that require the header |
| 221 | + - Update inline descriptions to include the new members in the header note |
| 222 | + |
| 223 | +--- |
| 224 | + |
| 225 | +## Deprecating enumerations |
| 226 | + |
| 227 | +### To deprecate an entire enumeration |
| 228 | + |
| 229 | +1. **Update enumeration definition:** |
| 230 | + - **In enums.md or parent resource:** Add "(deprecated)" to section title: `### emailType values (deprecated)` |
| 231 | + - **In own topic (rare):** Add "(deprecated)" to H1 title and add deprecation banner |
| 232 | + |
| 233 | +2. **Update properties using the enum:** |
| 234 | + - Update type, description, possible values with alternative/workaround |
| 235 | + |
| 236 | +### To deprecate enumeration members |
| 237 | + |
| 238 | +1. **Update member table:** |
| 239 | + - Add "(deprecated)" to member name, specify alternative, move to end (see common pattern) |
| 240 | + |
| 241 | +2. **Update property descriptions:** |
| 242 | + - Note which values are deprecated and provide guidance |
| 243 | + |
| 244 | +--- |
| 245 | + |
| 246 | +## Quality checklist for enumerations |
| 247 | + |
| 248 | +### For new enumerations |
| 249 | + |
| 250 | +- [ ] Documentation option selected based on decision guide (Option 1, 2, or 3) |
| 251 | +- [ ] **Option 1 (Enum file):** |
| 252 | + - [ ] New enumerations added to appropriate enums.md or enums-{subnamespace}.md file |
| 253 | + - [ ] Only Member column documented (no Description or Value columns) |
| 254 | + - [ ] Members listed in order from Documentation Plan |
| 255 | + - [ ] For evolvable enums: unknownFutureValue included in member list |
| 256 | + - [ ] Property descriptions include all enum values with correct format |
| 257 | + - [ ] For evolvable enums with members after unknownFutureValue: Prefer header note included in property description |
| 258 | +- [ ] **Option 2 (Parent resource):** |
| 259 | + - [ ] H3 section "{enum-type} values" added after Properties table |
| 260 | + - [ ] Table has Member and Description columns |
| 261 | + - [ ] Members listed in ascending order by numeric value (values not exposed) |
| 262 | + - [ ] For evolvable enums: unknownFutureValue description is "Evolvable enumeration sentinel value. Do not use." |
| 263 | + - [ ] For evolvable enums with members after unknownFutureValue: Introductory text about Prefer header included |
| 264 | + - [ ] Properties table links to H3 section |
| 265 | + - [ ] For subnamespaces: Fully qualified enum name used |
| 266 | +- [ ] **Option 3 (Separate topic):** |
| 267 | + - [ ] File created with correct naming convention |
| 268 | + - [ ] Title is "{enum-type} enum type" |
| 269 | + - [ ] Description mentions evolvable enumeration if applicable |
| 270 | + - [ ] Members H2 section with Member and Description columns |
| 271 | + - [ ] For evolvable enums: unknownFutureValue description is "Evolvable enumeration sentinel value. Don't use." |
| 272 | + - [ ] For evolvable enums with members after unknownFutureValue: Introductory text about Prefer header included |
| 273 | + - [ ] For subnamespaces: Namespace attribute added in page annotation |
| 274 | + - [ ] Parent resource Properties table links to enum topic |
| 275 | + |
| 276 | +### For updating existing enumerations |
| 277 | + |
| 278 | +- [ ] New enumeration members added to existing enumeration tables/files |
| 279 | +- [ ] Order from Documentation Plan maintained |
| 280 | +- [ ] All properties that consume updated enumerations have been updated |
| 281 | +- [ ] Enum member lists in property descriptions match enumeration definition |
| 282 | +- [ ] For evolvable enums: unknownFutureValue always documented |
| 283 | +- [ ] For evolvable enums with new members after unknownFutureValue: Property descriptions and introductory text updated with Prefer header note |
| 284 | + |
| 285 | +### For deprecating enumerations |
| 286 | + |
| 287 | +- [ ] Section title or H1 title updated with "(deprecated)" |
| 288 | +- [ ] Properties using enum updated with alternatives |
| 289 | +- [ ] Deprecated members moved to end of table with "(deprecated)" suffix |
0 commit comments