Building a Semantic Calendar in HTML5

Recently, developer Wilfred Nas asked an interesting question on Twitter with regards to calendars being traditionally marked up in HTML with tables, and should they perhaps be lists instead. This got me thinking if we could make calendar markup more semantic using HTML5‘s time element.

For those of you who don’t know about HTML5‘s time element, it allows the definition of date/time content along with a machine-readable form of that content via its datetime attribute. Some examples of this might be:

<time datetime="2015-07">July 2015</time>
<time datetime="2015-07-03">today</time>
<time datetime="2015-07-03">3rd July 2015</time>
<time datetime="2015-W27">this week</time>
<time datetime="2015-07-03T12:00">today at midday</time>
<time datetime="2015">2015</time>

As you can see, time can be quite powerful as the visible content to the user can be different to the machine-readable value that it represents, and it can also represent a multitude of different types of date/time values. The W3C specification has a load more of examples.

Given the examples mentioned above, it should be possible to build a calendar in HTML using the time element that takes advantage of its properties and is therefore more semantic.

Therefore could be marked up as follows:

<time datetime="2015" class="year">
  <time datetime="2015-07" class="month">
    <time datetime="2015-W27" class="week">
      <time datetime="2015-07-01">1</time>
      <time datetime="2015-07-02">2</time>
      <time datetime="2015-07-03">3</time>
      <time datetime="2015-07-04">4</time>
      <time datetime="2015-07-05">5</time>
    <time datetime="2015-W28" class="week">
      <time datetime="2015-07-06">6</time>
      <time datetime="2015-07-07">7</time>
      <time datetime="2015-07-08">8</time>
      <time datetime="2015-07-09">9</time>
      <time datetime="2015-07-10">10</time>
      <time datetime="2015-07-11">11</time>
      <time datetime="2015-07-12">12</time>
    <time datetime="2015-W29" class="week">
      <time datetime="2015-07-13">13</time>
      <time datetime="2015-07-14">14</time>
      <time datetime="2015-07-15">15</time>
      <time datetime="2015-07-16">16</time>
      <time datetime="2015-07-17">17</time>
      <time datetime="2015-07-18">18</time>
      <time datetime="2015-07-19">19</time>
    <time datetime="2015-W30" class="week">
      <time datetime="2015-07-20">20</time>
      <time datetime="2015-07-21">21</time>
      <time datetime="2015-07-22">22</time>
      <time datetime="2015-07-23">23</time>
      <time datetime="2015-07-24">24</time>
      <time datetime="2015-07-25">25</time>
      <time datetime="2015-07-26">26</time>
    <time datetime="2015-W31" class="week">
      <time datetime="2015-07-27">27</time>
      <time datetime="2015-07-28">28</time>
      <time datetime="2015-07-29">29</time>
      <time datetime="2015-07-30">30</time>
      <time datetime="2015-07-31">31</time>

We could therefore build an entire semantic calendar in this way, making it look nicer with a bit of CSS.


Even though the specification indicates that the time element can contain phrasing content of which time is a part of, the W3C validator declares that The element time must not appear as a descendant of the time element, which seems a bit odd.

I did find a document on HTML markup and specifically the time element that does contain a constraint that prevents time from being nested, but this is an old document that is no longer valid and the new version of this mentions no such constraint. The WHATWG Wiki also recommends that nested time elements should be allowed, and this seems a good idea to me.

I have put the question to the W3C HTML Working Group about this and am awaiting an answer from my peers. I will update this article when I have more information.