Event

Represents an event concept. It allows either a date or a datetime, but not a mix of both. One of the start properties is required, but the end properties are optional.

Scope

This data type is intended to represent the raw known factual information a specific temporal event. The interpretation and context of an event will be dependent on which resource type is using it.

Structure

An Event shall always contain some start_* attribute.
- A valid Event shall at minimum contain either a start_date or a start_datetime.
An Event shall be defined using either date or date-time specificity.
- Mixed usage of date and date-time is prohibited
- If start_date is defined, an optional end_date may be specified.
- If start_datetime is defined, an optional end_datetime may be specified.

Name	Cardinality	Type	Description & Constraints
start_date	0..1	`string`	The start date of the event in `YYYY-MM-DD` format.
start_datetime	0..1	`string`	The start datetime of the event in ISO 8601 format (e.g., `2024-12-01T10:00:00Z`).
end_date	0..1	`string`	The end date of the event in `YYYY-MM-DD` format. This is optional if `start_date` is used.
end_datetime	0..1	`string`	The end datetime of the event in ISO 8601 format. This is optional if `start_datetime` is used.

Specification

Schema
Source
Examples

Loading ....

{
  "$id": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/data/event.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Event",
  "description": "Represents an event concept. It allows either a date or a datetime, but not a mix of both. One of the start properties is required, but the end properties are optional.",
  "type": "object",
  "properties": {
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "The start date of the event in YYYY-MM-DD format."
    },
    "start_datetime": {
      "type": "string",
      "format": "date-time",
      "description": "The start datetime of the event in ISO 8601 format (e.g., 2024-12-01T10:00:00Z)."
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "The end date of the event in YYYY-MM-DD format. This is optional if `start_date` is used."
    },
    "end_datetime": {
      "type": "string",
      "format": "date-time",
      "description": "The end datetime of the event in ISO 8601 format. This is optional if `start_datetime` is used."
    }
  },
  "oneOf": [
    {
      "title": "Date",
      "description": "This schema is used when the event starts with a date (`start_date`), and optionally, an end date (`end_date`) can be specified. Mixing a start date with a datetime is not allowed.",
      "properties": {
        "start_date": {
          "type": "string",
          "format": "date"
        },
        "end_date": {
          "type": "string",
          "format": "date"
        }
      },
      "required": [
        "start_date"
      ],
      "not": {
        "required": [
          "start_datetime",
          "end_datetime"
        ]
      }
    },
    {
      "title": "DateTime",
      "description": "This schema is used when the event starts with a datetime (`start_datetime`), and optionally, an end datetime (`end_datetime`) can be specified. Mixing a start datetime with a date is not allowed.",
      "properties": {
        "start_datetime": {
          "type": "string",
          "format": "date-time"
        },
        "end_datetime": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "start_datetime"
      ],
      "not": {
        "required": [
          "start_date",
          "end_date"
        ]
      }
    }
  ]
}

Date Start

{
  "start_date": "2024-12-01"
}

Date Range

{
  "start_date": "2024-12-01",
  "end_date": "2024-12-31"
}

DateTime Start

{
  "start_datetime": "2024-12-01T10:00:00Z"
}

DateTime Range

{
  "start_datetime": "2024-12-01T10:00:00Z",
  "end_datetime": "2024-12-31T10:00:00Z"
}

Implementation Notes

Date vs DateTime Specificity

The Event data type supports either Date or DateTime specificity. When choosing which specificity to transmit an Event, consider the intent of the transmission, and whether the time component would aid in providing meaningful context to the conveyed information. We offer the following guidance:

Reporting normally uses day resolution. If you know your message is intended to be used for reporting purposes, use the date format over date-time.
System logging and auditing uses should lean towards using the date-time format if the time component is available.
When the usage intent is unknown and the time component is available, use the date-time format as it will contain a higher degree of information fidelity.

Transformation Specificity

Conversion and inference between the date and date-time formats can be tricky as it is not possible to do a lossless bidirectional transformation between the two formats (i.e. if you drop the time from date-time, you will have a hard time getting the time value back).

When converting from date-time to date, the transformation shall account for the timezone offset.
- As all dates are recorded in UTC time, it is not sufficient to simply truncate the time portion.
- Use the local time of the system where it is operating at as a frame of reference.
- For most situations, anticipate using either Pacific Daylight Time (PDT) or Pacific Standard Time (PST).
We advise against converting from date to date-time as assumptions for the time component would be necessary.

Ongoing Events

The Event data type only supports representing a specific moment with just a start, or a finite duration with a start and an end. Event does not support conveying an ongoing event (e.g. there exists a start date, but no end date is provided because it is still current or ongoing). This is because the message specification needs to support asynchronous communication workloads; it may be possible for an ongoing event to no longer hold true by the time the message has been parsed by the recipient system.

While inferences may be made about values that only have the start defined, they should not be interpreted when handling their values, and should instead be used "at face value" to describe only the specific moment when a start occurs.

Scope​

Structure​

Specification​

Implementation Notes​

Date vs DateTime Specificity​

Transformation Specificity​

Ongoing Events​

References​