DatetimeV2 prebuilt entity for a LUIS app

Important

LUIS will be retired on October 1st 2025 and starting April 1st 2023 you will not be able to create new LUIS resources. We recommend migrating your LUIS applications to conversational language understanding to benefit from continued product support and multilingual capabilities.

The datetimeV2 prebuilt entity extracts date and time values. These values resolve in a standardized format for client programs to consume. When an utterance has a date or time that isn't complete, LUIS includes both past and future values in the endpoint response. Because this entity is already trained, you do not need to add example utterances containing datetimeV2 to the application intents.

Types of datetimeV2

DatetimeV2 is managed from the Recognizers-text GitHub repository.

Example JSON

The following utterance and its partial JSON response is shown below.

8am on may 2nd 2019

"entities": {
    "datetimeV2": [
        {
            "type": "datetime",
            "values": [
                {
                    "timex": "2019-05-02T08",
                    "resolution": [
                        {
                            "value": "2019-05-02 08:00:00"
                        }
                    ]
                }
            ]
        }
    ]
}

Subtypes of datetimeV2

The datetimeV2 prebuilt entity has the following subtypes, and examples of each are provided in the table that follows:

  • date
  • time
  • daterange
  • timerange
  • datetimerange

Values of resolution

  • The array has one element if the date or time in the utterance is fully specified and unambiguous.
  • The array has two elements if the datetimeV2 value is ambiguous. Ambiguity includes lack of specific year, time, or time range. See Ambiguous dates for examples. When the time is ambiguous for A.M. or P.M., both values are included.
  • The array has four elements if the utterance has two elements with ambiguity. This ambiguity includes elements that have:
    • A date or date range that is ambiguous as to year
    • A time or time range that is ambiguous as to A.M. or P.M. For example, 3:00 April 3rd.

Each element of the values array may have the following fields:

Property name Property description
timex time, date, or date range expressed in TIMEX format that follows the ISO 8601 standard and the TIMEX3 attributes for annotation using the TimeML language.
mod term used to describe how to use the value such as before, after.
type The subtype, which can be one of the following items: datetime, date, time, daterange, timerange, datetimerange, duration, set.
value Optional. A datetime object in the Format yyyy-MM-dd (date), HH:mm:ss (time) yyyy-MM-dd HH:mm:ss (datetime). If type is duration, the value is the number of seconds (duration)
Only used if type is datetime or date, time, or `duration.

Valid date values

The datetimeV2 supports dates between the following ranges:

Min Max
1st January 1900 31st December 2099

Ambiguous dates

If the date can be in the past or future, LUIS provides both values. An example is an utterance that includes the month and date without the year.

For example, given the following utterance:

May 2nd

  • If today's date is May 3rd 2017, LUIS provides both "2017-05-02" and "2018-05-02" as values.
  • When today's date is May 1st 2017, LUIS provides both "2016-05-02" and "2017-05-02" as values.

The following example shows the resolution of the entity "may 2nd". This resolution assumes that today's date is a date between May 2nd 2017 and May 1st 2018. Fields with X in the timex field are parts of the date that aren't explicitly specified in the utterance.

Date resolution example

The following utterance and its partial JSON response is shown below.

May 2nd

"entities": {
    "datetimeV2": [
        {
            "type": "date",
            "values": [
                {
                    "timex": "XXXX-05-02",
                    "resolution": [
                        {
                            "value": "2019-05-02"
                        },
                        {
                            "value": "2020-05-02"
                        }
                    ]
                }
            ]
        }
    ]
}

Date range resolution examples for numeric date

The datetimeV2 entity extracts date and time ranges. The start and end fields specify the beginning and end of the range. For the utterance May 2nd to May 5th, LUIS provides daterange values for both the current year and the next year. In the timex field, the XXXX values indicate the ambiguity of the year. P3D indicates the time period is three days long.

The following utterance and its partial JSON response is shown below.

May 2nd to May 5th


"entities": {
    "datetimeV2": [
        {
            "type": "daterange",
            "values": [
                {
                    "timex": "(XXXX-05-02,XXXX-05-05,P3D)",
                    "resolution": [
                        {
                            "start": "2019-05-02",
                            "end": "2019-05-05"
                        },
                        {
                            "start": "2020-05-02",
                            "end": "2020-05-05"
                        }
                    ]
                }
            ]
        }
    ]
}

Date range resolution examples for day of week

The following example shows how LUIS uses datetimeV2 to resolve the utterance Tuesday to Thursday. In this example, the current date is June 19th. LUIS includes daterange values for both of the date ranges that precede and follow the current date.

The following utterance and its partial JSON response is shown below.

Tuesday to Thursday

"entities": {
    "datetimeV2": [
        {
            "type": "daterange",
            "values": [
                {
                    "timex": "(XXXX-WXX-2,XXXX-WXX-4,P2D)",
                    "resolution": [
                        {
                            "start": "2019-10-08",
                            "end": "2019-10-10"
                        },
                        {
                            "start": "2019-10-15",
                            "end": "2019-10-17"
                        }
                    ]
                }
            ]
        }
    ]
}

Ambiguous time

The values array has two time elements if the time, or time range is ambiguous. When there's an ambiguous time, values have both the A.M. and P.M. times.

Time range resolution example

DatetimeV2 JSON response has changed in the API V3. The following example shows how LUIS uses datetimeV2 to resolve the utterance that has a time range.

Changes from API V2:

  • datetimeV2.timex.type property is no longer returned because it is returned at the parent level, datetimev2.type.
  • The datetimeV2.value property has been renamed to datetimeV2.timex.

The following utterance and its partial JSON response is shown below.

from 6pm to 7pm

The following JSON is with the verbose parameter set to false:


"entities": {
    "datetimeV2": [
        {
            "type": "timerange",
            "values": [
                {
                    "timex": "(T18,T19,PT1H)",
                    "resolution": [
                        {
                            "start": "18:00:00",
                            "end": "19:00:00"
                        }
                    ]
                }
            ]
        }
    ]
}

Time resolution example

The following utterance and its partial JSON response is shown below.

8am

"entities": {
    "datetimeV2": [
        {
            "type": "time",
            "values": [
                {
                    "timex": "T08",
                    "resolution": [
                        {
                            "value": "08:00:00"
                        }
                    ]
                }
            ]
        }
    ]
}

Deprecated prebuilt datetime

The datetime prebuilt entity is deprecated and replaced by datetimeV2.

To replace datetime with datetimeV2 in your LUIS app, complete the following steps:

  1. Open the Entities pane of the LUIS web interface.
  2. Delete the datetime prebuilt entity.
  3. Select Add prebuilt entity
  4. Select datetimeV2 and click Save.

Next steps

Learn about the dimension, email entities, and number.