Namespace: Org.OData.Temporal.V1
Terms for describing time-dependent data
This is a public review draft that may incompatibly change any time.
| Term | Type | Description |
|---|---|---|
| ApplicationTimeSupport | ApplicationTimeSupportType | This collection supports temporal requests |
Updates existing time slices with values from delta time slices whose object keys match and whose periods overlap
The update behavior for a given object key is known from the SQL statement
UPDATE ... FOR PORTION OF BUSINESS_TIME ... WHERE ....
deltaTimeslices with non-matching object keys and non-overlapping sub-periods of deltaTimeslices are disregarded.
| Parameter | Type | Description |
|---|---|---|
| timeslices | [EntityType] | Binding parameter: Time slices to modify |
| deltaTimeslices | [TimesliceWithPeriod] | New time slices whose property values are used to update the timeslices collectionThe delta time slices need not contain all properties, but at least the boundary values of the period to change. An absent object key property matches any key property value. New time slices are processed in the order of the collection, which especially matters if some of the specified change periods overlap. |
| → | [EntityType] | Modified time slices Same entity type as binding parameter. |
Like Update, but additionally inserts those (sub-periods of) deltaTimeslices that Update disregards
| Parameter | Type | Description |
|---|---|---|
| timeslices | [EntityType] | Binding parameter: Time slices to modify |
| deltaTimeslices | [TimesliceWithPeriod] | New time slices to be merged into the timeslices collectionThe delta time slices must contain all properties that are needed for insertion. New time slices are processed in the order of the collection, which especially matters if some of the specified change periods overlap. |
| → | [EntityType] | Modified time slices Same entity type as binding parameter. |
Like Update, but updates the properties that are present in a given delta time slice only in those contiguous time slices, starting with the earliest, that have same the original value for all these properties
| Parameter | Type | Description |
|---|---|---|
| timeslices | [EntityType] | Binding parameter: Time slices to modify |
| deltaTimeslices | [TimesliceWithPeriod] | New time slices whose property values are used to update the timeslices collectionThe delta time slices need not contain all properties, but at least the lower boundary of the period to change. An absent object key property matches any key property value. New time slices are processed in the order of the collection, which especially matters if some of the specified change periods overlap. |
| → | [EntityType] | Modified time slices Same entity type as binding parameter. |
Deletes (sub-periods of) existing time slices whose object keys match and whose periods overlap deltaTimeslices
The deletion behavior for a given object key is known from the SQL statement
DELETE ... FOR PORTION OF BUSINESS_TIME ... WHERE ....
The sub-period of an existing time slice that lies outside a given instance of deltaTimeslices
is kept, effectively shortening the time slice.
| Parameter | Type | Description |
|---|---|---|
| timeslices | [EntityType] | Binding parameter: Time slices to modify |
| deltaTimeslices | [TimesliceWithPeriod] | Time slices to be deleted from the timeslices collectionThe delta time slices contain only the boundary values of the period to delete and (parts of) the object key. An absent object key property matches any key property value. |
| → | [EntityType] | Deleted (sub-periods of) time slices Same entity type as binding parameter. |
Like Delete, but deletes or shortens only those contiguous time slices, starting with the earliest, that have same the original value for all properties expect the period boundaries
| Parameter | Type | Description |
|---|---|---|
| timeslices | [EntityType] | Binding parameter: Time slices to modify |
| deltaTimeslices | [TimesliceWithPeriod] | Time slices to be deleted from the timeslices collectionThe delta time slices contain only the lower and optionally upper boundary values of the period to delete and (parts of) the object key. An absent object key property matches any key property value. |
| → | [EntityType] | Deleted time slices Same entity type as binding parameter. |
| Property | Type | Description |
|---|---|---|
| UnitOfTime | UnitOfTime | Unit of time and other properties of a time period |
| Timeline | Timeline | Describes how the history and future of the data are represented |
| SupportedActions | [QualifiedActionName] | List of supported temporal actions |
Unit of time and other properties of a time period
Derived Types:
Period start and end are of type Edm.DateTimeOffset
| Property | Type | Description |
|---|---|---|
| Precision | Byte | Precision of Edm.DateTimeOffset values for period start and end |
Period start and end are of type Edm.Date
The period is a contiguous set of days and does not consider the time of the day.
| Property | Type | Description |
|---|---|---|
| ClosedClosedPeriods | Boolean | If true, the period end is the last day in the period; if false, the period end is the first day after the period |
Describes how the history and future of the data are represented
Derived Types:
Each OData entity maps each point in application time to an instance of the entity type
To address an entity in a resource path or path to related resources, a point in application time must be specified as described in [OData-Temporal, section 4.2.1]. The addressed entity is then a snapshot of the data at the given point in time. When an action defined in this vocabulary is applied to a collection of this entity type, the entity key plays the role of object key.
Each OData entity represents data during a period of application time
The temporal collection MUST NOT contain two entities with the same object key as defined by their ObjectKey properties
and with overlapping application-time periods as defined by their PeriodStart and PeriodEnd properties.
The temporal collection always contains all entities (with consecutive time periods) for a given object key.
| Property | Type | Description |
|---|---|---|
| PeriodStart | PropertyPath | Property containing lower boundary of a period |
| PeriodEnd | PropertyPath | Property containing upper boundary of a period |
| ObjectKey | [PropertyPath] | The set of primitive properties that identify a temporal object A temporal object is a set of facts whose changes over application time are tracked by the service. The entities in the annotated collection belong to potentially multiple temporal objects, and each temporal object is uniquely identified by the values of the specified object key properties. Object key properties follow the same rules as entity key properties. If no object key is specified, only a single temporal object belongs to the annotated collection. |
Delta time slices with validity period
The properties PeriodStart and PeriodEnd MUST NOT be present
if the entity type of the Timeslice already contains period start and end, that is,
if the collection on which the action is invoked has visible timeline.
If present, they MUST have the same type, either Edm.Date or Edm.DateTimeOffset,
and they are interpreted according to the ApplicationTimeSupport/UnitOfTime of the collection.
In particular, ApplicationTimeSupport/UnitOfTime/ClosedClosedPeriods governs whether a PeriodEnd of type Edm.Date
is the last day in the period or the first day after the period.
| Property | Type | Description |
|---|---|---|
| Timeslice | EntityType | A time slice with the same entity type as the binding parameter of the action |
| PeriodStart | PrimitiveType? | Lower boundary of the time slice |
| PeriodEnd | PrimitiveType? | Upper boundary of the time slice |