Dates in XBRL
Creating XBRL reports frequently requires making explicit information that was previously only implicit. Human readers often infer information from context and convention, whereas the goal of XBRL is to create unambiguous, standalone structured data.
A good example of this is the handling of dates and time periods. Reports often describe reporting dates and periods in ways that are imprecise or ambiguous in isolation. This can easily lead to misinterpretation of the information by a machine, even though, in context, the meaning is clear to a human reader. In order to ensure accurate analysis of a report by software it is vitally important that dates are marked up with XBRL in a consistent, logical and precise manner.
In this blog we’ll look at just a few examples of the many ways that dates are typically presented in human-readable reports, and why the conventions used there can cause confusion when creating XBRL data. We’ll also discuss how dates and periods work in XBRL, and look at the notations used for dates in the different XBRL formats, including Inline XBRL, xBRL-JSON and xBRL-CSV. This blog will get into technical details that should generally be hidden from end users by XBRL software, but it will hopefully provide some useful insight to why converting dates in human-readable reports to structured data is so important.
Who is this for? The good news, of course, is that modern XBRL software tends to hide away these details, but it doesn’t hurt for external reporting, accounting and audit professionals — as well as software developers that might be coming to these issues afresh — to be familiar with the details.
Dates and time periods in XBRL
All reported facts in XBRL must carry a date as part of their metadata, telling software (as well as human readers) exactly what point or period in time the fact relates to.
Let’s consider the following cash flow statement:
The statement gives balances at three dates:
- 1st April 2022
- 1st April 2023
- 31st March 2024
But a date refers to a day – a 24-hour period. Is the balance reported as of the start or end of the stated day? The answer is that it depends. For the first two dates, the report is referring to the balance before 1st April, whereas in the third case it’s the balance after 31st March. This table is using exactly the same language (“balance at”) to mean two different things: “balance before” and “balance after”. As a human reader, I can infer this from the context, but in XBRL, facts are expected to be unambiguously understandable in isolation; they can’t rely on context for meaning.
XBRL removes this ambiguity by always referring to periods using both dates and times, not just dates, thereby making it explicit whether we’re talking about the start or end of a day. XBRL uses the ISO8601 standard for dates and times, and all periods are reported using the combination of a date and a time – a “datetime”. The three dates in this report are represented in XBRL as the following datetimes:
- 2022-04-01T00:00:00
- 2023-04-01T00:00:00
- 2024-04-01T00:00:00
In each case we use midnight at the start of the stated date. This is the instant at the end of one reporting period and the start of the next. What was implicit in a human-readable report becomes explicit in XBRL.
The last case causes some confusion because the date part doesn’t directly match the presentation used in the human-readable report, but it does accurately reflect the meaning of the report. There really is only a single instant between the end of one reporting period and the start of the next, but a human-readable report describes it in two different ways depending on context and convention.
For example, elsewhere in this same report, we have the Statement of Changes in Equity:
The structure of this table is very similar to the previous one, but it uses different dates:
- 31st March 2022
- 31st March 2023
- 31st March 2024
Are the figures for the first two dates really stated a day earlier than those in the previous table? No – this table is just using a different convention for labelling the same points in time. In XBRL, these are tagged consistently using the same three instants as before:
- 2022-04-01T00:00:00
- 2023-04-01T00:00:00
- 2024-04-01T00:00:00
Instants and durations
All concepts in XBRL have an intrinsic period type, which can be either “duration” or “instant”. Concepts that are reported as of a moment in time, such as assets or liabilities, are “instant” concepts and facts for such concepts are reported with a single datetime. Concepts that are reported over a period in time, such as revenue or profit, are “duration” concepts, and facts are reported using a pair of datetimes identifying the start and end of the duration.
Technical formats
At a semantic level, dates and time periods in XBRL are very simple. XBRL treats all facts as having a time period that is either a single datetime (representing an instant) or the duration between two datetimes.
At a syntactic level, different XBRL formats do allow some additional notations for representing those periods in a more efficient or intuitive way. These are discussed below.
Periods in xBRL-XML and Inline XBRL
XBRL 2.1’s original XML syntax (now referred to as “xBRL-XML”), and Inline XBRL, allow periods to be represented as ISO8601 datetimes, but also permit a shorthand notation for reporting periods using just dates.
When reporting an instant using a date, it is interpreted as referring to the end of the stated date, so the following are completely equivalent:
<period> <instant>2024-03-31</instant> </period><period> <instant>2024-04-01T00:00:00</instant> </period>
When reporting a duration using dates, the start date is interpreted as referring to the start of the day, and the end date refers to the end of the stated day, so the following two are equivalent:
<period> <startDate>2023-04-01</startDate> <endDate>2024-03-31</endDate> </period><period> <startDate>2023-04-01T00:00:00</startDate> <endDate>2024-04-01T00:00:00</endDate> </period>
The different interpretation applied to start dates attempts to reflect the human convention of describing periods using inclusive dates. In ordinary language, “1st April 2023 to 31st March 2024” is understood to mean the one-year period including both of those dates.
Unfortunately, this approach has created a lot of confusion and a lot of tagging errors, because the same date denotes a different datetime depending on the element that it appears in.
For example, an opening balance reported “as of 1st April” is sometimes incorrectly tagged as:
<period> <instant>2023-04-01</instant> </period>
This is interpreted as meaning the end of 1st April — 24 hours too late. Although such tagging errors have become less common as software has improved, the use of simple dates invites such errors.
The reality is that human-readable reports often describe dates in a way that is ambiguous in isolation, and you need to correctly understand what they mean in order to tag them in XBRL.
Periods in xBRL-JSON
In 2021, two new formats for XBRL data were published: xBRL-JSON and xBRL-CSV. These formats share a common data model (“The Open Information Model”) that is compatible with xBRL-XML.
xBRL-JSON is designed to be easy for software to consume, and to this end, it requires that periods are all reported consistently using full datetimes. An instant fact would be reported using a period property, as follows:
"period": "2024-04-01T00:00:00"
A duration fact is reported using a pair of datetimes:
"period": "2023-04-01T00:00:00/2024-04-01T00:00:00"
There is no option to use shorthand dates in xBRL-JSON. This simplifies things for consuming software, and significantly reduces the chances of tagging errors.
Periods in xBRL-CSV
xBRL-CSV allows XBRL data to be reported in CSV format. xBRL-CSV is designed to enable a flexible, compact representation of data, and to this end, it permits a variety of shorthand period formats that can be used in CSV data, in addition to the same explicit formats supported by xBRL-JSON.
For example, an inclusive period can be specified using a pair of dates combined with “..”, so the following two are equivalent:
- 2023-04-01..2024-03-31
- 2023-04-01T00:00:00/2024-04-01T00:00:00
A calendar year can be specified using just the year, so the following are all equivalent:
- 2023
- 2023-01-01..2023-12-31
- 2023-01-01T00:00:00/2024-01-01T00:00:00
xBRL-CSV permits the use of single dates, but these represent a one-day duration, not an instant. For example, the following two are equivalent and both specify a 24-hour duration:
- 2023-04-01
- 2023-04-01T00:00:00/2023-04-02T00:00:00
When defining the period for an instant fact, this can either be defined explicitly using a single datetime, as per xBRL-JSON, or it can be taken from the start or end instant of a duration. For example, the following are all equivalent:
- 2023@end
- 2023-12-31@end
- 2024-01-01@start
- 2024-01-01T00:00:00
Similarly:
- 2023@start
- 2023-01-01@start
- 2022-12-31@end
- 2023-01-01T00:00:00
xBRL-CSV uses metadata that defines how data in a CSV report maps into XBRL data, and the “@start” and “@end” selectors are more commonly used in that metadata, applying to all dates in a column and enabling efficient and intuitive reporting. For example, the metadata could say:
- $refDate@end
and this would mean “take the instant at the end of the duration reported in the ‘refDate’ column”. The ‘refDate’ column could then report a date, such as “2023-12-31”, and this would be interpreted as meaning the instant at the end of 31st December 2023.
Syntax vs display
I should emphasise that this blog post is about the technical formats used for periods in XBRL reports in order to enable unambiguous consumption of that data by software. Software that presents XBRL data to users can and should use whatever formats will be most clear and intuitive to those users. For example, software can (and probably should) display “2023-01-01T00:00:00/2024-01-01T00:00:00” as something like “1st Jan 2023 to 31st Dec 2023” or an equivalent using localised conventions and language. Similarly, XBRL report creation software will take care of converting human-readable dates into the correct technical format required by XBRL.
What about T24:00:00 ?
Throughout this blog, we’ve used T00:00:00 to mean midnight at the start of a day. ISO 8601 also supports the syntax T24:00:00 to mean midnight at the end of the stated day. None of the XBRL formats support the T24:00:00 syntax: you must use the T00:00:00 on the following day, which is completely equivalent.
When XBRL v2.1 (xBRL-XML) was finalised in 2003, the XML Schema standard did not support T24:00:00. Later versions of XML Schema do support T24:00:00, but in order to avoid interoperability issues, this format is not permitted in xBRL-XML.
xBRL-JSON and xBRL-CSV do reference the newer XML Schema standard that supports T24:00:00, but they also require that periods are reported in their “canonical representation”. The canonical representation of T24:00:00 datetime is T00:00:00 on the following day, which is completely equivalent.
It’s also worth noting that ISO8601 itself dropped support for T24:00:00 in 2019, although it was reinstated in an update in 2022!
Summary
In order to create unambiguous data, the periods associated with XBRL facts always include a time component. This is usually midnight at the start of the stated date, or “T00:00:00”. When working with XBRL:
- Make sure that periods accurately reflect the intended meaning of the data.
- The dates used in XBRL syntax may not exactly match the date conventions used in human-readable reports.
- In common usage, end dates and closing balances usually refer to the end of the stated date. In XBRL, this is represented as midnight at the start of the next day.
- xBRL-XML and xBRL-CSV permit some shorthand formats that don’t include a time component; make sure you understand how these will be interpreted.
- Use certified XBRL software to view and create XBRL reports. XBRL software should display dates to users in an intuitive way, and guide users to tag dates correctly.
