Skip to content

Latest commit

 

History

History
146 lines (105 loc) · 8.87 KB

Org.OData.Temporal.V1.md

File metadata and controls

146 lines (105 loc) · 8.87 KB

Temporal Vocabulary

Namespace: Org.OData.Temporal.V1

Terms for describing time-dependent data

Terms

Term Type Description
ApplicationTimeSupport ApplicationTimeSupportType This collection supports temporal requests

Actions

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 collection
The 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.
[TimesliceWithPeriod] Modified time slices

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 collection
The 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.
[TimesliceWithPeriod] Modified time slices

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 collection
The 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.
[TimesliceWithPeriod] Deleted (sub-periods of) time slices

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
If an upper boundary property does not specify a default value, a default value of max is assumed.
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. If PeriodStart is present and PeriodEnd is absent, a default value of max is assumed for PeriodEnd.

Property Type Description
PeriodStart PrimitiveType? Lower boundary of the time slice
PeriodEnd PrimitiveType? Upper boundary of the time slice
Timeslice EntityType A time slice with the same entity type as the binding parameter of the action
When it appears in the return type of an action in this vocabulary, the time slice has the same entity set as the binding parameter value.