Checklist Serialization Syntax Guide

This document aims to provide a comprehensive guide to the syntax used for serializing checklists into a string format. This feature allows checklists to be stored as strings, making them especially useful for automation, documentation, and import/export purposes. In this guide, we will explain the syntax that users should follow, how the serialization is parsed, and how it can be leveraged to streamline processes and enhance automation in Jira.

✅ Task Syntax

Each task must start on a new line with - (a hyphen followed by a space). This should be the first characters of the line. Our system uses this format to detect and parse individual tasks.

You may also include the following optional markers:

⚠️ You don’t need to manually include [ ] for unchecked tasks — if it's missing, the task will still be considered unchecked by default.

📝 [a:...] and [dd:...] are both optional. You can include them anywhere in the task line — at the start, middle, or end — and they will be correctly parsed.

✅ Examples

- [x] Finalize marketing plan [dd:2025-07-01] [a:abc123]
- ?[] Review legal documents
- Prepare slides   ← will be treated as: [] Prepare slides
- [a:dev123] [] Setup development environment
- [] Submit draft [a:writer789] [dd:2025-08-01]
- [] [dd:2025-09-15] Book venue [a:orgLead1]

🗂 Tasklist Syntax

Tasklists are defined using -- followed by a title. Each task belongs to the tasklist defined before it.

-- Marketing Launch
- [] Create campaign draft
- [x] Review assets [a:john123]

🔁 No Tasklist? No Problem!

If no tasklist title (-- ...) is found, all tasks will automatically be grouped into a default tasklist titled "Default Tasklist".

- [] Write user stories
- [x] Finalize sprint goal

Will be treated as:

-- Default Tasklist
- [] Write user stories
- [x] Finalize sprint goal

🧠 Multi-line & Advanced Syntax

📝 Multi-line Task Titles

We support multiline task content, meaning not every line is treated as a new task.

• A new task only starts when a line begins with - (a hyphen followed by a space).
• Any line that does not start with - is considered a continuation of the previous task's content.
• This allows you to write long or descriptive task content across multiple lines without breaking the structure.

Example:

-- Sprint Planning
- [] Discuss project scope
and timeline with team
- [] Set sprint velocity
- [] Prepare roadmap\
presentation slides for team leads

🛠 What the System Handles Automatically

📍 Where to Use This

You can use this serialized checklist format in several ways:

1. Issue Create Screen

Users can paste the serialized checklist directly into the input field during issue creation.
Once the issue is created, our system will automatically parse the input and generate the full checklist inside the issue.

This is perfect for teams who want a quick, manual way to define checklist content without templates or automation.

2. Jira Automation / API Integration

In automation rules or external integrations, you can set a custom field named:

Checklist text (Tick)

This field accepts a serialized checklist string. On issue creation, Tick will automatically read the content from this field and generate all corresponding checklists.

🧑‍💻 Using This Syntax in Rich Text Fields

If you're pasting a serialized checklist into a rich text field (like the Jira description or comment field), keep in mind:

⚠️ Jira's rich text editor may automatically apply formatting to certain characters like [, ], --, or ?, which can interfere with the correct interpretation of the checklist syntax.

To ensure the checklist is parsed correctly:

• ✅ Wrap the entire serialized text inside a code block.
• Use triple backticks ````` to start and end the block.

Example:

-- Tasklist Title
- [] First task
- [x] Completed task [dd:2025-07-01] [a:john123]

This prevents the editor from applying formatting or styles that could corrupt the structure, and ensures our parser can read it exactly as intended.

💡 This is considered a best practice when using this syntax in any formatted text field.

✨ Best Practices

• ✅ Use Jira accountId for [a:...] to assign tasks
• 📅 Use proper ISO dates like [dd:2025-09-01]
• 🧪 Test your input with a sample issue before scaling
• ✍️ Use multi-line formatting or \\ for clarity
• 🧹 Leave out [a:] or [dd:] if not needed — they’re optional

🛠 Example: Complex Use Case

-- Design Phase
- [] Create wireframes
- [x] Review UI with stakeholders [a:designLead123]

-- Development Phase
- [a:dev456] [] Set up repo
- [] Implement layout\\
responsive for all screen sizes
- ?[] Prepare handover notes [dd:2025-10-01]