Skip to main content
Some source systems don’t have first-class support for date-tracked values. They expose a single text field per property, but the business meaning is “this value applies from 2024-01-01” or “these two values apply to different time ranges”. The dated property pattern is a compact string format for packing that information into a single text field, which Twine then expands into a proper list of dated property entries. The pattern is consumed by a pattern converter step on a property mapping: the raw source text is read, the converter parses it, and the resulting entries flow into the entity like any other dated property.

​
Builder

Fill in the fields below to compose a valid pattern. The generated string is shown underneath, together with the dated property entries it will produce.

​
A value on its own

The simplest pattern is just a value:
This becomes a single dated property entry with valid_from: null - meaning the value has been in effect since the beginning of time. This is appropriate for properties where history is not meaningful.

​
A value with a start date

Separate the value from its effective date with a comma:
The value takes effect on the given date and stays in effect indefinitely. Whitespace around the comma is optional: 50000, 2024-01-01 parses identically.

​
A value within a closed interval

Add an end date to describe a value that was only valid for a bounded period:
A closed interval always produces two dated property entries: the value itself, and a terminator on the day after the end date. The terminator is an entry with value: null that signals the property is no longer active. This mirrors how closed intervals are represented throughout Twine.
Querying the property at end_date + 1 will return the terminator, not the value. This is almost always what you want - but it surprises people the first time they see it.
If you only need an end date but no start, use an empty start slot with two commas:
This produces the value with valid_from: null plus a terminator on 2025-01-01.

​
Multiple values in a single pattern

Separate multiple values with / to describe a full history in one string:
Each segment is parsed independently. The order in the source text does not matter - Twine sorts the resulting entries by valid_from in descending order (newest first) as part of its standard dated property handling. Whitespace around / is optional.

​
Grouping values with an ID

Some properties can hold several independent values at the same time - see properties with multiple simultaneous values. Attach an ID to each segment with # to keep those series apart:
An ID must not contain whitespace, /, ,, or #. A single optional space is allowed between the date and the #:
When an ID is attached to a closed interval, both the value entry and the terminator carry the same ID.

​
Value types

The parser recognises the following value forms and converts them to typed values. The first rule that matches is used. Raw text values cannot contain , or /, since those are structural delimiters. Use a quoted string if the value needs to contain either of them, or leading or trailing whitespace:
Quoted strings have no escape syntax. The first " after the opening quote ends the string.
Dates in value position use strict YYYY-MM-DD form with literal dash separators. Dates in start or end position accept a few additional forms - see Date formats below.

​
Decimal numbers and the comma separator

Comma is used both as a part delimiter and, in European conventions, as a decimal separator. The parser handles both, but the rule is subtle enough to be worth stating explicitly. A comma decimal is only recognised when the number is followed by another comma or the end of input. In every other position, the comma is treated as a delimiter. If you are unsure, use . as the decimal separator - it is unambiguous everywhere. The builder above always emits dots.

​
Date formats

In start and end position, dates accept three forms. All three validate the calendar: invalid combinations such as 2020-02-30 cause the whole pattern to fail. In value position, only the strict dashed form with a four-digit year is accepted, to keep date values unambiguous when they share a pattern with numeric values.

​
Whitespace

Whitespace around / and , is ignored. Inside a value or an ID, whitespace is significant and must be wrapped in quotes if the grammar would otherwise stop at it. The parser normalises these Unicode spaces to a regular ASCII space before parsing: U+00A0 (non-breaking space), U+2007 (figure space), U+2009 (thin space), U+202F (narrow no-break space), U+200B (zero-width space). This is useful when copy-pasting from sources that inject invisible spaces. Tabs and other Unicode whitespace are not normalised. The whole pattern is trimmed before parsing.

​
What is not supported

  • Tabs as whitespace, and Unicode whitespace beyond the normalised set above.
  • Escape sequences inside quoted strings.
  • Raw text values containing , or / - use a quoted string.
  • Negative percentages and negative hours.
  • Times of day (HH:MM:SS). HH:MM is accepted, but only as a duration.
  • Datetimes.
  • An end date without a start date in any form other than value,,end_date.

​
Errors

A pattern either parses into a list of dated property entries or returns an error. Errors are always returned as values - the converter never raises. Two kinds of errors can occur:
  • Unparsed input - the parser consumed part of the input and then got stuck at a character it did not expect. The error points to the column where parsing halted.
  • Invalid content - the grammar was satisfied but the content does not make sense, for example an invalid calendar date or a malformed number.
An empty or missing pattern is not an error: it produces an empty list of entries.