Practical guide
Calendar Tasks: Read DUE, Progress and UTC Completion Separately
Keep a task’s expected due boundary separate from progress, its actual UTC finish and revision metadata. Compare three complete fictional VTODO files and check a date deadline before treating it as an end-of-day promise.
On this page
Choose an action item before choosing its date fields
A task due on Friday and a meeting held on Friday answer different questions. The task records work expected to be completed; the meeting records an event interval. If an export turns the task into a midnight event, changing that event’s end does not explain the original task’s deadline or whether the work is complete.
RFC 5545 provides VTODO for an action item or assignment. Its required component fields include UID and DTSTAMP. Start, due, completion, status and percent complete have distinct purposes. This guide uses ordinary nonrecurring DATE or UTC examples to keep those purposes visible. [1]
Read the component name in a retained export before changing fields. A VTODO can belong in a complete VCALENDAR object; do not insert it inside a VEVENT. The files below contain fictional practice data and no invitations, attendees or alarm delivery. Their format does not establish that a particular calendar app supports importing or displaying tasks.
Keep expected time, actual finish and progress separate
DUE describes when the task is expected to be completed. COMPLETED describes when it actually was completed, and must be a UTC DATE-TIME. Finishing early does not require moving the due boundary to the finish time. These are separate facts. [2]
| Field | Recorded value | Meaning and limit |
|---|---|---|
| DTSTART | 20270112T090000Z | The component begins at 09:00 UTC on January 12. It is not a measured work log. |
| DUE | 20270115T170000Z | The expected completion boundary is 17:00 UTC on January 15. It remains after completion. |
| COMPLETED | 20270115T163000Z | The fictional actual finish is 16:30 UTC, thirty minutes before the unchanged due boundary. |
| STATUS | COMPLETED | The overall task state is complete; this word does not supply a finish timestamp. |
| PERCENT-COMPLETE | 100 | The whole fictional task is complete. A progress value is not a time or an event duration. |
On a phone, scroll inside the table. Keyboard readers can focus its region and use the arrow keys.
For the shown task, keep DUE at 17:00Z and record COMPLETED at 16:30Z on January 15. The difference is thirty minutes. It describes the relationship between two timestamps, not time spent working. A task that was worked on intermittently for several days can have the same endpoints.
PERCENT-COMPLETE is an integer from 0 to 100: 0 means not started, 100 means complete, and intermediate values report partial completion. For assignments to multiple people, the RFC describes each person’s assigned portion; an arbitrary average of their numbers is not automatically the whole task’s progress. [3]
The task STATUS values are NEEDS-ACTION, IN-PROCESS, COMPLETED and CANCELLED. A VEVENT’s CONFIRMED value is not a task-status choice. The completed example here explicitly records both STATUS:COMPLETED and PERCENT-COMPLETE:100. Inspect all fields together rather than assuming that an application will update one whenever another changes. [4]
Read a DATE deadline at the correct boundary
A DATE value has a year, month and day with no clock fields. However, a task’s due date is not a promise that the whole written day remains available. RFC 5545’s own VTODO example uses DUE;VALUE=DATE:20070501, says the work needs to be completed before May 1, and states that it is overdue at midnight on May 1. [1]
The date-only practice file therefore uses DUE;VALUE=DATE:20270116 for a fictional boundary before January 16. Do not silently read a due value of January 15 as “up to 23:59 on January 15.” Confirm the intended date boundary and the task app’s interpretation. When a real deadline requires a precise clock and zone, record that explicitly rather than deriving it from an all-day label.
The UTC practice uses DUE:20270115T170000Z to state one fixed instant. It can display at a different local time in another zone while retaining that instant. A bare 20270115T170000 is floating time; it does not mean UTC simply because it contains the same digits. Numeric UTC-offset suffixes are not an allowed iCalendar DATE-TIME form. [5]
Use DUE for the task’s expected completion boundary. DTEND is a property of VEVENT or VFREEBUSY, not a replacement task-deadline field. The existing all-day event guide explains a different model: a DATE event interval and its busy-time transparency. Neither that event nor this task field establishes an organization’s legal deadline or a person’s actual availability.
Check the pair of fields before repairing a deadline
If DTSTART and DUE both occur in a VTODO, they must have the same value type, and DUE must be later than DTSTART. Their local-time form must also agree. For an ordinary date-only task with a start, choose matching DATE values; for a UTC task, use two UTC DATE-TIME values. The files below compare a date-only DUE without a start with UTC start/due pairs. They do not test named-zone definitions or daylight-saving transitions. [2]
A task may use an explicit DUE or a positive DURATION, but not both. If DURATION is used, DTSTART is required. For a DATE-valued start, the duration must use days or weeks. The duration describes the task’s defined span in place of its due field; it is not percent complete, a finish timestamp or an alarm repetition interval. [1] [6]
| Observation | Complete field issue | Rule being checked | Next decision |
|---|---|---|---|
| DATE start with UTC DUE | DTSTART;VALUE=DATE:20270112 and DUE:20270115T170000Z | The two values have different types. | Choose matching DATE values or matching DATE-TIME values for the intended task. |
| Start equals DUE | Both are 20270115T170000Z. | DUE must be later than DTSTART when both occur. | Record the genuine earlier start or revise the intended due boundary. |
| DUE and DURATION together | A VTODO includes both DUE and DURATION. | The component requires a choice between them. | Keep an explicit DUE, or use a positive DURATION with DTSTART. |
| Local completion string | COMPLETED:20270115T163000 | COMPLETED requires a UTC DATE-TIME. | Establish the real finish instant, then encode its UTC value with Z. |
On a phone, scroll inside the table. Keyboard readers can focus its region and use the arrow keys.
Keep the original bytes before repairing a field. A mismatched DATE and DATE-TIME pair can mean that the export changed one value type, or that the author never chose a single deadline model. Deleting the start to silence a check would discard a fact unless you first confirm that the task genuinely has no recorded start.
Compare three complete fictional task files
The first file is a separate date-boundary example. The second and third are alternative snapshots of one fictional UTC task, with the same UID and unchanged DTSTART and DUE. They are shown for field comparison; importing both is not a tested update procedure. The ICS import guide explains why matching identity fields do not promise replacement behavior.
Date-boundary practice
Download date-boundary practice (.ics)
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//DayMoon Calendar//Fictional Task Reading 1.0//EN
BEGIN:VTODO
UID:todo-date-practice@daymooncalendar.com
DTSTAMP:20270111T090000Z
DUE;VALUE=DATE:20270116
SUMMARY:Fictional date-boundary task
STATUS:NEEDS-ACTION
PERCENT-COMPLETE:0
END:VTODO
END:VCALENDAR
UTC task in progress
Download utc task in progress (.ics)
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//DayMoon Calendar//Fictional Task Reading 1.0//EN
BEGIN:VTODO
UID:todo-utc-practice@daymooncalendar.com
DTSTAMP:20270112T090000Z
DTSTART:20270112T090000Z
DUE:20270115T170000Z
SUMMARY:Fictional task field review
STATUS:IN-PROCESS
PERCENT-COMPLETE:60
END:VTODO
END:VCALENDAR
UTC task completed
Download utc task completed (.ics)
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//DayMoon Calendar//Fictional Task Reading 1.0//EN
BEGIN:VTODO
UID:todo-utc-practice@daymooncalendar.com
DTSTAMP:20270115T163500Z
DTSTART:20270112T090000Z
DUE:20270115T170000Z
COMPLETED:20270115T163000Z
SUMMARY:Fictional task field review
STATUS:COMPLETED
PERCENT-COMPLETE:100
END:VTODO
END:VCALENDAR
Each file has a VCALENDAR wrapper and one VTODO. The specimen checks verify the finite DATE/UTC forms, component delimiters, matching start/due types, later due boundary, allowed shown status and progress values, UTC completion and short CRLF-terminated lines. Negative field fixtures check specific rejections. These checks cover the shown subset; they do not certify a general iCalendar parser or any calendar-account import.
DTSTAMP is UTC metadata. Because these specimens omit METHOD, the RFC uses DTSTAMP for the component information’s last revision in the calendar store. The completed snapshot’s fictional revision is 16:35Z, five minutes after its fictional 16:30Z completion. DTSTAMP does not replace COMPLETED and does not determine DUE. [7]
Write a complete deadline and completion record
This is a completed fictional review record, not a report from a real task account. It gives a second reader the fields, the interpretation and the unresolved application check in one place.
- Owner and scope
- Theo is preparing a nonrecurring practice field-review task. It has no invitations, shared assignment protocol, recurrence or actual work log.
- Start and expected boundary
- DTSTART 20270112T090000Z; DUE 20270115T170000Z. Both are UTC DATE-TIME; the due instant is later.
- Actual finish in the fictional record
- COMPLETED 20270115T163000Z. It is thirty minutes before the due instant; the due field is unchanged.
- Progress and state decision
- STATUS COMPLETED and PERCENT-COMPLETE 100 are explicitly recorded for the same whole task.
- Revision metadata
- DTSTAMP 20270115T163500Z records the fictional later component revision. It is five minutes after completion and has a different role.
- Application observation and next check
- No real app import, task display, completion action or busy-time search has been performed. First verify the service supports tasks, then compare a non-sensitive single-task export with its supported view.
If the app shows a different date or drops completion information, retain its actual export and the observed view. Identify whether it changed the component, a value type, the time interpretation or a task field. A second import or a changed UID cannot establish which stage lost the intended meaning.
Try three complete task-date decisions
Use the stated fictional fields to answer each question before opening its explanation.
Case 1
A VTODO has DUE;VALUE=DATE:20270115. A colleague reads this as permission to finish at 23:59 on January 15. Does the RFC example support that assumption?
Show answer and explanation for case 1
No. Do not silently extend the written DATE deadline to the end of that day.
The RFC’s DATE example says before the due date and overdue at midnight on that date. Confirm the intended boundary and app interpretation; use an explicit clock and zone when the actual deadline needs them.
Case 2
The UTC task was due at 17:00Z on January 15 and completed at 16:30Z. Should DUE become 16:30Z so the file says it is finished?
Show answer and explanation for case 2
Keep DUE at 17:00Z and record COMPLETED at 16:30Z.
Expected completion and actual completion are different fields. This fictional finish is thirty minutes early. The explicit completed state and percent 100 describe progress; none of them require rewriting the expected boundary.
Case 3
A VTODO contains DURATION:PT1H but no DTSTART. Can the duration by itself define an exact due instant?
Show answer and explanation for case 3
No. A VTODO using DURATION also requires DTSTART.
Choose a genuine start plus a positive duration, or an explicit DUE appropriate to the task. DUE and DURATION must not occur together. A bare duration contains no date from which to derive an instant.
Sources and further reading
- RFC 5545 — To-do componentAction-item model, required component fields, DUE/DURATION constraints and the explicit DATE midnight example; section 3.4 container also read.
- RFC 5545 — Due and actual completionComplete DUE and COMPLETED clauses read; expected boundary, matching start and UTC actual finish.
- RFC 5545 — Percent completeInteger range and separately assigned portions.
- RFC 5545 — Task status valuesVTODO status choices; event confirmation has separate values.
- RFC 5545 — DATE and DATE-TIME formsBoth complete value clauses read; floating and UTC forms. Named-zone/DST/leap-second details not adopted here.
- RFC 5545 — Task durationComplete duration and start clauses read; alternative to explicit DUE, required start and day/week form for DATE starts.
- RFC 5545 — Revision timestampUTC DTSTAMP and its meaning when METHOD is absent. Source is RFC 5545, September 2009; retrieval is November 17, 2026, not a newly issued rule.