This page consists of the following sections:

Specifying Dates

In Schedules, a date can be specified as:

a single date with optional wildcards.
a range of dates with optional wildcards.
a combination of week and day, with optional wildcards.
a reference to another item, such as a calendar object.

Each of the date types can be specified as one of the following objects (described below):

Single Date Object
Date Range Object
Week-and-Day Date Object
Date Reference Object

Single Date Object

The following table lists the single date object properties:

Field Name	Type	Description
ot	String	(Required) The ot (object type) property must report the constant string “date:single”.
year	Integer	(Optional) year contains the four-digit calendar year, such as 2019. year can be omitted or set to -1 to match any year. Possible values are: -1 or <*positive integer*>.
month	Integer	(Optional) month contains the number of the month, where January is 1 and December is 12. Number 13 represents all odd months, and 14 represents all even months. month can be set to -1 to match any month. Possible values are: -1, or 1 to 14.
day	Integer	(Optional) day contains the number of the day within the month, starting with 1 for the first day of the month. Number 32 selects the last day of the month, 33 selects all odd days, and 34 selects all even days. day can be set to -1 to match any day. Possible values are: -1, or 1 to 34.
weekday	Integer	(Optional) weekday contains the number of the day within the week, starting with 1 for Monday. Number 8 selects every day, 9 selects every Monday to Friday, 10 selects every Saturday and Sunday, and 11 selects every Friday and Saturday. weekday can be set to -1 to match any weekday. Matching any weekday is the same as explicitly specifying weekday: 11. The explicit form is required where an omission has a different effect. See Weekly Schedule for more information. Possible values are: -1, or 1 to 11.

Example: Christmas Day

{
	ot: "date:single",
	month: 12,
	day: 25
}

Date Range Object

The following table lists the Date Range Object properties:

Field Name	Type	Description
ot	String	(Required) The ot (object type) property must report the constant string date:single.
start	Any valid value	(Optional) Provides a single data object as defined in 1475232. No start date or a null date is the same as setting the start date to a date in the distant past. Both start and end are inclusive. The range begins at 00:00 on the start date and ends at 24:00 on the end date. Possible values are: null or <single date object> Default: null.
end	String	(Optional) Provides a single data object as defined in Single Date Object. No end date or a null date is the same as setting the end date to a date in the distant future. The end date must be reachable after the start. Both start and end are inclusive. The range begins at 00:00 on the start date and ends at 24:00 on the end date. Possible values are: null or <single date object>

Example: Christmas Day and Boxing Day

{
	ot: "date:range",
	start: { 				// start with Christmas Day
		ot: "date:single",
		month: 12,
		day: 25
	},
	end: { 					// end with the first 26th day in any month,
		ot: "date:single",
		day: 26 			// any year, *after* the start date.
	}
}

Week-and-Day Date Object

The following table lists the week-and-day date object properties:

Field Name	Type	Description
ot	String	(Required) The ot (object type) property must report the constant string “date:week-and-day”.
month	Integer	(Optional) month contains the number of the month, where January is 1 and December is 12. Number 13 represents all odd months, and 14 represents all even months. month can be set to -1 to match any month. Possible values are: -1, or 1 to 14.
day	Integer	(Optional) day selects groups of days in the month. day can be set to -1 to match any day. Possible values are -1, or 1 to 9, where: -1: matches any day of the month. 1: selects days numbered 1 to 7 2: selects days numbered 8 to 14 3: selects days numbered 15 to 21 4: selects days numbered 22 to 28 5: selects days numbered 29 to 31 6: selects the last seven days 7: selects any of the 7 days prior to the last 7 days of the month 8: selects any of the 7 days prior to the last 14 days of the month 9: selects any of the 7 days prior to the last 21 days of the month
weekday	Integer	(Optional) weekday contains the number of the day within the week: 1 for Monday 2 for Tuesday 3 for Wednesday 4 for Thursday 5 for Friday 6 for Saturday 7 for Sunday Additional values for weekday: 8 selects every day 9 selects every Monday to Friday, 10 selects every Saturday and Sunday 11 selects every Friday and Saturday. -1 to match any weekday. (Matching any weekday is the same as explicitly specifying weekday: 11) The explicit form is required where an omission has a different effect. See Weekly Schedule for more information. Possible values are: -1, or 1 to 11.

Example: Every Second Saturday in every Month

{
	ot: "date:week-and-day",
	weekday: 6,
	days: 2
}

Example: The Last Thursday in November

{
	ot: "date:week-and-day",
	month: 11,
	weekday: 4,
	days: 6
}

Date Reference Object

The date reference object references an item outside the schedule object, but within the same IAP segment. The reference yields a Boolean result, that when true, the date is considered active. Date reference objects are typically used to reference calendar objects, but can also reference other properties within the feedback channel.

The following table lists the Date Reference Object properties:

Field Name	Type	Description
ot	String	(Required) The ot (object type) property must report the constant string “date:ref”.
fb	String	(Required) References an addressable object relative to the feedback channel within the same segment. The syntax requires using the tilde to represent the feedback channel address. For example `~/cal/example/sts` addresses the status object of the “example” calendar.
path	String	(Optional) Contains a slash-separated path to the property within the object. Default: "state"
active	Number, String, or Boolean	(Optional) The referenced item is considered active when the property at the given path within the addressed fb reports the active value. Default: "active"

Example: Every Second Saturday in Every Month

{
	ot: "date:ref",
	fb: "~/cal/holidays/sts"
}

Weekly Schedule

The weekly schedule is an object with zero or more key-value pairs, one for each day of the week. The keys use the same encoding as the weekday in the Date objects, such as “1” to “7” for “Monday” to “Sunday”, “8” for every day, and so on.

The weekday encoding is described in Single Date Object properties table. But because IAP/MQ objects use JSON encoding, and numbers are not valid keys for JSON objects, the weekly schedule uses the same weekday identifiers in string format.

Each key maps to a set of time-value pairs. Time follows the format described in Time and maps to a value. The value can be null or any valid value that is acceptable by all target datapoints.

Time

Time is presented as a string in HH:MM:SS format using the 24-hour clock: “14:30:00”. Hours and minutes are required, but seconds are optional: both “14:30:00” and “14:30” specify thirty minutes past the second hour after midday (2:30 PM).

An optional one-letter prefix or postfix is used for time relative to astronomical events:

“R00:30” is 30 minutes after sunrise.
“00:30R” is 30 minutes before sunrise.
“S00:30” is 30 minutes after sunset.
“00:30S” is 30 minutes before sunset.

Time must be a specific time, wildcards are not allowed.

Astronomical events (sunrise, sunset) are computed for the location of the segment controller. Elevation angles for sunset and sunrise can be configured within that segment and default to -6° for civil twilight.

Example: Commented Weekly Schedule

{
	"6": { 					// on Saturday:
		"00:00S": 0.5, 		// set the lights to 50% at sunset,
		"S00:30": 0.75, 	// then raise to 75% half an hour after sunset,
		"S01:00": 1.0 		// then raise to 100% an hour after sunset,
	}, 						// (relinquish at midnight).
	"7": { 					// on Sunday:
		"00:00": 1.0, 		// continue with 100% from midnight,
		"01:00", 0.75, 		// reduce to 75% at 1:00 am,
		"02:00", 0.5, 		// reduce to 50% at 2:00 am,
		"03:00", 1, 		// return to 100% at 3:00 am,
		"R00:45": null 		// relinquish 45 minutes after sunrise
	}
}

Exception Schedule

The exception schedule is an unordered list of Special Event Objects.

Each special event has a date, which describes when the special event is active, and a set of time-value pairs, as described in Weekly Schedule. Each Special Event also supports a priority (prio) that prioritizes special events with overlapping schedules. The special event priority has no effect on the priority at which the schedule output value is assigned to the targets.

The schedule output is non-deterministic when the schedule contains conflicting events at the same priority or when multiple schedules conflict with each other.

Special Event Object

The following table lists the Special Event Object properties:

Field Name	Type	Description
date	String	(Required) Contains one of the Date objects: single date, date range, week-and-day date, or a date reference.
prio	Integer	(Optional) prio is required when the list of special events contain otherwise conflicting definitions. This priority has no effect on the priority at which the schedule output value is assigned to the targets Possible values are 1 to 16, where 1 is the highest priority. Default: 16.
events	String	(Optional) Contains a set of time-value pairs. events uses the same format as a single day entry within the weekly schedule. The events property can be empty or null. Both render this exception ineffective.

Example: Commented Shop Open/Closed Sign Schedule

{
	prio: 8,
	effective: {
		ot: "date:single",
		month: 12 							// for every December
	},
	weekly: {
		"10": { 							// every Monday to Friday
			"07:00": "open", 				// we are open from 7:00
			"23:00": "closed" 				// to 11 pm
		},
		"6": { 								// on Saturday we
			"07:00": "open" 				// open at 7:00 and close at midnight
		},
		"7": {
			"10:00": "open", 				// Sunday trading hour law
			"17:00": "closed" 				// 10:00 to 5 pm.
		}
	},
	exceptions: [ 							// except when one of these apply:
		{
			date: {
				ot: "date:ref",
				fb: "~/cal/holidays/sts"
			},
			events: {
				"00:00": "Happy Holidays"
			}
		}
	],
	default: "closed", 						// we are closed at other times
	dp: [
		"~/dev/lon/0/if/display/0/nviText"	// drive this target
	]
}

Dates in Schedules and Calendars