takentaal/takentaal.spec.1.0.md

# TakenTaal Spec

Version 1.0

## Abstract

TakenTaal is a plain text format for writing plans that describe work that is to
be performed within the context of a grant. It is designed to be the document
that is written by recipients of a grant and sent to the reviewers of that
grant. The syntax allows these documents to be parsed by machines and audited
and validated using automated tooling.

A TakenTaal document looks as follows:

```
takentaal v1.0

# {10000} Project Name

This is the description of the entire work plan.

## {1000} First task

This is the description of the first task.

- {500} First subtask
- {500} Second subtask

## {2000} Second task

This is the description of the second task.

- { 750} First subtask
- {1250} Second subtask
```

## 1. Introduction

The specification was written by the NLnet Foundation to facilitate the
communication of intended work between them and their grantees.

TakenTaal is a Dutch closed compound word translating in English to "language of
tasks".

The specification was written with several goals in mind:

- TakenTaal documents should describe and divide work in tasks and subtasks,
- TakenTaal documents should be flat, concise and unambiguous,
- TakenTaal documents should be auditable,
- TakenTaal documents should be diffable,
- TakenTaal documents should be lockable,
- TakenTaal documents should be amendable.

Definitions for some of these requirements are provided in the Definitions
section.

This specification will offer suggestions on how to process the documents and
what to do with the results of the processing, but ultimately it is up to the
implementation to decide on the processing rules. For example, implementations
could allow under- and/or overbudgeting, in which case an audit of such a
document should merely result in a warning, not a rejection.

It is important to note that these documents are not designed for automated
reviewing, they are designed to be reviewed by humans and to be parsed by tools
that will assist in the reviewing process.

## 2. Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be
interpreted as described in RFC2119.

This specification uses the Augmented Backus-Naur Form (ABNF) notation of
RFC2234. The following definitions are also used in this document:

character: A valid Unicode character

ucalpha: Uppercase alphabetical characters (A-Z)

## 3. Definitions

A title is a sequence of characters on a single line. It SHOULD provide a clear
and concise summary of the data structure it belongs to.

A description is a sequence of characters that MAY be divided in multiple lines.
It SHOULD provide more details and context to the data structure it belongs to.

An amount is an integer and represents a monetary value. It SHOULD provide a
financial context to the data structure it belongs to.

A work plan is a data structure that consists of the following elements:

- a title,
- a description,
- an expected amount (optional),
- a set of tasks.

A task is a data structure that consists of the following elements:

- a title,
- a description,
- an expected amount (optional),
- a set of subtasks.

A subtask is a data structure that consists of the following elements:

- a title,
- an amount.

Auditing a TakenTaal document refers to the process of parsing the document and
comparing and validating the amounts against the expected amounts of the plan,
the tasks and the subtasks.

Diffing a TakenTaal document refers to the process of providing feedback to the
reader of the document on the exact changes that ocurred between copies of the
same document.

Locking a TakenTaal document (partially) refers to the process of marking parts
of the document with special flags that will disallow any modification to said
parts when amending the document.

Amending a TakenTaal document refers to the process of taking a fixed version of
the document, making a copy of that document, editing the copy, and receiving
feedback from the parser whether the edits are allowed to be merged back into
the original document.

## 4. Document syntax

In short, documents are formatted as follows:

- the first line is "takentaal v1.0"
- lines beginning with "# " are the title of the plan,
- lines beginning with "## " are the title of a task,
- lines beginning with "- " are a subtask,
- in amendments, lines beginning with "/ ", "* " or "! " are subtasks with
  a special status,
- all other lines are the description of the plan or a task.

Titles MAY be preceded by an amount in curly brackets.

Descriptions consists of paragraphs, each paragraph corresponding to a single
line of text.

### 4.1 Characters and lines

TakenTaal documents are sequences of valid Unicode characters.

TakenTaal documents are parsed line for line, where lines are separated by
newline characters.

### 4.2 Header

TakenTaal documents MUST begin with a header line announcing the version of the
TakenTaal spec used. The TakenTaal spec you are currently reading expects the
version to be "1.0".

The header is formatted as follows:

    header = "takentaal v1.0"

### 4.3 Title

TakenTaal documents MUST contain a plan title and MAY contain task titles and
subtask titles.

A title is formatted as follows:

    title = character *(character / SP)

### 4.4 Description

TakenTaal documents MAY contain description lines for plans or tasks.

A description line is formatted as follows:

    description = character *(character / SP)

Two description lines interrupted by a newline MUST be separated into two
paragraphs.

### 4.5 Amount

TakenTaal documents MAY contain financial amounts. Amount MAY contain spaces,
useful to align them for visual clarity.

A financial amount is formatted as follows:

    amount = "{" *SP 1*DIGIT *SP "}"

### 4.6 Plan

A TakenTaal document, in its entirety, represents a plan. All lines of the
document that are placed above the first task declaration describe the plan
itself.

A line that gives the plan a title MUST be formatted as follows:

    plan-title = "# " *SP [amount] *SP title

A TakenTaal document MUST have one title. Subsequent lines formated as the
plan-title MUST be added to the description of the plan.

Every line that does not follow the format mentioned above is considered part of
the description of the plan.

### 4.7 Task

A task MUST always begin with the declaration of its title. The definition of
the task ends either with the declaration of a new task, or the end of the
document.

A line that declares a task's title is formatted as follows:

    task-title = "## " *SP [amount] *SP title

A line that declares a subtask is formatted as follows:

    subtask = subtask-status *SP [amount] *SP title

Every subtask has its status encoded in the first character of the line. The
subtask status is formatted as follows:

    subtask-status = "-" / "/" / "*" / "!"

The subtask status characters have the following meaning:

- "- ": the subtask is considered new
- "/ ": the subtask is considered partially completed
- "* ": the subtask is considered fully completed
- "! ": the subtask is considered cancelled

with the last three being only available in amendments.

Every non-empty line that does not follow the formats mentioned above is
considered a paragraph of the description of the task.

## 5. Document processing

### 5.1 Auditing

The goal of auditing a TakenTaal document is to match the amounts of the plan,
the tasks and the subtasks. By default, the plan amount SHOULD be equal to the
sum of the task amounts. The task amount SHOULD be equal to the sum of the
subtask amounts.

If amounts do not match, it is up to the implementation to decide whether to
entirely reject the plan, or simply warn the reviewer.

Cancelled subtasks MUST NOT be considered during auditing.

### 5.2 Diffing

The goal of diffing a TakenTaal document with an older version of itself is to
compare the changes between the two versions and observe what was changed. This
process is usually applied when amending a document. This is helpful for both
the writers and the reviewers of the document, to clearly understand what an
amendment exactly changes to a document.

Because these documents are plain text, most plain text diff tools and
algorithms should work.

### 5.3 Amending

A TakenTaal document amendment communicates the intent to change parts of the
work plan. This includes changing titles and/or description, changing an item's
associated amount, and/or adding/removing tasks/subtasks.

An amendment is an entire TakenTaal document, usually a copy of the original
document, which was then modified. Amendments can be plain text diffed against
the original document to observe what changes are introduced by the amendment.

Updating a subtask status SHOULD be done by the reviewers in their copy of the
document. If so, amendments SHOULD NOT be used to update a subtask status.

### 5.4 Validating an amendment

To assist with reviewing the amendments and avoid modifications that may
invalidate the documents, TakenTaal documents can be partially locked using
status indicators. These indicators are machine-parsable to allow for automated
validation.

Imagine a scenario where one of the subtasks was already (partially) completed
and paid out. Amendments MUST be disallowed to modify that subtask.

This is where locking a subtask comes in. Subtasks can be locked by using any
status indicator other than "-" (see 4.7). When locked, a subtask MUST not be
allowed to receive modifications in the following properties:

- title,
- amount,
- index (optional).

The index is the position of the subtask in the work plan: a subtask with index
"3.2" is the second subtask of the third task, in the order that they appear in
the TakenTaal document. Implementations are RECOMMENDED to lock this index as
well. To keep the index locked, subtasks MUST NOT be added or removed above the
locked subtask. Instead of removing a subtask, they can be marked as cancelled
with the "!" status character, hiding them from document audits while
maintaining their index and the indexes of subtasks after it. It is RECOMMENDED
to always put added subtasks after existing subtasks.

Tasks SHOULD be locked by default and SHOULD be cancelled by cancelling all
their subtasks. Tasks SHOULD NOT be allowed to be edited or removed. It is
RECOMMENDED to add a new task at the end of the document instead.

The original document MUST be stored by the reviewing party and MUST be used to
validate the incoming amendment for amendment validation to be reliable. The
document editors supply the amendment, but the reviewers MUST validate the
incoming amendment against their own version of the original document.

The status indicators in the original document SHOULD take precedence over the
ones in the amendment. For example, a subtask that is locked in the original
document SHOULD NOT be unlocked by an amendment. 

Implementations decide what types of status indicator update to allow. For
example, they COULD allow amendments to mark a subtask as cancelled but disallow
amendments to mark a subtask as completed.

Implementations SHOULD provide detailed feedback about why an amendment is
invalid, to clearly communicate what rules are followed by the implementation.

## 6. Examples

Example 1: a minimal TakenTaal document:

```
takentaal v1.0
# Project Name

This is the description of the entire work plan.

## First task

This is the description of the first task.

- {500} First subtask
- {500} Second subtask

## Second task

This is the description of the second task.

- { 500} First subtask
- {1500} Second subtask
```

Example 2: a full valid TakenTaal document:

```
takentaal v1.0
# {3000} Project Name

This is the description of the entire work plan.

## {1000} First task

This is the description of the first task.
This line is still part of the first paragraph of the description.

This is a second paragraph of that description.

- {500} First subtask
- {500} Second subtask

## {2000} Second task

This is the description of the second task.

- { 500} First subtask
- {1500} Second subtask
```

Example 3: a document with status indicators:

```
takentaal-amendment v1.0
# Project Name

## {500} First task

! {500} This subtask has been cancelled
* {500} This subtask has been completed

## {500} Second task

/ {500} This subtask was partially completed
```

Example 4: a document that gets flagged during auditing (amounts mismatch):

```
takentaal v1.0
# Project Name

## First task {2000 EUR}

- {500} First subtask
- {500} Second subtask
```