In HTML, what does the datetime attribute on the <time> element do, and when may you omit it?

## The problem `<time>` solves Human-readable dates are ambiguous and endlessly varied: "March 5", "5/3", "last Tuesday", "in two hours". Machines that want to read a page — search crawlers, feed generators, calendar importers, your own scripts — cannot parse all of that reliably. `<time>` lets you keep the prose you actually want to show and attach the unambiguous value beside it: ```html <p>The workshop starts <time datetime="2026-03-05T14:30-05:00">Thursday at 2:30pm</time>.</p> ``` The visible text is for people; `datetime` is for machines. Neither constrains the other, which is the whole point. ## The permitted values `datetime` must be a **valid date/time string** as HTML defines it, and the vocabulary is wider than most people expect: - a date — `2026-03-05` - a month — `2026-03` - a year — `2026` - a week — `2026-W10` - a yearless date — `03-05` - a time — `14:30`, `14:30:15`, `14:30:15.500` - a local date and time — `2026-03-05T14:30` - a global date and time, with `Z` or a numeric offset — `2026-03-05T14:30Z`, `2026-03-05T14:30-05:00` - a time-zone offset on its own — `-05:00` - a duration — `PT2H30M`, `PT30M`, `P3D` Durations use the `P…T…` form: `P` opens the period, `T` separates the date part from the time part, so two and a half hours is `PT2H30M`, not `2:30` and not `T2H30M`. A space-separated duration form is also permitted (`2h 30m`), but the `PT` form is the one to say in an interview because it is unambiguous and universally accepted. A value the parser cannot read is simply not a valid `<time>` value — you do not get a browser error, you get silence, which is why validators matter here. ## When you may omit the attribute If the element's own text content is already a valid date/time string, `datetime` is redundant: ```html <time>2026-03-05</time> <!-- fine, text is machine-readable --> <time>March 5, 2026</time> <!-- no machine-readable value at all --> ``` The second example is the trap. Nothing errors, nothing renders differently, and a naive reviewer sees `<time>` and assumes the page is machine-readable. It is not: browsers do not parse English dates out of text content. ## What `<time>` does not do Three over-claims come up constantly: - **It does not format or localise.** There is no built-in "render this in the user's locale" behaviour. If you want a localised string you produce it yourself and put it in the text content. - **It does not produce a relative time.** "3 hours ago" is text you compute; the element only records what the absolute value is. - **It has no default assistive-technology behaviour.** A screen reader reads the visible text, not the attribute. So if the visible text is `5/3` and you meant March 5, the attribute does not rescue the reader — fix the text. It also has no default styling of its own, and it is phrasing content, so it sits inside a sentence like any other inline element. ## Where it pays off The common wins are content pipelines: an article's publication date that a feed builder or crawler can read, an event listing whose start and end are unambiguous, a recipe's prep duration, or a `<time>` inside a comment that your client-side code reads to render "2 hours ago" without re-parsing prose. It is also the honest markup even when nothing consumes it yet, because it costs one attribute and makes the intent explicit. ## Pitfalls to name Putting a display string in `datetime` (`datetime="March 5"`), which is invalid. Using `<time>` for things that are not dates or times — a duration is fine, but a version number or a page count is not. Mixing a local date-time with a text that implies a time zone, leaving readers in another region to guess: if the zone matters, use the global form with `Z` or an offset. And assuming `<time>` gives you structured data on its own — it is a machine-readable value in the document, not a schema.