-
Notifications
You must be signed in to change notification settings - Fork 45
/
Org.OData.Temporal.V1.xml
238 lines (214 loc) · 15.5 KB
/
Org.OData.Temporal.V1.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
<?xml version="1.0" encoding="utf-8"?>
<!--
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.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.
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.</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" />
<Annotation Term="Core.LongDescription">
<String>If an upper boundary property does not specify a default value, a default value of `max` is assumed.</String>
</Annotation>
</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`,
and they are interpreted according to the [`ApplicationTimeSupport/UnitOfTime`](#ApplicationTimeSupportType) 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`.</String>
</Annotation>
<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>
<NavigationProperty Name="Timeslice" Type="Edm.EntityType" Nullable="false">
<Annotation Term="Core.AutoExpand" />
<Annotation Term="Core.Description" String="A time slice with the same entity type as the binding parameter of the action" />
<Annotation Term="Core.LongDescription">
<String>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.</String>
</Annotation>
</NavigationProperty>
</ComplexType>
<!-- Operations on Temporal Objects -->
<Action Name="Update" IsBound="true">
<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(Temporal.TimesliceWithPeriod)" Nullable="false">
<Annotation Term="Core.Description" String="Modified time slices" />
</ReturnType>
</Action>
<Action Name="Upsert" IsBound="true">
<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(Temporal.TimesliceWithPeriod)" Nullable="false">
<Annotation Term="Core.Description" String="Modified time slices" />
</ReturnType>
</Action>
<Action Name="Delete" IsBound="true">
<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(Temporal.TimesliceWithPeriod)" Nullable="false">
<Annotation Term="Core.Description" String="Deleted (sub-periods of) time slices" />
</ReturnType>
</Action>
</Schema>
</edmx:DataServices>
</edmx:Edmx>