<?xml version="1.0" encoding="utf-8"?>
<!--

     OData Extension for Temporal Data Version 4.0
     Committee Specification Draft 01
     29 July 2021
     Copyright (c) OASIS Open 2021. All Rights Reserved.
     Source: https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/csd01/vocabularies/
     Latest version of narrative specification: https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/odata-temporal-ext-v4.0.html
     TC IPR Statement: https://www.oasis-open.org/committees/odata/ipr.php

-->
<!--

  Technical Committee:
  OASIS Open Data Protocol (OData) TC
  https://www.oasis-open.org/committees/odata

  Chairs:
  - Ralf Handl (ralf.handl@sap.com), SAP SE
  - Michael Pizzo (mikep@microsoft.com), Microsoft

  Editors:
  - Ralf Handl (ralf.handl@sap.com), SAP SE
  - Michael Pizzo (mikep@microsoft.com), Microsoft
  - Heiko Theissen (heiko.theissen@sap.com), SAP SE

  Additional artifacts:
  This vocabulary is one component of a Work Product that also includes the following vocabulary components:
  - OData Core Vocabulary. Latest version: https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.xml.
  - OData Measures Vocabulary. Latest version: https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Measures.V1.xml.
  - OData Capabilities Vocabulary. Latest version: https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Capabilities.V1.xml.
  - OData Validation Vocabulary. Latest version: https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Validation.V1.xml.
  - OData Aggregation Vocabulary. Latest version: https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.xml.
  - OData Authorization Vocabulary. Latest version: https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Authorization.V1.xml.

  Related work:
  This vocabulary replaces or supersedes:
  - None.
  This vocabulary is related to:
  - OData Version 4.01 Part 1: Protocol. Latest version: http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html.
  - OData Version 4.01 Part 2: URL Conventions. Latest version: http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html.
  - OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01. Latest version: http://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html.
  - OData Common Schema Definition Language (CSDL) XML Representation Version 4.01. Latest version: http://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html.
  - OData JSON Format Version 4.01. Latest version: http://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html.
  - OData Extension for Data Aggregation Version 4.0. Latest version: http://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/odata-data-aggregation-ext-v4.0.html.

  Abstract:
  This vocabulary defines terms to describe which data in a given entity model is time-dependent, and how.

-->
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
  <edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.xml">
    <edmx:Include Namespace="Org.OData.Core.V1" Alias="Core" />
  </edmx:Reference>
  <edmx:DataServices>
    <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Org.OData.Temporal.V1" Alias="Temporal">
      <Annotation Term="Core.Description">
        <String>Terms for describing time-dependent data</String>
      </Annotation>
      <Annotation Term="Core.LongDescription">
        <String>*This is a public review draft that may incompatibly change any time.*</String>
      </Annotation>
      <Annotation Term="Core.Links">
        <Collection>
          <Record>
            <PropertyValue Property="rel" String="latest-version" />
            <PropertyValue Property="href" String="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Temporal.V1.xml" />
          </Record>
          <Record>
            <PropertyValue Property="rel" String="alternate" />
            <PropertyValue Property="href" String="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Temporal.V1.json" />
          </Record>
          <Record>
            <PropertyValue Property="rel" String="describedby" />
            <PropertyValue Property="href" String="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Temporal.V1.md" />
          </Record>
        </Collection>
      </Annotation>


      <Term Name="ApplicationTimeSupport" Type="Temporal.ApplicationTimeSupportType" Nullable="false" AppliesTo="Collection">
        <Annotation Term="Core.AppliesViaContainer" />
        <Annotation Term="Core.Description">
          <String>This collection supports temporal requests</String>
        </Annotation>
      </Term>

      <ComplexType Name="ApplicationTimeSupportType">
        <Property Name="UnitOfTime" Type="Temporal.UnitOfTime" Nullable="false">
          <Annotation Term="Core.Description" String="Unit of time and other properties of a time period" />
        </Property>
        <Property Name="Timeline" Type="Temporal.Timeline" Nullable="false">
          <Annotation Term="Core.Description" String="Describes how the history and future of the data are represented" />
        </Property>
        <Property Name="SupportedActions" Type="Collection(Core.QualifiedActionName)" Nullable="false">
          <Annotation Term="Core.Description" String="List of supported temporal actions" />
        </Property>
      </ComplexType>

      <ComplexType Name="UnitOfTime" Abstract="true">
        <Annotation Term="Core.Description" String="Unit of time and other properties of a time period" />
      </ComplexType>

      <ComplexType Name="UnitOfTimeDateTimeOffset" BaseType="Temporal.UnitOfTime">
        <Annotation Term="Core.Description" String="Period start and end are of type Edm.DateTimeOffset" />
        <Property Name="Precision" Type="Edm.Byte" Nullable="false">
          <Annotation Term="Core.Description" String="Precision of Edm.DateTimeOffset values for period start and end" />
        </Property>
      </ComplexType>

      <ComplexType Name="UnitOfTimeDate" BaseType="Temporal.UnitOfTime">
        <Annotation Term="Core.Description" String="Period start and end are of type Edm.Date" />
        <Annotation Term="Core.LongDescription" String="The period is a contiguous set of days and does not consider the time of the day." />
        <Property Name="ClosedClosedPeriods" Type="Edm.Boolean" Nullable="false" DefaultValue="false">
          <Annotation Term="Core.Description" String="If `true`, the period end is the last day in the period; if `false`, the period end is the first day after the period" />
        </Property>
      </ComplexType>


      <ComplexType Name="Timeline" Abstract="true">
        <Annotation Term="Core.Description" String="Describes how the history and future of the data are represented" />
      </ComplexType>

      <ComplexType Name="TimelineSnapshot" BaseType="Temporal.Timeline">
        <Annotation Term="Core.Description" String="Each OData entity maps each point in application time to an instance of the entity type" />
        <Annotation Term="Core.LongDescription">
          <String>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.</String>
        </Annotation>
      </ComplexType>

      <ComplexType Name="TimelineVisible" BaseType="Temporal.Timeline">
        <Annotation Term="Core.Description" String="Each OData entity represents data during a period of application time" />
        <Annotation Term="Core.LongDescription">
          <String>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.</String>
        </Annotation>
        <Property Name="PeriodStart" Type="Edm.PropertyPath" Nullable="false">
          <Annotation Term="Core.Description" String="Property containing lower boundary of a period" />
        </Property>
        <Property Name="PeriodEnd" Type="Edm.PropertyPath" Nullable="false">
          <Annotation Term="Core.Description" String="Property containing upper boundary of a period" />
        </Property>
        <Property Name="ObjectKey" Type="Collection(Edm.PropertyPath)" Nullable="false">
          <Annotation Term="Core.Description" String="The set of primitive properties that identify a temporal object" />
          <Annotation Term="Core.LongDescription" String="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." />
        </Property>
      </ComplexType>

      <ComplexType Name="TimesliceWithPeriod">
        <Annotation Term="Core.Description" String="Delta time slices with validity period" />
        <Annotation Term="Core.LongDescription">
          <String>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`,
          depending on the `ApplicationTimeSupport/UnitOfTime` of the collection.</String>
        </Annotation>
        <Property Name="Timeslice" Type="Edm.EntityType" Nullable="false">
          <Annotation Term="Core.Description" String="A time slice with the same entity type as the binding parameter of the action" />
        </Property>
        <Property Name="PeriodStart" Type="Edm.PrimitiveType" Nullable="true">
          <Annotation Term="Core.Description" String="Lower boundary of the time slice" />
        </Property>
        <Property Name="PeriodEnd" Type="Edm.PrimitiveType" Nullable="true">
          <Annotation Term="Core.Description" String="Upper boundary of the time slice" />
        </Property>
      </ComplexType>

      <!-- Operations on Temporal Objects -->

      <Action Name="Update" IsBound="true" EntitySetPath="timeslices">
        <Annotation Term="Core.Description" String="Updates existing time slices with values from delta time slices whose object keys match and whose periods overlap" />
        <Annotation Term="Core.LongDescription">
          <String>The update behavior for a given object key is known from the [SQL statement](https://www.ibm.com/docs/en/db2oc?topic=statements-update)
          `UPDATE ... FOR PORTION OF BUSINESS_TIME ... WHERE ...`.

`deltaTimeslices` with non-matching object keys and non-overlapping sub-periods of `deltaTimeslices` are disregarded.</String>
        </Annotation>
        <Parameter Name="timeslices" Type="Collection(Edm.EntityType)" Nullable="false">
          <Annotation Term="Core.Description" String="Time slices to modify" />
        </Parameter>
        <Parameter Name="deltaTimeslices" Type="Collection(Temporal.TimesliceWithPeriod)" Nullable="false">
          <Annotation Term="Core.Description" String="New time slices whose property values are used to update the `timeslices` collection" />
          <Annotation Term="Core.LongDescription">
            <String>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.</String>
          </Annotation>
        </Parameter>
        <ReturnType Type="Collection(Edm.EntityType)" Nullable="false">
          <Annotation Term="Core.Description" String="Modified time slices" />
          <Annotation Term="Core.LongDescription" String="Same entity type as binding parameter." />
        </ReturnType>
      </Action>

      <Action Name="Upsert" IsBound="true" EntitySetPath="timeslices">
        <Annotation Term="Core.Description" String="Like [`Update`](#Update), but additionally inserts those (sub-periods of) `deltaTimeslices` that `Update` disregards" />
        <Parameter Name="timeslices" Type="Collection(Edm.EntityType)" Nullable="false">
          <Annotation Term="Core.Description" String="Time slices to modify" />
        </Parameter>
        <Parameter Name="deltaTimeslices" Type="Collection(Temporal.TimesliceWithPeriod)" Nullable="false">
          <Annotation Term="Core.Description" String="New time slices to be merged into the `timeslices` collection" />
          <Annotation Term="Core.LongDescription">
            <String>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.</String>
          </Annotation>
        </Parameter>
        <ReturnType Type="Collection(Edm.EntityType)" Nullable="false">
          <Annotation Term="Core.Description" String="Modified time slices" />
          <Annotation Term="Core.LongDescription" String="Same entity type as binding parameter." />
        </ReturnType>
      </Action>

      <Action Name="UpdateFrom" IsBound="true" EntitySetPath="timeslices">
        <Annotation Term="Core.Description" String="Like [`Update`](#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 Name="timeslices" Type="Collection(Edm.EntityType)" Nullable="false">
          <Annotation Term="Core.Description" String="Time slices to modify" />
        </Parameter>
        <Parameter Name="deltaTimeslices" Type="Collection(Temporal.TimesliceWithPeriod)" Nullable="false">
          <Annotation Term="Core.Description" String="New time slices whose property values are used to update the `timeslices` collection" />
          <Annotation Term="Core.LongDescription">
            <String>The 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.</String>
          </Annotation>
        </Parameter>
        <ReturnType Type="Collection(Edm.EntityType)" Nullable="false">
          <Annotation Term="Core.Description" String="Modified time slices" />
          <Annotation Term="Core.LongDescription" String="Same entity type as binding parameter." />
        </ReturnType>
      </Action>

      <Action Name="Delete" IsBound="true" EntitySetPath="timeslices">
        <Annotation Term="Core.Description" String="Deletes (sub-periods of) existing time slices whose object keys match and whose periods overlap `deltaTimeslices`" />
        <Annotation Term="Core.LongDescription">
          <String>The deletion behavior for a given object key is known from the [SQL statement](https://www.ibm.com/docs/en/db2oc?topic=statements-delete)
          `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.</String>
        </Annotation>
        <Parameter Name="timeslices" Type="Collection(Edm.EntityType)" Nullable="false">
          <Annotation Term="Core.Description" String="Time slices to modify" />
        </Parameter>
        <Parameter Name="deltaTimeslices" Type="Collection(Temporal.TimesliceWithPeriod)" Nullable="false">
          <Annotation Term="Core.Description" String="Time slices to be deleted from the `timeslices` collection" />
          <Annotation Term="Core.LongDescription">
            <String>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.</String>
          </Annotation>
        </Parameter>
        <ReturnType Type="Collection(Edm.EntityType)" Nullable="false">
          <Annotation Term="Core.Description" String="Deleted (sub-periods of) time slices" />
          <Annotation Term="Core.LongDescription" String="Same entity type as binding parameter." />
        </ReturnType>
      </Action>

      <Action Name="DeleteFrom" IsBound="true" EntitySetPath="timeslices">
        <Annotation Term="Core.Description" String="Like [`Delete`](#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 Name="timeslices" Type="Collection(Edm.EntityType)" Nullable="false">
          <Annotation Term="Core.Description" String="Time slices to modify" />
        </Parameter>
        <Parameter Name="deltaTimeslices" Type="Collection(Temporal.TimesliceWithPeriod)" Nullable="false">
          <Annotation Term="Core.Description" String="Time slices to be deleted from the `timeslices` collection" />
          <Annotation Term="Core.LongDescription">
            <String>The 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.</String>
          </Annotation>
        </Parameter>
        <ReturnType Type="Collection(Edm.EntityType)" Nullable="false">
          <Annotation Term="Core.Description" String="Deleted time slices" />
          <Annotation Term="Core.LongDescription" String="Same entity type as binding parameter." />
        </ReturnType>
      </Action>

    </Schema>
  </edmx:DataServices>
</edmx:Edmx>
