Skip to content

Commit 7b2546f

Browse files
qmacroqmacro
committed
odata-dd-5 additions
1 parent f6d2cd6 commit 7b2546f

1 file changed

Lines changed: 68 additions & 1 deletion

File tree

‎tutorials/odata-dd-5-annotations/odata-dd-5-annotations.md‎

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ time: 20
2020

2121
## Intro
2222

23-
The members of the OData Technical Committee have worked hard on OData as a robust, well-defined and extensible standard. In this tutorial we'll look at a key extensibility mechanism in the form of Vocabularies, and a dominant use thereof in the form of Annotations.
23+
The members of the OData Technical Committee have worked hard on OData as a robust, well-defined and extensible standard. In this tutorial we'll look at a key extensibility mechanism in the form of vocabularies, and a dominant use thereof in the form of annotations.
2424

2525
---
2626

@@ -134,3 +134,70 @@ So an `<edmx:Include>` element forms an important part of the `<edmx:Reference>`
134134
> Indeed, [section 3.3 Element edmx:Reference](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part3-csdl/odata-v4.0-errata03-os-part3-csdl-complete.html#_Toc453752504) states that at least one `<edmx:Include>` or `<edmx:IncludeAnnotation>` is mandatory.
135135
136136
The `<edmx:Include>` element serves to identify a particular schema to be included, from the referenced vocabulary. It also does one more thing here - it specifies a short name, in the form of a value for an `Alias` attribute, which can be used to refer to that imported vocabulary schema. Just like the `as` aliasing in our imaginary JavaScript equivalent example earlier. So instead of the full name "Org.OData.Capabilities.V1" being needed to prefix vocabulary terms, the short form "Capabilities" can be used, as we'll see in subsequent steps.
137+
138+
### A first look at the annotations
139+
140+
Now we understand that annotations are organized into vocabularies, and have seen how such vocabulary resources are referenced to be included into an OData metadata document, let's now take a first look at what annotations are used in this particular OData metadata document, and how.
141+
142+
We should first take a brief look at the CSDL specification, and learn that:
143+
144+
- "Vocabulary annotations can be specified as a child of the model element being annotated or as a child of an `edm:Annotations` element that targets the model element." (from [section 4.6 Annotations](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part3-csdl/odata-v4.0-errata03-os-part3-csdl-complete.html#_Toc453752519))
145+
- "An annotation applies a term to a model element and defines how to calculate a value for the applied term." (from [section 14 Vocabulary and Annotation](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part3-csdl/odata-v4.0-errata03-os-part3-csdl-complete.html#_Vocabulary_and_Annotation))
146+
147+
Additionally:
148+
149+
- "A service SHOULD NOT require a client to interpret annotations. Clients SHOULD ignore unknown terms and silently treat unexpected or invalid values (including invalid type, invalid literal expression, etc.) as an unknown value for the term." ( also from [section 14 Vocabulary and Annotation](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part3-csdl/odata-v4.0-errata03-os-part3-csdl-complete.html#_Vocabulary_and_Annotation))
150+
151+
With the information from the first two points here, we can see in our OData metadata document that both approaches to annotation are used.
152+
153+
First, we see the "annotation as child element" approach where the annotation "Core.Links" is applied directly to the `<Schema>` element via the `<Annotation>` element which appears a direct child of `<Schema>`:
154+
155+
```xml
156+
<Schema Namespace="Main" xmlns="http://docs.oasis-open.org/odata/ns/edm">
157+
<Annotation Term="Core.Links">
158+
<Collection>
159+
<Record>
160+
<PropertyValue Property="rel" String="author"/>
161+
<PropertyValue Property="href" String="https://cap.cloud.sap"/>
162+
</Record>
163+
</Collection>
164+
</Annotation>
165+
...
166+
</Schema>
167+
```
168+
169+
Further on in the metadata document we see an example of the other approach, where `<Annotation>` elements appear as direct children of a containing `<Annotations>` element, and the elements to which the annotations are applied are specified in `Target` attributes):
170+
171+
> Again, as explained in the previous [Metadata](https://developers.sap.com/tutorials/odata-dd-4-metadata.html) tutorial, in the "Get acquainted with the schema element" step, we'll leave out the XML namespace prefix `edm` her when writing elements that belong to that namespace.
172+
173+
174+
```xml
175+
<Schema Namespace="Main" xmlns="http://docs.oasis-open.org/odata/ns/edm">
176+
...
177+
<EntityContainer Name="EntityContainer">
178+
<EntitySet Name="Categories" EntityType="Main.Categories">
179+
<NavigationPropertyBinding Path="Products" Target="Products"/>
180+
</EntitySet>
181+
</EntityContainer>
182+
...
183+
<Annotations Target="Main.EntityContainer/Categories">
184+
<Annotation Term="Capabilities.DeleteRestrictions">
185+
<Record Type="Capabilities.DeleteRestrictionsType">
186+
<PropertyValue Property="Deletable" Bool="false"/>
187+
</Record>
188+
</Annotation>
189+
<Annotation Term="Capabilities.InsertRestrictions">
190+
<Record Type="Capabilities.InsertRestrictionsType">
191+
<PropertyValue Property="Insertable" Bool="false"/>
192+
</Record>
193+
</Annotation>
194+
<Annotation Term="Capabilities.UpdateRestrictions">
195+
<Record Type="Capabilities.UpdateRestrictionsType">
196+
<PropertyValue Property="Updatable" Bool="false"/>
197+
</Record>
198+
</Annotation>
199+
</Annotations>
200+
</Schema>
201+
```
202+
203+
Here, three different annotations terms "Capabilities.DeleteRestrictions", "Capabilities.InsertRestrictions" and "Capabilities.UpdateRestrictions" are being applied, via `Target="Main.EntityContainer/Categories"` to the "Categories" entityset in the entity container named "EntityContainer" in the "Main" OData namespace.

0 commit comments

Comments
 (0)