Azure Boards: types, hierarchy and fields

[
  { "op": "add", "path": "/fields/System.Description", "value": "As a warehouse operator, I want to export an order's picking list as CSV, so that I can print it for the floor team." },
  { "op": "add", "path": "/multilineFieldsFormat/System.Description", "value": "Markdown" }
]

{ "action": "create", "workItemType": "User Story",
  "fields": [
    { "name": "System.Title", "value": "Export picking list as CSV" },
    { "name": "Microsoft.VSTS.Common.AcceptanceCriteria",
      "value": "- Given order 1002 with 4 lines, when I choose \"Export CSV\", then `picking-1002.csv` downloads with a header row and 4 data rows.",
      "format": "Markdown" }
  ] }

<ul>
  <li>Given order 1002 with 4 lines, when I choose "Export CSV", then <code>picking-1002.csv</code> downloads with a header row and 4 data rows.</li>
  <li>Given an order with no lines, when I choose "Export CSV", then the message "Nothing to export" appears and no file downloads.</li>
</ul>

# Azure Boards: types, hierarchy and fields

Verified 2026-09 against learn.microsoft.com/azure/devops/boards (work item field index, process templates) and the Azure DevOps MCP server tool schemas.

## Work item types per process

| Level | Agile | Scrum | CMMI | Basic |
|---|---|---|---|---|
| Portfolio | Epic → Feature | Epic → Feature | Epic → Feature | Epic |
| Requirement | User Story | Product Backlog Item | Requirement | Issue |
| Defect | Bug (backlog or task level, per team setting) | Bug | Bug | — (use Issue) |
| Task | Task | Task | Task | Task |
| Size field | Story Points `Microsoft.VSTS.Scheduling.StoryPoints` | Effort `Microsoft.VSTS.Scheduling.Effort` | Size `Microsoft.VSTS.Scheduling.Size` | — |

Detect the process by reading the parent's type or the project's work item types; never assume "User Story".

## Common field reference names

| Field | Reference name | Type |
|---|---|---|
| Title | `System.Title` | string, 255 chars |
| Description | `System.Description` | large text (HTML or Markdown) |
| Acceptance Criteria | `Microsoft.VSTS.Common.AcceptanceCriteria` | large text (HTML or Markdown); not on Task or Basic Issue |
| Repro Steps | `Microsoft.VSTS.TCM.ReproSteps` | large text (HTML or Markdown); Bug only |
| Priority | `Microsoft.VSTS.Common.Priority` | integer 1–4 |
| Tags | `System.Tags` | `tag1; tag2` |
| Area Path | `System.AreaPath` | tree path |
| Iteration Path | `System.IterationPath` | tree path |
| State | `System.State` | per process (New/Active/Resolved/Closed in Agile; New/Approved/Committed/Done in Scrum) |
| Assigned To | `System.AssignedTo` | identity |

## Links

- **Parent / Child** (`System.LinkTypes.Hierarchy-Reverse` / `-Forward`): Feature ↔ Story, Story ↔ Task. Creating a child through the parent sets both ends.
- **Related** (`System.LinkTypes.Related`): same-level items that inform each other.
- **Predecessor / Successor** (`System.LinkTypes.Dependency-Reverse` / `-Forward`): ordering constraints.
- Artifact links: branch, commit, pull request and build links appear under Development; commits and PRs that mention the ID create them automatically.

## Large-text fields: HTML or Markdown

`System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria` and `Microsoft.VSTS.TCM.ReproSteps` are large-text fields. They are **HTML by default**; Azure Boards (Services, since 2025) also renders them as Markdown once a field is switched, and the switch is permanent for that field on that work item.

**Say which format you are writing.** REST API — set the value and the format in the same patch document:

```json
[
  { "op": "add", "path": "/fields/System.Description", "value": "As a warehouse operator, I want to export an order's picking list as CSV, so that I can print it for the floor team." },
  { "op": "add", "path": "/multilineFieldsFormat/System.Description", "value": "Markdown" }
]
```

Azure DevOps MCP server — `wit_work_item_write` takes `format` per field (`"Html"` or `"Markdown"`); `add_child` defaults its `items[].format` to `Markdown`:

```json
{ "action": "create", "workItemType": "User Story",
  "fields": [
    { "name": "System.Title", "value": "Export picking list as CSV" },
    { "name": "Microsoft.VSTS.Common.AcceptanceCriteria",
      "value": "- Given order 1002 with 4 lines, when I choose \"Export CSV\", then `picking-1002.csv` downloads with a header row and 4 data rows.",
      "format": "Markdown" }
  ] }
```

When you write HTML instead (the safe default for an existing item that has always been HTML), keep it minimal — `p`, `ul`, `ol`, `li`, `strong`, `code`, `a` — and escape `<`, `>` and `&` in the text (`&lt;orderId&gt;`):

```html
<ul>
  <li>Given order 1002 with 4 lines, when I choose "Export CSV", then <code>picking-1002.csv</code> downloads with a header row and 4 data rows.</li>
  <li>Given an order with no lines, when I choose "Export CSV", then the message "Nothing to export" appears and no file downloads.</li>
</ul>
```

Markdown sent to a field still in HTML mode renders as a single line; HTML sent to a field switched to Markdown shows the tags.