odata-dd-5 more work on step 1

qmacro · qmacro · commit b63351b10ad8 · 2026-02-17T17:41:27.000Z
diff --git a/tutorials/odata-dd-5-annotations/odata-dd-5-annotations.md b/tutorials/odata-dd-5-annotations/odata-dd-5-annotations.md
@@ -28,7 +28,7 @@ The members of the OData Technical Committee have worked hard on OData as a robu
 
 In the previous [Metadata](https://developers.sap.com/tutorials/odata-dd-4-metadata.html) tutorial we saw how the schema was presented within a context. That context is called the [entity model wrapper](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part3-csdl/odata-v4.0-errata03-os-part3-csdl-complete.html#_Toc453752500). We left the examination of part of that wrapper - the references to vocabularies, to this tutorial. Let's start by digging into those now.
 
-Here's what the relevant section of the wrapper looks like (with a little bit of whitespace to help readability):
+Here's what the relevant section of the wrapper in [the Northbreeze OData service's metadata document](https://odd.cfapps.eu10.hana.ondemand.com/northbreeze/$metadata) looks like:
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
@@ -49,9 +49,17 @@ Here's what the relevant section of the wrapper looks like (with a little bit of
 </edmx:Edmx>
 ```
 
-What are these references? Well, 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) of the CSDL standards document is helpful here (after section [3.1 Element edmx:Edmx](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part3-csdl/odata-v4.0-errata03-os-part3-csdl-complete.html#_Toc453752504) tells us that there can be zero or more of them).
+What are these references? Well, 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) of the CSDL standards document is helpful here (after section [3.1 Element edmx:Edmx](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part3-csdl/odata-v4.0-errata03-os-part3-csdl-complete.html#_Toc453752504) tells us that there can be zero or more of them within an `<edmx:Edmx>` element).
 
-Basically, `edmx:Reference` elements point to external CSDL documents, specific content from which (indicated by the `edmx:Include` elements within) is then added to the overall scope of the referring (OData metadata) document. Think of it like an "include" as found in various programming languages.
+Basically, `edmx:Reference` elements point to external CSDL documents, specific content from which (indicated by the `edmx:Include` elements within) is then added to the overall scope of the referring (OData metadata) document.
+
+Think of it like an "include" or "import" as found in various programming languages; these references might look like this in JavaScript, for example:
+
+```javascript
+import { "Org.OData.Capabilities.V1" as "Capabilities" } from "https://oasis-tcs.github.io/.../Org.OData.Capabilities.V1.xml";
+import { "com.sap.vocabularies.Common.v1" as "Common" } from "https://sap.github.io/.../Common.xml";
+import { "Org.OData.Core.V1" as "Core" } from "https://oasis-tcs.github.io/.../Org.OData.Core.V1.xml";
+```
 
 Note that each of the referenced external documents in our OData metadata document are resources in GitHub repositories:
 
@@ -66,7 +74,7 @@ Taking the first of the three `<edmx:Reference>` elements here, we see that:
 
 ![OASIS OData TC - Vocabularies](oasis-vocabularies-toc.png)
 
-If we look at the XML representation in CSDL (i.e. EDMX) form, we see this:
+If we look at the XML representation of the "Capabilities" vocabulary in CSDL form, we see this:
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
@@ -93,3 +101,19 @@ If we look at the XML representation in CSDL (i.e. EDMX) form, we see this:
   </edmx:DataServices>
 </edmx:Edmx>
 ```
+
+It's another EDMX document! There is a beauty to the OData specifications that is special. Anyway, there are two thing of note here:
+
+- this document _also_ has references to vocabularies
+- there is a single `<Schema>` element, with the OData namespace "Org.Data.Capabilities.V1"
+
+And that specific schema is exactly the one that's referenced in the `<edmx:Include>` element:
+
+```xml
+<edmx:Reference
+  Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Capabilities.V1.xml">
+  <edmx:Include Alias="Capabilities" Namespace="Org.OData.Capabilities.V1"/>
+</edmx:Reference>
+```
+
+It just so happens that in this referenced CSDL document, there _is_ only one schema, but there could be more. So an `<edmx:Include>` element forms an important part of the `<edmx:Reference>` (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) and serves to identify a particular schema to be included, from the referenced vocabulary. The `<edmx:Include>` element 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.
