Dates

A Date Variable holds a calendar day, with no time of day and no time zone. You send it in one shape and get it back in two: a timestamp for code and formatted text for people.

Sending a date

Send every Date Variable as YYYY-MM-DD:

/api/advice/{adviceSetId}?DOB=1991-10-31

{ "DOB": "1991-10-31" }

The rule covers query strings, JSON bodies, Advice Batch state, and the state a Web Component receives through config. The Variable Dictionary states it too, in each Date entry's validOptionsInstructions.

Leave these out:

Don't send	Why
A time or offset, such as `1991-10-31T00:00:00+01:00`	An offset names an instant, and midnight on October 31 at `+01:00` is still October 30 in UTC. The advice follows that earlier day, so a computed age can change.
A raw `+` in a query string	Query strings read `+` as a space, and the request returns `400`.
Any other shape, such as `10/31/1991` or `Oct 31 1991`	It sits outside the contract. Convert it to `YYYY-MM-DD` first.

Send only days that exist, and check them before you send. A value the API cannot read as a date returns 400 with the message Non-date value input for Date type variable.

Reading a date

Field	Shape	Example
`params`	your input, unchanged	`1991-10-31`
`variables[].value`	ISO 8601 in UTC, with milliseconds	`1991-10-31T00:00:00.000Z`
`variables[].valueFormatted`	text in the Variable's `format`	`October 31, 1991`
`replayParams`, `replayParamsAll`	ISO 8601	`1991-10-31T00:00:00.000Z`
Backlink `value`	ISO 8601	`1991-10-31T00:00:00.000Z`
`data-variable-raw-value` on a `<taffrail-var>`	ISO 8601	`1991-10-31T00:00:00.000Z`
Dates the rules compute, such as `SS_Full_Retirement_Date`	ISO 8601	`2058-10-31T00:00:00.000Z`
Headlines and advice text	text	"If you were born October 31, 1991, …"

To work with a returned date:

Take the day from the first ten characters. value.slice(0, 10) gives 1991-10-31. Never hand the timestamp to new Date() and read it with local getters or a local formatter: anywhere west of UTC, that shows October 30.
To display it, use valueFormatted or the advice text. To format it yourself, parse the ten characters as a local date, as date-fns parseISO("1991-10-31") does, then format that.
To send it back, send the ten characters, not the timestamp.
To compare two dates, compare their ten-character strings.

Format strings

On a Date Variable, format and formatInput are date-fns patterns built from Unicode TR35 tokens.

format is the display pattern. The API applies it to build valueFormatted and every date in the advice text. The Variable Dictionary returns it as displayFormat.
formatInput is the pattern a person types, such as MM/dd/yyyy. Build an input mask or placeholder from it, then convert what the person typed to YYYY-MM-DD before you send it. It appears only when the Variable sets one.

Token	Means	October 31, 1991
`yyyy`	year	`1991`
`M`, `MM`	month number; `MM` pads to two digits	`10`
`MMM`, `MMMM`	month name	`Oct`, `October`
`d`, `dd`	day of the month	`31`
`mm`	minutes, not the month	`00`

These are not moment.js tokens. date-fns reads YYYY as a week-numbering year and DD as the day of the year, so read yyyy and dd as the year and the day.

See Formats for number formats and more date examples.