---
title: 'DDD Annotations'
url: 'https://www.twelvetone.tv/docs/developer-tools/document-driven-design/ddd-annotations'
markdown: 'https://www.twelvetone.tv/docs/developer-tools/document-driven-design/ddd-annotations.md'
date: '2026-09-25'
description: 'DDD annotations can be placed in source code comments and wiki documents. Syntax'
taxonomy:
  category:
    - docs
  devtype:
    - private
---

[](#)  [ Home ](https://www.twelvetone.tv/docs/)     [ Developer Tools ](https://www.twelvetone.tv/docs/developer-tools)     [ Document Driven Design (DDD) ](https://www.twelvetone.tv/docs/developer-tools/document-driven-design)      DDD Annotations    

# DDD Annotations

DDD annotations can be placed in source code comments and wiki documents.

# Syntax

The format is:

```none
 ~TYPE FIELDS* MESSAGE*~
```

|  |  |
|---|---|
| TYPE | The type of annotation. |
| FIELDS | An optional list of key:value pairs. A colon separates the key and value. |
| MESSAGE | Optional content of the annotation. |

- DDD annotations are placed between tildes. The first tilde must be the first character on a line.
- Field keys and values must use quotes if they contain spaces or escaped quotes.
- Message cannot contain the tilde character.

Fields and content syntax are specific to each annotation type.

# Examples

A task with 3 fields.

```
 ~task status:inprogress priority:high description:"Fix spelling" ~
```

A task with 2 fields, and content.

```
 ~task status:inprogress priority:high Fix spelling ~
```

Using whitespace.

```
 ~task 
    status : inprogress 
    priority : high 
    Fix spelling ~
```

Implied fields. For example, the *task* annotation can extract fields from the content).

```
 ~task in-progress 50% spellcheck this document~
```

# JSON Format

When represented as JSON, the structure is:

```json
[
    {
        "type":"feature",
        "fields":{"priority":"low","release":"next"},
        "message":"Add a spellcheck option to the editor."
    },
    {
        "type":"bug",
        "fields":{"priority":"high","release":"current"},
        "message":"Smoke comes out of the server."
    }
]
```

# Standard Tags and Annotations

How to markup docs with:

- unreviewed
- incomplete
- placeholders
- replaceable text
- linked info
- new features
- feature release
- bug fixes

# Issue Management (task|bug|feature|todo)

Specifies issues related to software improvement.

## Optional fields

- completed status
- queue status
- category
- target release

If the annotation does not contain a caption, the preceding line is used as the caption. If the caption is '*document* or *implement*, the preceding line is appended to the caption.

# Documentation Type (type)

Specifies the type of documentation. This annotation is active until replaced with another declaration. Multiple documentation types can be specified.

| Symbol | Type |
|---|---|
| u | User |
| d | Developer |
| i | Implementor |
| p | Purchaser |
| a | Acquirer |

You can use the full or partial name instead of a single letter.

```
 ~type u ~
user doc here...

 ~type developer ~
developer doc here...

 ~type u i~
implementer and user doc here...
```

 [ ](https://www.twelvetone.tv/docs/developer-tools/document-driven-design/ddd-benefits) [](https://www.twelvetone.tv/docs/developer-tools/document-driven-design/documentation-types)

---

## Navigation

- Parent: [Document Driven Design (DDD)](https://www.twelvetone.tv/docs/developer-tools/document-driven-design.md)
- Previous: [DDD Benefits](https://www.twelvetone.tv/docs/developer-tools/document-driven-design/ddd-benefits.md)
- Next: [Documentation Types](https://www.twelvetone.tv/docs/developer-tools/document-driven-design/documentation-types.md)