\(\hbox{}\)

This stage:

https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/csd04/odata-temporal-ext-v4.0-csd04.md (Authoritative)
https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/csd04/odata-temporal-ext-v4.0-csd04.html
https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/csd04/odata-temporal-ext-v4.0-csd04.pdf

Previous stage:

https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/cs01/odata-temporal-ext-v4.0-cs01.docx (Authoritative)
https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/cs01/odata-temporal-ext-v4.0-cs01.html
https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/cs01/odata-temporal-ext-v4.0-cs01.pdf

Latest stage:

https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/odata-temporal-ext-v4.0.md (Authoritative)
https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/odata-temporal-ext-v4.0.html
https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/odata-temporal-ext-v4.0.pdf

Technical Committee:

OASIS Open Data Protocol (OData) TC

Chairs:

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

Editors:

Ralf Handl (ralf.handl@sap.com), SAP SE
Hubert Heijkers (hubert.heijkers@nl.ibm.com), IBM
Gerald Krause (gerald.krause@sap.com), SAP SE
Michael Pizzo (mikep@microsoft.com), Microsoft
Heiko Theißen (heiko.theissen@sap.com), SAP SE
Martin Zurmuehl (martin.zurmuehl@sap.com), SAP SE

Additional artifacts:

This document is one component of a Work Product that also includes:

• ABNF components: OData Temporal ABNF Construction Rules Version 4.0 and OData Temporal ABNF Test Cases: https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/csd04/abnf/
• OData Temporal Vocabulary:
  • https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/csd04/vocabularies/Org.OData.Temporal.V1.json
  • https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/csd04/vocabularies/Org.OData.Temporal.V1.xml

Related work:

This specification is related to:

• OData Version 4.02. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. A multi-part Work Product that includes:
  • OData Version 4.02 Part 1: Protocol. Latest stage. https://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html
  • OData Version 4.02 Part 2: URL Conventions. Latest stage. https://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html
  • ABNF components: OData ABNF Construction Rules Version 4.02 and OData ABNF Test Cases. https://docs.oasis-open.org/odata/odata/v4.0/csd04/abnf/
• OData Vocabularies Version 4.0. Edited by Michael Pizzo, Ralf Handl, and Ram Jeyaraman. Latest stage: https://docs.oasis-open.org/odata/odata-vocabularies/v4.0/odata-vocabularies-v4.0.html
• OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-json/v4.0/odata-csdl-json-v4.0.html
• OData Common Schema Definition Language (CSDL) XML Representation Version 4.02. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-xml/v4.0/odata-csdl-xml-v4.0.html
• OData JSON Format Version 4.02. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. Latest stage: https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html
• OData Data Aggregation Extension Version 4.0. Edited by Ralf Handl, Hubert Heijkers, Gerald Krause, Michael Pizzo, Heiko Theißen, and Martin Zurmuehl. Latest stage: https://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/odata-data-aggregation-ext-v4.0.html

Abstract:

This specification defines how to represent and interact with time-dependent data using the Open Data Protocol (OData).

Status:

This document was last revised or approved by the OASIS Open Data Protocol (OData) TC on the above date. The level of approval is also listed above. Check the “Latest stage” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://groups.oasis-open.org/communities/tc-community-home2?CommunityKey=e7cac2a9-2d18-4640-b94d-018dc7d3f0e2#technical.

TC members should send comments on this specification to the TC’s email list. Any individual may submit comments to the TC by sending email to Technical-Committee-Comments@oasis-open.org. Please use a Subject line like “Comment on OData Temporal”.

This specification is provided under the RF on RAND Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page (https://www.oasis-open.org/committees/odata/ipr.php).

Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product’s prose narrative document(s), the content in the separate plain text file prevails.

Key words:

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 RFC2119 and RFC8174 when, and only when, they appear in all capitals, as shown here.

Citation format:

When referencing this specification the following citation format should be used:

[OData-Temporal-v4.0]

OData Extension for Temporal Data Version 4.0. Edited by Ralf Handl, Hubert Heijkers, Gerald Krause, Michael Pizzo, Heiko Theißen, and Martin Zurmuehl. 25 January 2022. OASIS Committee Specification Draft 04. https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/csd04/odata-temporal-ext-v4.0-csd04.html. Latest stage: https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/odata-temporal-ext-v4.0.html.

Notices

Copyright © OASIS Open 2022. All Rights Reserved.

Distributed under the terms of the OASIS IPR Policy.

The name “OASIS” is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs.

For complete copyright information please see the full Notices section in an Appendix below.

Assume a simple scenario: employees will work in different roles and in different departments during their career, and sometimes they even change their name. At each point in time the employee has exactly one name, one job title, and is assigned to one department.

Employees are assigned an immutable ID when first entering the company, and all employee-related data will be recorded with an application-time period attached. This allows entering planned changes ahead of time, using a future application-time start date: if an employee will get a different job title or switch to a different department, this data can already be entered into the system and stored as a new record.

In the sections below we will discuss two different API models that can be backed by the same storage model:

and

Both API models in the previous section are views on the same underlying data. A possible storage model for this data is:

The period start date is used as the temporal sub-key for identifying time slices together with the key of the temporal object.

Note: alternatively, the period end date could have been used as temporal sub-key, or the primary key of the time slice tables could have been an artificial key (sequence number, UUID, …) with both the temporal object key and the period boundaries as non-key fields.

The following example data will be used to further illustrate the capabilities introduced by this extension. It assumes that the example services only support four-digit years.

A client might wish to query the example APIs in several ways:

• Snapshot API
  1. Retrieve a current employee, together with the employee’s current department.
  2. Retrieve an employee as of a particular point in time, including the employee’s department as of that same point in time.
• Timeline API
  1. Retrieve employees that worked for the “Services” department in 2010.
  2. Retrieve all time slices of an employee.
  3. Retrieve all time slices of an employee for a given application-time period, including all time slices of the related departments within the application-time period of each employee time slice.
  4. Change a department’s budget in the past, present, or future.
  5. Change an employee’s association to a department in the past, present, or future.

A temporal expression is

• A date in the form dateValue, see OData-ABNF
• A timestamp in the form dateTimeOffsetValueInUrl, see OData-ABNF
• One of the literals min or max
• An expression resulting in a date or timestamp value

The literals min and max are interpreted depending on the data type of the time period start and end. They represent the minimum and maximum values of the time period that the service will allow. Their values are service specific as they can depend on the capabilities of the underlying data model.

Note that there is no literal for “today” as clients and services can be in different time zones and thus can have different notions of which date is “today”. Clients are advised to use concrete temporal values and should avoid using the URL function now() with period start and end of type Edm.Date.

Note that services may allow service-defined functions for temporal expressions, for example to deal with fiscal years in a particular company.

Temporal query options allow point-in-time as well as time-range queries. They take a temporal expression as their argument whose result type MUST match the type of the corresponding time period start and end.

Adding temporal query options to a request does not alter the response shape, it only affects the returned data.

Temporal query options can be used with data modification operations, in which case they do not alter the modification semantics of the request, they only affect the response. That is, they only influence the “implicit GET” after successful data modification.

If no temporal query options are specified,

• timeline entity sets return all time slices, and
• snapshot entity sets return the snapshot valid at the time of the request.

GET /api-1/Employees('E314')

{
  "@context": "$metadata#Employees/$entity",
  "ID": "E314",
  "Name": "McDevitt",
  "Jobtitle": "Senior"
}

GET /api-1/Employees('E314')?$at=2012-01-01

{
  "@context": "$metadata#Employees/$entity",
  "ID": "E314",
  "Name": "McDevitt",
  "Jobtitle": "Junior"
}

GET /api-1/Employees?$filter=contains(Name,'i')&$at=2012-01-01

{
  "@context": "$metadata#Employees",
  "value": [
    {
      "ID": "E314",
      "Name": "McDevitt",
      "Jobtitle": "Junior"
    }
  ]
}

GET /api-1/Employees('E314')?$at=2012-01-01&$expand=Department($at=2021-11-23)

{
  "@context": "$metadata#Employees/$entity",
  "ID": "E314",
  "Name": "McDevitt",
  "Jobtitle": "Junior",
  "Department": {
    "ID": "D08",
    "Name": "1st Level Support"
  }
}

GET /api-1/Departments('D15')?$at=2015-01-01&$expand=Employees

{
  "@context": "$metadata#Departments/$entity",
  "ID": "D15",
  "Name": "Services",
  "Employees": [
    {
      "ID": "E314",
      "Name": "McDevitt",
      "Jobtitle": "Senior"
    },
    {
      "ID": "E401",
      "Name": "Gibson",
      "Jobtitle": "Expert"
    }
  ]
}

GET /api-2/Employees?$expand=history($select=Name,Jobtitle)
                    &$from=2012-03-01&$to=2025-01-01

{
  "@context": "$metadata#Employees",
  "value": [
    {
      "ID": "E314",
      "history": [
        {
          "Name": "McDevitt",
          "Jobtitle": "Junior",
          "From": "2011-01-01",
          "To": "2013-10-01"
        },
        {
          "Name": "McDevitt",
          "Jobtitle": "Senior",
          "From": "2013-10-01",
          "To": "2014-01-01"
        },
        {
          "Name": "McDevitt",
          "Jobtitle": "Senior",
          "From": "2014-01-01",
          "To": "9999-12-31"
        }
      ]
    },
    {
      "ID": "E401",
      "history": [
        {
          "Name": "Gibson",
          "Jobtitle": "Expert",
          "From": "2012-03-01",
          "To": "9999-12-31"
        }
      ]
    }
  ]
}

GET /api-2/Departments('D15')/Employees?
    $expand=history(
      @emp=$this;
      $expand=Department(
        $expand=history($at=@emp/From)
      )
    )

{
  "@context": "$metadata#Employees",
  "value": [
    {
      "ID": "E314",
      "history": [
        {
          "Name": "McDevitt",
          "Jobtitle": "Junior",
          "From": "2011-01-01",
          "To": "2013-10-01",
          "Department": {
            "ID": "D08",
            "history": [{
              "Name": "Support",
              "Budget": 1000,
              "From": "2010-01-01",
              "To": "2012-10-01"
            }]
          }
        },
        {
          "Name": "McDevitt",
          "Jobtitle": "Senior",
          "From": "2013-10-01",
          "To": "2014-01-01",
          "Department": {
            "ID": "D08",
            "history": [{
              "Name": "1st Level Support",
              "Budget": 1250,
              "From": "2012-06-01",
              "To": "2014-01-01"
            }]
          }
        },
        {
          "Name": "McDevitt",
          "Jobtitle": "Senior",
          "From": "2014-01-01",
          "To": "9999-12-31",
          "Department": {
            "ID": "D15",
            "history": [{
              "Name": "Services",
              "Budget": 1170,
              "From": "2011-01-01",
              "To": "9999-12-31"
            }]
          }
        }
      ]
    },
    {
      "ID": "E401",
      "history": [
        {
          "Name": "Norman",
          "Jobtitle": "Expert",
          "From": "2009-11-01",
          "To": "2012-03-01",
          "Department": {
            "ID": "D15",
            "history": []
          }
        },
        {
          "Name": "Gibson",
          "Jobtitle": "Expert",
          "From": "2012-03-01",
          "To": "9999-12-31",
          "Department": {
            "ID": "D15",
            "history": [{
              "Name": "Services",
              "Budget": 1170,
              "From": "2011-01-01",
              "To": "9999-12-31"
            }]
          }
        }
      ]
    }
  ]
}

GET /api-2/Employees?$expand=history(
                       $select=Name,Jobtitle;
                       $from=2012-03-01&$to=2025-01-01;
                       $filter=contains(Jobtitle,'e')
                     )

{
  "@context": "$metadata#Employees",
  "value": [
    {
      "ID": "E314",
      "history": [
        {
          "Name": "McDevitt",
          "Jobtitle": "Senior",
          "From": "2013-10-01",
          "To": "2014-01-01"
        },
        {
          "Name": "McDevitt",
          "Jobtitle": "Senior",
          "From": "2014-01-01",
          "To": "9999-12-31"
        }
      ]
    },
    {
      "ID": "E401",
      "history": [
        {
          "Name": "Gibson",
          "Jobtitle": "Expert",
          "From": "2012-03-01",
          "To": "9999-12-31"
        }
      ]
    }
  ]
}

GET /api-2/Employees?$expand=history($select=Name,Jobtitle)
                    &$from=2015-01-01
                    &$filter=history/any(h:startswith(h/Name,'N'))

{
  "@context": "$metadata#Employees",
  "value": [
    {
      "ID": "E401",
      "history": [
        {
          "Name": "Gibson",
          "Jobtitle": "Expert",
          "From": "2012-03-01",
          "To": "9999-12-31"
        }
      ]
    }
  ]
}

This section and its subsections describe modifications in application time, both for

• snapshot entity sets with hidden application time, where time slices exist in the data persistency but are not directly visible in the entity set, each OData entity corresponds to a temporal object and only represents data at one point in time, and for
• timeline entity sets with visible application time, where each OData entity corresponds to an application-time slice and all application-time slices of a temporal object are part of the entity set.

Modification operations fall into two categories:

• Direct modification of time slices, and
• Changes to a temporal object over a period of application time that can affect multiple time slices without explicitly addressing each single affected time slice.

POST /api-2/Departments('D08')/history/Temporal.Update
Content-Type: application/json

{
  "deltaTimeslices": [
    {
      "Timeslice": {
        "From": "2012-04-01",
        "To": "2014-07-01",
        "Budget": 1320
      }
    }
  ]
}

{
  "@context": "../../$metadata#Collection(Temporal.TimesliceWithPeriod)",
  "value": [
    {
      "Timeslice": {
        "@context": "#Departments('D08')/history/$entity",
        "From": "2012-01-01",
        "To": "2012-04-01",
        "Name": "Support",
        "Budget": 1250
      }
    },
    {
      "Timeslice": {
        "@context": "#Departments('D08')/history/$entity",
        "From": "2012-04-01",
        "To": "2012-06-01",
        "Name": "Support",
        "Budget": 1320
      }
    },
    {
      "Timeslice": {
        "@context": "#Departments('D08')/history/$entity",
        "From": "2012-06-01",
        "To": "2014-01-01",
        "Name": "1st Level Support",
        "Budget": 1320
      }
    },
    {
      "Timeslice": {
        "@context": "#Departments('D08')/history/$entity",
        "From": "2014-01-01",
        "To": "2014-07-01",
        "Name": "1st Level Support",
        "Budget": 1320
      }
    },
    {
      "Timeslice": {
        "@context": "#Departments('D08')/history/$entity",
        "From": "2014-07-01",
        "To": "9999-12-31",
        "Name": "1st Level Support",
        "Budget": 1400
      }
    }
  ]
}

POST /api-1/Employees/Temporal.Update
Content-Type: application/json

{
  "deltaTimeslices": [
    {
      "PeriodStart": "2021-10-01",
      "Timeslice": {
        "ID": "E401",
        "Jobtitle": "Ultimate Expert"
      }
    }
  ]
}

{
  "@context": "../$metadata#Collection(Temporal.TimesliceWithPeriod)",
  "value": [
    {
      "PeriodStart": "2012-03-01",
      "PeriodEnd": "2021-10-01",
      "Timeslice": {
        "@context": "#Employees/$entity",
        "ID": "E401",
        "Name": "Gibson",
        "Jobtitle": "Expert"
      }
    },
    {
      "PeriodStart": "2021-10-01",
      "PeriodEnd": "9999-12-31",
      "Timeslice": {
        "@context": "#Employees/$entity",
        "ID": "E401",
        "Name": "Gibson",
        "Jobtitle": "Ultimate Expert"
      }
    }
  ]
}

POST /api-3/CostCenters/Temporal.Upsert
Content-Type: application/json

{
  "deltaTimeslices": [
    {
      "Timeslice": {
        "AreaID": "51",
        "CostCenterID": "C1",
        "ValidTo": "2001-03-31",
        "ValidFrom": "1984-04-01",
        "ProfitCenterID": "P2"
      }
    },
    {
      "Timeslice": {
        "AreaID": "51",
        "CostCenterID": "C2",
        "ValidFrom": "2012-04-01",
        "DepartmentID": "D04"
      }
    }
  ]
}

{
  "@context": "../$metadata#Collection(Temporal.TimesliceWithPeriod)",
  "value": [
    {
      "Timeslice": {
        "@context": "#CostCenters/$entity",
        "tsid": "n",
        "AreaID": "51",
        "CostCenterID": "C1",
        "ValidTo": "1984-03-31",
        "ValidFrom": "1955-04-01",
        "ProfitCenterID": "P1",
        "DepartmentID": "D02"
      }
    },
    {
      "Timeslice": {
        "@context": "#CostCenters/$entity",
        "tsid": "o",
        "AreaID": "51",
        "CostCenterID": "C1",
        "ValidTo": "2001-03-31",
        "ValidFrom": "1984-04-01",
        "ProfitCenterID": "P2",
        "DepartmentID": "D02"
      }
    },
    {
      "Timeslice": {
        "@context": "#CostCenters/$entity",
        "tsid": "p",
        "AreaID": "51",
        "CostCenterID": "C1",
        "ValidTo": "9999-12-31",
        "ValidFrom": "2001-04-01",
        "ProfitCenterID": "P1",
        "DepartmentID": "D02"
      }
    },
    {
      "Timeslice": {
        "@context": "#CostCenters/$entity",
        "tsid": "q",
        "AreaID": "51",
        "CostCenterID": "C2",
        "ValidTo": "9999-12-31",
        "ValidFrom": "2012-04-01",
        "ProfitCenterID": null,
        "DepartmentID": "D04"
      }
    }
  ]
}

The following documents are referenced in such a way that some or all of their content constitutes requirements of this document.

OData-ABNF

ABNF components: OData ABNF Construction Rules Version 4.02 and OData ABNF Test Cases.
See link in “Related work” section on cover page.

OData-Aggregation

OData Extension for Data Aggregation Version 4.0.
See link in “Related work” section on cover page.

OData-CSDL

OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02.
See link in “Related work” section on cover page.

OData Common Schema Definition Language (CSDL) XML Representation Version 4.02.
See link in “Related work” section on cover page.

OData-Protocol

OData Version 4.02. Part 1: Protocol.
See link in “Related work” section on cover page.

OData-URL

OData Version 4.02. Part 2: URL Conventions.
See link in “Related work” section on cover page.

OData-VocCap

OData Vocabularies Version 4.0: Capabilities Vocabulary.
See link in “Related work” section on cover page.

OData-VocCore

OData Vocabularies Version 4.0: Core Vocabulary.
See link in “Related work” section on cover page.

OData-VocTemporal

OData Temporal Vocabulary.
See link in “Additional artifacts” section on cover page.

RFC2119

Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997
https://www.rfc-editor.org/info/rfc2119.

RFC8174

Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017
https://www.rfc-editor.org/info/rfc8174.

Fowler

Martin Fowler, “Temporal Patterns”, 16 February 2005
http://martinfowler.com/eaaDev/timeNarrative.html.

Kulkarni

Krishna Kulkarni, “Temporal Features in SQL standard”, September 2012
https://dbs.uni-leipzig.de/file/Temporal%20features%20in%20SQL2011.pdf.

Snodgrass

Richard T. Snodgrass, “Developing Time-Oriented Database Applications in SQL”, Morgan Kaufmann Publishers, Inc., San Francisco, July, 1999, ISBN 1-55860-436-7
http://www2.cs.arizona.edu/people/rts/tdbbook.pdf and http://www2.cs.arizona.edu/people/rts/pp30-31.pdf.

SQL:2011

ISO/IEC 9075-2:2011 Information technology - Database languages - SQL - Part 2: Foundation (SQL/Foundation).

The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol are gratefully acknowledged.

Special thanks to Andrew Eisenberg, whose contributions in the early stages of the OData TC were invaluable to getting this extension specification on track.

OData TC Members: