12 KiB
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