System entities

Recognized formats

• 20 cents
• Five dollars
• $10

Attributes

• .literal: Exact phrase in input that is interpreted to be a currency mention.
• .numeric_value: Canonical numeric value as an integer or a double, in base units.
• .location: Lists the index element values of the first and last letters in the text string for the phrase that is interpreted to be a currency mention.
• .unit: Base unit of currency that is specified as a 3-letter ISO currency code. For example, USD or EUR.

The following table illustrates the information that each attribute captures from the user input.

For the input veinte euro (twenty euro in Spanish) or €1.234,56, @sys-currency returns these values:

Equivalent results are returned for other supported languages and national currencies.

@sys-currency usage tips

If you use the @sys-currency entity as a node condition and the user specifies $0 as the value, the value is recognized as a currency properly, but the condition is evaluated to the number zero, not the currency zero. As a result, the null in the condition is evaluated to false and the node is not processed. To check for currency values in a way that handles zeros properly, use the expression @sys-currency OR @sys-currency == 0 in the node condition instead.

For more information about currencies that are recognized per language, see Currency support.

Recognized formats

• Friday
• today
• May 8

Attributes

• .alternatives: Saves alternative date values when the input is open to interpretation. Typically the future date is returned as the @sys-date value. If there is ambiguity, the past date is saved as an alternative date. For example, for the input in January, a future date is returned. However, if it's February (January passed for this year), then the past January is returned also as an alternative date. An alternative date is also provided for weekdays when the weekday is specified without a modifier. For example, for the input Are you open Wednesday?, the future date is stored, but an alternative date with the date of the previous Wednesday is created also. Alternative dates are created for phrases that contain modifiers such as next, this, or last, which can have different meanings in different locales. The watsonx Assistant service treats last and next dates as references to the most immediate last or next day that is referenced, which might be in either the same or a previous week. For some modifiers, an alternative date is created or not depending on the current day of the week. For example, maybe the input contains this Wednesday. If it's Monday, the future date is stored and no alternative date is created. However, if it's Wednesday, then the date is assumed to be the Wednesday of the coming week, but today's date is stored as an alternative date. Each alternative date is saved as an object that contains a value and confidence for each alternative date. The alternative date objects are stored in a JSON Array. To get an alternative value, use the syntax: @sys-date.alternative.
• .calendar_type: Specifies the calendar type for the time zone in use. GREGORIAN is the only supported type.
• .datetime_link: See Date and time mentions.
• .day: Helper method that returns the day in the date.
• .day_of_week: Returns the day of the week in the date as a lowercase string.
• .festival: Recognizes locale-specific holiday names and can return the date of the upcoming holiday, such as Thanksgiving, Christmas, and Halloween. Use all lowercase letters if you need to specify a holiday name, in a condition for example (@sys-date.festival == 'thanksgiving'). For more information about recognized holidays, see Festivals.
• .granularity: Recognizes time frame mentions. Options are day, weekend, week, fortnight, month, quarter, and year.
• .interpretation: The object that is returned by your assistant, which contains new fields that increase the precision of the system entity classifier. You can omit interpretation from the expression that you use to refer to its fields. For example, you can access the value of the festival field in the interpretation object by using the shorthand syntax <? @sys-date.festival ?>.
• .literal: Exact phrase in input that is interpreted to be the date.
• .location: Index element values of the first and last letters in the text string for the phrase that is interpreted to be a date.
• .month: Helper method that returns the month in the date.
• .range_link: If present, indicates that the user's input contains a date range. The start and end index values of the string that includes the date range are saved as part of the link name. Additional information is provided, including the role that each @sys-date plays in the range relationship. For example, the start date has a role type of date_from and the end date has a role type of date_to. To check a role value, you can use the syntax @sys-date.role?.type == 'date_from'. If the user input implies a range, but only one date is specified, then the range_link property is not returned, but one role type is returned. For example, if the user asks Have you been open since yesterday. Yesterday's date is recognized as the @sys-date mention, and a role of type date_from is returned for it. A range_modifier that identifies the word in the input that triggers the identification of a range is also returned. In this example, the modifier is since.
• .relative_{timeframe}: Recognizes and captures mentions of relative date values in the user's input. Returns a number that shows the number of units between now and the specified date. The {time frame} units can be year, month, week, weekend, or day.
• .specific_{timeframe}: Recognizes and captures mentions of specific date units in the user's input. The {time frame} units can be year, quarter, month, day, or day_of_week.
• .year: Helper method that returns the year in the date.

The following table illustrates the information that each attribute captures from the user input.

Recognized formats

• 2pm
• at 4
• 15:30

Attributes

• .alternatives: Captures times other than the one saved as the @sys-time value that the user might mean when the time is not clearly indicated. The alternative values are saved as an object that contains a value and confidence for each alternative time and is stored in a JSON Array. To get an alternative value, use the syntax: @sys-time.alternative.
• .calendar_type: Specifies the calendar type for the time zone in use. GREGORIAN is the only supported type.
• .granularity: Recognizes mentions of time frames. Options are hour, minute, second, and instant.
• .hour: Helper method that returns the hour that is specified in the time as a numeric value.
• .interpretation: The object that is returned by your assistant, which contains new fields that increase the precision of the system entity classifier. You can omit interpretation from the expression that you use to refer to its fields. For example, you can access the value of the granularity field in the interpretation object by using the shorthand syntax <? @sys-time.granularity ?>.
• .literal: Exact phrase in the input that is interpreted to be the time.
• .location: Lists the index element values of the first and last letters in the text string for the phrase that is interpreted to be a time mention.
• .minute: Helper method that returns the minute value that is specified in the time.
• .part_of_day: Recognizes terms that represent the time of day, such as morning, afternoon, evening, night, or now. Also sets a time range for each part of the day. The response contains two @sys-time values, one for the start and one for the end of the time range. The entities array contains a range_link object with time-from and time-to role types. The time ranges for different parts of the day can differ by locale. For US English, morning is 6:00:00 to 12:00:00. Afternoon is 12:00:00 to 18:00:00. Evening is 18:00:00 to 22:00:00. Night is 22:00:00 to 23:59:59. Night ends just before midnight because otherwise it would overlap with a new day, which is measured by @sys-date.
• .range_link: If present, indicates that the user's input contains a time range. The start and end index values of the string that includes the time range are saved as part of the link name. Additional information is provided, including the role that each @sys-time plays in the range relationship. For example, the start time has a role type of time_from and the end time has a role type of time_to. To check a role value, you can use the syntax @sys-time.role?.type == 'time_from'. If the user input implies a range, but only one time is specified, then the range_link property is not returned, but one role type is returned. A range_modifier that identifies the word in the input that triggers the identification of a range is also returned.
• .relative_{timeframe}: Recognizes relative mentions of time and returns a number that shows the number of units between now and the specified time. The {timeframe} units can be hour, minute, or second.
• .second: Helper method that returns the second value that is specified in the time.
• .specific_{timeframe}: Recognizes and captures mentions of specific time units in the user input. The {timeframe} units can be hour, minute, or second.

The following table illustrates the information that each attribute captures from the user input.

Recognized formats

• now
• two hours from now
• on Monday at 4pm

Attributes

• .datetime_link: If present, this indicates that the user's input mentions a date and time together, which implies that the date and time are related to one another. The start and end index values of the string that includes the date and time are saved as part of the link name.

The following table illustrates the information that each attribute captures from the user input.

Time zones

Mentions of a date or time that are relative to the current time are resolved for a chosen time zone. By default, the time zone is Greenwich mean time. Therefore, REST API clients that are located in different time zones get the current Coordinated Universal Time when now is mentioned in input.

Optionally, the REST API client can add the local time zone as the context variable $timezone. This context variable must be sent with every client request. For example, the $timezone value can be America/Los_Angeles, EST, or UTC. For a full list of supported time zones, see Supported time zones.

When the $timezone variable is provided, the values of relative @sys-date and @sys-time mentions are computed based on the client time zone instead of Coordinated Universal Time.

For information about processing date and time values, see the Date and time method reference.

Recognized formats

• 21
• twenty one
• 3.13

Attributes

• .literal: Exact phrase in input that is interpreted to be the number.
• .location: Index element values of the first and last letters in the text string that is interpreted to be a number.
• .numeric_value: Canonical numeric value as an integer or a double.
• .range_link: If present, indicates that the user's input contains a number range. The location value of the text that specifies the range is appended to the link name. Additional information is provided, including the role that each @sys-number plays in the range relationship. For example, the start number has a role type of number_from and the end number has a role type of number_to. To check a role value, you can use the syntax @sys-number.role?.type == 'number_from'.

The following table illustrates the information that each attribute captures from the user input.

@sys-number usage tips

• If you use the @sys-number entity as a node condition and the user specifies zero as the value, the 0 value is recognized properly as a number. However, the 0 is interpreted as a null value for the condition, which results in the node not being processed. To check for numbers in a way that handles zeros properly, use the expression @sys-number == 0 in the node condition also. The full expression to use is @sys-number OR @sys-number == 0.

• If you use @sys-number to compare number values in a condition, be sure to separately include a check for the presence of a number itself. If no number is found, @sys-number evaluates to null. Your comparison might evaluate to true even when no number is present.

  For example, do not use @sys-number<4 alone because if no number is found, @sys-number evaluates to null. Because null is less than 4, the condition evaluates to true even though no number is present.

  Use (@sys-number OR @sys-number == 0) AND @sys-number < 4 instead. If no number is present, the first condition evaluates to false. As a result, the whole condition evaluates to false.

For more information about processing number values, see the Numbers method reference.

Recognized formats

• 15%
• 10 percent

Attributes

• .literal: Exact phrase in input that is interpreted to be a percentage.
• .location: Index element values of the first and last letters in the text string that is interpreted to be a percentage mention.
• .numeric_value: Canonical numeric value as an integer or a double
• .range_link: If present, indicates that the user's input contains a range, such as from 2 to 3 percent. The location value of the text that specifies the range is appended to the link name. Additional information is provided, including the role that each @sys-percentage plays in the range relationship. For example, the start number has a role type of number_from and the end number has a role type of number_to. To check a role value, you can use the syntax @sys-percentage.role?.type == 'number_from'.

The following table illustrates the information that each attribute captures from the user input.

@sys-percentage usage tips

• If you use the @sys-percentage entity as a node condition and the user specifies 0% as the value, the value is recognized as a percentage properly, but the condition is evaluated to the number zero not the percentage 0%. As a result, the null in the condition is evaluated to false and the node is not processed. To check for percentages in a way that handles zero percentages properly, use the expression @sys-percentage OR @sys-percentage == 0 in the node condition instead.

• If you input a value like 1-2%, the values 1% and 2% are returned as system entities.