SAP OData Vocabularies

https://sap.github.io/odata-vocabularies
Admin
SAP OData Vocabularies provide semantic markup for structured data published via OData services,...
Tokens:15,232
Snippets:92
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### OData GET Request: Search Query Option Example

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

This example shows a GET request to an OData service utilizing the custom 'search' query option. The 'search' option allows clients to pass a free-text search term to the backend, enabling flexible searching across entity properties. The backend service implementation determines how this term is matched and against which properties.

```http
GET /Orders?search=blue
```

--------------------------------

### Install Node.js Dependencies with npm

Source: https://sap.github.io/odata-vocabularies/index

This command installs the necessary Node.js dependencies for contributors working with the OData vocabularies repository. It requires Node.js to be installed on the system.

```shell
npm install
```

--------------------------------

### Common Text Annotation Example

Source: https://sap.github.io/odata-vocabularies/vocabularies/UI

Demonstrates how to use the Common.Text annotation to specify the text or ID property for an annotation value. This is useful for localizing or providing descriptive text for properties.

```odata
Property Name @Common.Text : 'PropertyName'

```

--------------------------------

### Example Hierarchical OData Query (OData)

Source: https://sap.github.io/odata-vocabularies/vocabularies/Hierarchy

Demonstrates a sample OData query utilizing hierarchical transformations such as 'descendants', 'ancestors', and 'Hierarchy.TopLevels'. It shows how to apply filters and specify hierarchy levels.

```odata
SalesOrganizations?$apply=
descendants(..., ID, filter(ID eq 'US'), keep start)
/ancestors(..., ID, filter(contains(Name, 'New York')), keep start)
/Hierarchy.TopLevels(..., NodeProperty='ID', Levels=2)
&$top=10
```

--------------------------------

### Constant Annotation Values for Primitive Types (Reference)

Source: https://sap.github.io/odata-vocabularies/docs/annotation-cheat-sheet-cap

Provides a reference table for constructing constant annotation values for various EDM primitive types. This includes examples for strings, numbers, booleans, dates, and other scalar types.

```text
Edm.Binary | 'T0RhdGE'
Edm.Boolean | true
Edm.Date | '2000-01-01'
Edm.DateTimeOffset | '2000-01-01T16:00:00.000Z'
Edm.Decimal | '3.14'
Edm.Duration | 'P7D'
Enumeration Type | #Red
Edm.Double or Edm.Single | 3.14
Edm.Guid | '21EC2020-3AEA-1069-A2DD-08002B30309D'
Edm.Int16, Edm.Int32, Edm.64, Edm.Byte, Edm.SByte | 42
Edm.Int64 | '42'
Edm.String | 'annotation value'
Edm.TimeOfDay | '21:45:00'
Edm.AnnotationPath | 'Product/Supplier/@UI.LineItem'
Edm.NavigationPropertyPath | Supplier
Edm.PropertyPath | Details.ChangedAt
```

--------------------------------

### MultiLevelExpand Function Example in OData

Source: https://sap.github.io/odata-vocabularies/vocabularies/Analytics

Demonstrates the usage of the experimental MultiLevelExpand function within an OData `$apply` transformation. This function is used to expand a leveled hierarchy with custom aggregation of properties, supporting complex filtering, grouping, and expansion logic.

```odata
$apply=filter(Industry in ('IT','AI'))
/groupby((Country,Region,Segment,Industry),
         filter($these/aggregate(Amount) gt 0 and
                $these/aggregate(Currency) ne null))
/concat(
  groupby((Country,Region,Segment,Industry))
    /aggregate($count as LeavesCount),
  aggregate(Amount,Currency),
  Analytics.MultiLevelExpand(
    LevelProperties=[{"DimensionProperties":["Country"],"AdditionalProperties":["CountryName"]},
                     {"DimensionProperties":["Region"],"AdditionalProperties":["RegionName"]},
                     {"DimensionProperties":["Segment","Industry"],"AdditionalProperties":[]}],
    Aggregation=["Amount","Currency"],
    SiblingOrder=[{"Property":"Amount","Descending":true}],
    Levels=2,
    ExpandLevels=[{"Entry":["US"],"Levels":0},
                  {"Entry":["DE","BW"],"Levels":1}]
  )/concat(aggregate($count as ResultEntriesCount),
           skip(20)/top(10)))

```

--------------------------------

### OData Batch Request for Copying and Reparenting Hierarchy Nodes

Source: https://sap.github.io/odata-vocabularies/vocabularies/Hierarchy

Demonstrates an OData batch request to copy a node and its descendants, followed by reparenting the copied node using a PATCH request. This example illustrates how to use CopyAction and ChangeNextSiblingAction in sequence.

```odata
{
  "requests": [
    {
      "id": "1",
      "method": "post",
      "url": "HierarchyDirectory(1)/Nodes('A')/CopyAction"
    },
    {
      "id": "2",
      "dependsOn": ["1"],
      "method": "patch",
      "url": "$1",
      "body": {
        "Superordinate@odata.bind": "Nodes('B')"
      }
    }
  ]
}
```

--------------------------------

### Example Function Imports for Leave Request Approval in OData

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

Demonstrates the use of `edm:FunctionImport` for actions like approving or rejecting leave requests. It includes attributes such as `sap:action-for` to specify the entity type and `sap:applicable-path` to control invocation.

```xml
<FunctionImport Name="LeaveRequestApproval"
                ReturnType="ThisModel.ApprovalResult"
                m:HttpMethod="POST"
                sap:label="Approve"
                sap:action-for="ThisModel.LeaveRequest"
                sap:applicable-path="ControlData/NeedsApproval">
  <Parameter Name="ID" Type="Edm.Guid" Mode="In" />
</FunctionImport>

<FunctionImport Name="LeaveRequestRejection"
                ReturnType="ThisModel.ApprovalResult"
                m:HttpMethod="POST"
                sap:label="Reject"
                sap:action-for="ThisModel.LeaveRequest"
                sap:applicable-path="ControlData/NeedsApproval">
  <Parameter Name="ID" Type="Edm.Guid" Mode="In" />
  <Parameter Name="Reason" Type="Edm.String" Mode="In" />
</FunctionImport>
```

--------------------------------

### OData Error Message Structure Example (EDM)

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

Defines the minimum structure for OData error messages, including code, message, target, and severity. This structure is crucial for consistent error reporting in OData services.

```EDM
<code>:
  Edm.String
<message>:
  Edm.String
<target>:
  Edm.String nullable
<additionalTargets>:
  Collection(Edm.String)
<transition>:
  Edm.Boolean
<numericSeverity>:
  Edm.Byte
<longtextUrl>:
  Edm.String nullable
```

--------------------------------

### Maintain Recursive Hierarchy Nodes - JSON Request Example

Source: https://sap.github.io/odata-vocabularies/vocabularies/Hierarchy

This JSON example demonstrates how to maintain nodes within a recursive hierarchy using OData actions. It includes requests for creating a child node and changing its sibling order. The 'dependsOn' property ensures sequential execution of dependent requests.

```json
{
  "requests": [{
    "id": "1",
    "method": "post",
    "url": "HierarchyDirectory(1)/Nodes",
    "body": {
      "Name": "child of A",
      "Superordinate@odata.bind": "Nodes('A')"
    }
  }, {
    "id": "2",
    "dependsOn": ["1"],
    "method": "post",
    "url": "$1/Hierarchy.ChangeNextSiblingAction",
    "body": {
      "NextSibling": null
    }
  }]
}
```

--------------------------------

### Example Recursive Rollup OData Query (OData)

Source: https://sap.github.io/odata-vocabularies/vocabularies/Hierarchy

Presents an OData query that uses 'rolluprecursive' for hierarchical data processing, combined with 'descendants', 'ancestors', and aggregation. It illustrates a more complex hierarchical data retrieval scenario.

```odata
SalesOrganizations?$apply=groupby((rolluprecursive(..., ID,
  descendants(..., ID, filter(ID eq 'US')),
  ancestors(..., ID, filter(contains(Name, 'New York')), keep start))), aggregate(...))
/Hierarchy.TopLevels(..., NodeProperty='ID', Levels=2)
&$top=10
```

--------------------------------

### OData Metadata: Instance Annotation Property Example

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

This XML snippet demonstrates how to define a property in an OData metadata document that holds an instance annotation value. The 'sap:is-annotation="true"' attribute identifies the property as an annotation holder, separating it from regular data properties. This is crucial for distinguishing between metadata annotations and instance annotations.

```xml
<Property Name="Street" Type="Edm.String" Nullable="true" sap:field-control="Address_FC" />
<Property Name="City" Type="Edm.String" Nullable="true" sap:field-control="Address_FC" />
<Property Name="Address_FC" Type="Edm.Byte" Nullable="true" sap:is-annotation="true" />
```

--------------------------------

### Build OData Vocabularies JSON/Markdown Files

Source: https://sap.github.io/odata-vocabularies/CONTRIBUTING

Executes the build process to synchronize XML source files with JSON and Markdown outputs. This command is crucial before committing changes to ensure data consistency. It is also automatically executed by GitHub Actions for pull requests.

```shell
npm run build
```

--------------------------------

### AtomPub Service Document - app:collection Element

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

Explains the annotations and attributes applicable to the `app:collection` element in an AtomPub service document, including member titles, search links, and subscription links.

```APIDOC
## AtomPub Service Document - app:collection Element

### Description

This section describes the annotations and attributes that can be applied to the `app:collection` element, representing a collection of resources within the service document.

### Annotations and Attributes

- **`<sap:member-title>`**: Defines a human-readable name or caption for individual items within the collection. This is often the singular form of the collection's title.
- **`<atom:link rel="search" href="..."/>`**: Links to an OpenSearch description document, enabling free-text search for the collection by appending the `search` query option to the collection's URL.
- **`<atom:link rel="http://www.sap.com/Protocols/SAPData/rel#subscribe" href="..."/>`**: Provides a link to a collection that allows clients to subscribe to changes within the annotated collection. Refer to SAP NetWeaver Gateway documentation for details on subscription and notification.
- **`sap:addressable`**: An attribute that indicates whether the collection is addressable, mirroring the value of the corresponding entity set in the metadata document.
```

--------------------------------

### ApplicationType

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

Provides information about the software component, service ID, repository, and version of a service implementation.

```APIDOC
## ApplicationType

### Description
Provides information about the software component, service ID, repository, and version of a service implementation.

### Properties
- **Component** (String?): Software component of service implementation.
- **ServiceRepository** (String?): Service repository.
- **ServiceId** (String?): Service identifier.
- **ServiceVersion** (String?): Service version.
```

--------------------------------

### AtomPub Service Document Annotations

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

Demonstrates how to annotate AtomPub service documents with SAP-specific and Atom namespace elements to provide additional metadata for collections.

```xml
<atom:link rel="self" href="..."/>
<atom:link rel="latest-version" href="..."/>
<sap:member-title>...</sap:member-title>
<atom:link rel="search" href="..."/>
<atom:link rel="http://www.sap.com/Protocols/SAPData/rel#subscribe" href="..."/>
```

--------------------------------

### AtomPub Service Document - app:service Element

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

Describes the annotations and elements that can be used within the `app:service` element of an AtomPub service document, including links to the service document itself and its latest version.

```APIDOC
## AtomPub Service Document - app:service Element

### Description

This section details the annotations for the `app:service` element, which represents the root of an OData service document.

### Annotations

- **`<atom:link rel="self" href="..."/>`**: Specifies the URL of the service document itself.
- **`<atom:link rel="latest-version" href="..."/>`**: Provides the URL to the latest version of the service.

### Usage

Clients can use the `latest-version` link to potentially switch to a newer service version if it differs from the current one, possibly after user confirmation.
```

--------------------------------

### OData Entity Type with UI.Recommendations Annotation (XML)

Source: https://sap.github.io/odata-vocabularies/docs/recommendations

This snippet demonstrates an OData EntityType definition in XML, showcasing the use of the 'UI.Recommendations' annotation to point to a 'SAP__Recommendations' property. It includes the structure for the EntityType, Key, Properties, and the associated ComplexType for recommendations.

```xml
<EntityType Name="...">
  <Annotation Term="UI.Recommendations" Path="SAP__Recommendations" />
  <Key>
    <PropertyRef Name="ID" />
  </Key>
  <Property Name="ID" Type="Edm.String" Nullable="false" />
  <Property Name="DocumentType" Type="Edm.String" />
  ...
  <Property Name="SAP__Recommendations" Type="self.RecommendationsType" />
</EntityType>
<ComplexType Name="RecommendationsType">
  <Property Name="DocumentType" Type="Collection(UI.PropertyRecommendationType)" />
  ...
</ComplexType>
```

--------------------------------

### CreatedBy Annotation

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

The `CreatedBy` annotation indicates the user who first created a resource.

```APIDOC
## CreatedBy

### Description
First editor.

### Method
N/A (Annotation)

### Endpoint
N/A (Annotation)

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **value** (UserID?) - The ID of the user who created the resource.

#### Response Example
```json
{
  "value": "user123"
}
```
```

--------------------------------

### Parameter Types

Source: https://sap.github.io/odata-vocabularies/vocabularies/UI

Abstract and concrete types for defining parameters within a selection variant.

```APIDOC
## ParameterAbstract

### Description
Key property of a parameter entity type.

### Derived Types:
  * Parameter
  * IntervalParameter

## Parameter

### Description
Single-valued parameter.

### Properties

- **PropertyName** (PropertyPath) - Path to a key property of a parameter entity type
- **PropertyValue** (PrimitiveType) - Value for the key property

## IntervalParameter

### Description
Interval parameter formed with a 'from' and a 'to' property.

### Properties

- **PropertyNameFrom** (PropertyPath) - Path to the 'from' property of a parameter entity type
- **PropertyValueFrom** (PrimitiveType) - Value for the 'from' property
- **PropertyNameTo** (PropertyPath) - Path to the 'to' property of a parameter entity type
- **PropertyValueTo** (PrimitiveType) - Value for the 'to' property
```

--------------------------------

### PresentationVariantType

Source: https://sap.github.io/odata-vocabularies/vocabularies/UI

Defines how a collection of entities should be presented, including sorting, grouping, and visualization options.

```APIDOC
## PresentationVariantType

### Description
Defines how a collection of entities should be presented, including sorting, grouping, and visualization options.

### Properties

- **ID** (String?) - Optional identifier to reference this variant from an external context
- **Text** (String?) - Name of the presentation variant
- **MaxItems** (Int32?) - Maximum number of items that should be included in the result
- **SortOrder** ([SortOrderType]) - Collection can be provided inline or as a reference to a Common.SortOrder annotation via Path
- **GroupBy** ([PropertyPath]) - Sequence of groupable properties p1, p2, ... defining how the result is composed of instances representing groups, one for each combination of value properties in the queried collection.
- **TotalBy** ([PropertyPath]) - Sub-sequence q1, q2, ... of properties p1, p2, ... specified in GroupBy. With this, additional levels of aggregation are requested.
- **Total** ([PropertyPath]) - Aggregatable properties for which aggregated values should be provided for the additional aggregation levels specified in TotalBy.
- **DynamicTotal** ([AnnotationPath]) - Dynamic properties introduced by annotations for which aggregated values should be provided for the additional aggregation levels specified in TotalBy.
- **IncludeGrandTotal** (Boolean) - Result should include a grand total for the properties specified in Total.
- **InitialExpansionLevel** (Int32) - Level up to which the hierarchy defined for the queried collection should be expanded initially.
- **Visualizations** ([AnnotationPath]) - Lists available visualization types. Currently supported types are `UI.LineItem`, `UI.Chart`, and `UI.DataPoint`.
- **RecursiveHierarchyQualifier _(Experimental)_** (HierarchyQualifier?) - Qualifier of the recursive hierarchy that should be applied to the Visualization.
- **RequestAtLeast** ([PropertyPath]) - Properties that should always be included in the result of the queried collection.
- **SelectionFields _(Experimental)_** ([PropertyPath]) - Properties that should be presented for filtering a collection of entities.
```

--------------------------------

### CreatedAt Annotation

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

The `CreatedAt` annotation represents the creation timestamp of a resource.

```APIDOC
## CreatedAt

### Description
Creation timestamp.

### Method
N/A (Annotation)

### Endpoint
N/A (Annotation)

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **value** (DateTimeOffset?) - The creation timestamp.

#### Response Example
```json
{
  "value": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### ApplyMultiUnitBehaviorForSortingAndFiltering Annotation

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

The `ApplyMultiUnitBehaviorForSortingAndFiltering` annotation indicates that sorting and filtering of amounts in multiple currencies needs special consideration. A TODO is present to add a link to UX documentation.

```APIDOC
## ApplyMultiUnitBehaviorForSortingAndFiltering

### Description
Sorting and filtering of amounts in multiple currencies needs special consideration. TODO: add link to UX documentation on https://experience.sap.com/fiori-design/.

### Method
N/A (Annotation)

### Endpoint
N/A (Annotation)

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **value** (Tag) - Indicates special handling is required for multi-unit sorting/filtering.

#### Response Example
```json
{
  "value": "true"
}
```
```

--------------------------------

### Criticality and CriticalityCalculation Annotations

Source: https://sap.github.io/odata-vocabularies/vocabularies/UI

Demonstrates the use of Criticality and CriticalityCalculation annotations to define the criticality of an entity or property. Criticality uses a predefined type, while CriticalityCalculation allows for client-defined parameters.

```odata
@UI.Criticality : #High
Status : Edm.String

```

```odata
@UI.CriticalityCalculation : {
  Criticality : #High,
  Value : Status,
  ValueFormat : '@
}
Status : Edm.String

```

--------------------------------

### SAP OData Annotations: Quantity and Precision in Metadata

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

This snippet demonstrates how to use `sap:unit` and `sap:precision` attributes in an OData metadata document to define properties related to quantities and their display precision. It shows how to link a numeric property to its unit of measure and how to specify decimal places for display.

```xml
<Property Name="OrderedQuantity" Type="Edm.Int16" sap:unit="OrderedUnit" />
<Property Name="OrderedUnit" Type="Edm.String" sap:semantics="unit-of-measure" />
<Property Name ="Price" Type ="Edm.Decimal" Precision="10" Scale ="3" sap:unit ="Currency" sap:precision="DisplayScale" />
<Property Name="DisplayScale" Type ="Edm.Byte" />
<Property Name="Currency" Type ="Edm.String" sap:semantics="currency-code" sap:text="CurrencyText" />
<Property Name="CurrencyText" Type="Edm.String" />
```

--------------------------------

### SAP OData Annotations: Quantity and Precision in Atom Entry

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

This snippet shows the representation of quantity and precision data within an Atom entry for an OData service. It corresponds to the metadata definitions, illustrating how the actual data values for ordered quantity, unit, price, and currency are provided.

```xml
<d:OrderedQuantity>50</d:OrderedQuantity>
<d:OrderedUnit>KGM</d:OrderedUnit>
<d:Price>86.9</d:Price>
<d:DisplayScale>2</d:DisplayScale>
<d:Currency>EUR</d:Currency>
<d:CurrencyText>Euro</d:CurrencyText>
```

--------------------------------

### ErrorResolutionType

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

Offers guidance for resolving errors, including analysis hints and additional notes.

```APIDOC
## ErrorResolutionType

### Description
Offers guidance for resolving errors, including analysis hints and additional notes.

### Properties
- **Analysis** (String?): Short hint on how to analyze this error.
- **Note** (String?): Note for error resolution.
- **AdditionalNote** (String?): Additional note for error resolution.
```

--------------------------------

### Define Address Via Navigation Path Type (XML)

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

This snippet defines the 'AddressViaNavigationPath' annotation, indicating that a service prefers resource paths with navigation properties. It is useful for services that don't restrict paths via Capabilities or RequiresExplicitBinding.

```xml
<Annotation Term="Org.OData.Core.V1.AddressViaNavigationPath">
  <PropertyValue Property="Message" String="Service prefers requests to use a resource path with navigation properties"/>
  <PropertyValue Property="Documentation" String="Use this tag on services that do not restrict requests to certain resource paths via Capabilities or Core.RequiresExplicitBinding annotations, but that prefer requests with a resource path that contains the navigation properties reflecting the UI structure."/>
</Annotation>
```

--------------------------------

### Define WebSocket Base URL Type (XML)

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

This snippet defines the 'WebSocketBaseURL' annotation, specifying the base URL for WebSocket connections. This annotation must be unqualified.

```xml
<Annotation Term="Org.OData.Core.V1.WebSocketBaseURL">
  <PropertyValue Property="Message" String="Base URL for WebSocket connections"/>
  <PropertyValue Property="IsUnqualified" Bool="true"/>
</Annotation>
```

--------------------------------

### Type Definitions for Contact Information and Addresses

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

This section details the possible type values for different contact information and address properties.

```APIDOC
## Type Definitions for Contact Information and Addresses

### Phone Number Types

- `text`: Indicates a telephone number supporting text messages (SMS).
- `voice`: Indicates a voice telephone number.
- `fax`: Indicates a facsimile telephone number.
- `cell`: Indicates a cellular telephone number.
- `video`: Indicates a video conferencing telephone number.
- `pager`: Indicates a paging device telephone number.
- `textphone`: Indicates a telecommunication device for people with hearing or speech difficulties.

### Email Address Types

- `home`: Indicates an email address associated with a residence.
- `work`: Indicates an email address associated with a place of work.
- `pref`: Indicates a preferred-use email address.

### URL and Address Types

- `home`: Indicates an address associated with a residence.
- `work`: Indicates an address associated with a place of work.
- `org`: Indicates an address associated with the organization.
- `pref`: Indicates a preferred address.
- `other`: Indicates some other address.

These type values can be specified as a value list (e.g., `type=work,pref`).
```

--------------------------------

### mediaUploadLink Function Import

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

Describes the `mediaUploadLink` function import, which provides a URL for uploading new media content to a Document Management Service. This URL allows uploads without directly modifying a stream property or media resource, typically using HTTP POST with multipart/form-data.

```APIDOC
## POST /mediaUploadLink

### Description
URL for uploading new media content to a Document Management Service. In contrast to the `@odata.mediaEditLink` this URL allows to upload new media content without directly changing a stream property or media resource. The upload request typically uses HTTP POST with `Content-Type: multipart/form-data` following RFC 7578. The upload request must contain one multipart representing the content of the file. The `name` parameter in the `Content-Disposition` header (as described in RFC 7578) is irrelevant, but the `filename` parameter is expected. If the request succeeds the response will contain a JSON body of `Content-Type: application/json` with a JSON property `readLink`. The newly uploaded media resource can be linked to the stream property by changing the `@odata.mediaReadLink` to the value of this `readLink` in a subsequent PATCH request to the OData entity.

### Method
POST

### Endpoint
/mediaUploadLink

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **file** (File) - Required - The media content to upload.

### Request Example
(This would typically involve a multipart/form-data request, not a JSON body. The example below is a conceptual representation.)
```
--boundary
Content-Disposition: form-data; filename="example.jpg"
Content-Type: image/jpeg

[binary image data]
--boundary--
```

### Response
#### Success Response (200)
- **readLink** (URL) - The URL to link the uploaded media resource.

#### Response Example
```json
{
  "readLink": "/media/abc-123.jpg"
}
```
```

--------------------------------

### Define Primitive Term with Constant Annotation Value (CDS)

Source: https://sap.github.io/odata-vocabularies/docs/annotation-cheat-sheet-cap

Demonstrates how to define an EDM primitive term in CDS and assign a constant string value to it as an annotation. This is useful for static configuration or metadata definition.

```cds
<Term Name="StringTerm" Type="Edm.String" />

@Vocab.StringTerm: 'annotation value'
```

--------------------------------

### URL and Address Types for OData

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

Defines the type values for URLs and address constituents, indicating whether they are related to home, work, an organization, or are the preferred address.

```odata
<Annotation Term="Common.IsAddress" Bool="true" />
```

--------------------------------

### Define Primitive Term with Dynamic Annotation Value (CDS)

Source: https://sap.github.io/odata-vocabularies/docs/annotation-cheat-sheet-cap

Illustrates defining an EDM primitive term in CDS and associating it with a dynamic value using a CDS path expression. This allows annotations to reference properties from the entity data.

```cds
<Term Name="StringTerm" Type="Edm.String" />

@Vocab.StringTerm: Some.StringProperty
```

--------------------------------

### DateTimeStyle Annotation Usage

Source: https://sap.github.io/odata-vocabularies/vocabularies/UI

Illustrates the usage of the DateTimeStyle annotation to control the display format of temporal values (Date, TimeOfDay, DateTimeOffset) in the UI. It shows different allowed values for styling.

```odata
@Core.Description : 'Display date and time in short format'
@Common.FormattedLocation : 'DateTimeStyle.short'
MyDateTimeProperty : Edm.DateTimeOffset

```

```odata
@Core.Description : 'Display date and time in medium format'
@Common.FormattedLocation : 'DateTimeStyle.medium'
MyDateTimeProperty : Edm.DateTimeOffset

```

```odata
@Core.Description : 'Display date and time in long format'
@Common.FormattedLocation : 'DateTimeStyle.long'
MyDateTimeProperty : Edm.DateTimeOffset

```

```odata
@Core.Description : 'Display date and time in full format'
@Common.FormattedLocation : 'DateTimeStyle.full'
MyDateTimeProperty : Edm.DateTimeOffset

```

--------------------------------

### CreateHidden, UpdateHidden, DeleteHidden Annotations

Source: https://sap.github.io/odata-vocabularies/vocabularies/UI

Illustrates the use of CreateHidden, UpdateHidden, and DeleteHidden annotations to dynamically control the visibility of CRUD operations (Create, Edit/Save, Delete) for EntitySets. The annotation value is typically a path to a property.

```odata
EntitySet MyEntitySet @Common.CreateHidden : 'HasWritePermission'
{
  // ... properties ...
}

```

```odata
EntitySet MyEntitySet @Common.UpdateHidden : 'IsEditable'
{
  // ... properties ...
}

```

```odata
EntitySet MyEntitySet @Common.DeleteHidden : 'CanBeDeleted'
{
  // ... properties ...
}

```

--------------------------------

### Define WebSocket Channel Type (XML)

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

This snippet defines the 'WebSocketChannel' annotation for WebSocket connections. It includes details about the protocol, message format, and supported qualifiers like 'sideEffects'.

```xml
<Annotation Term="Org.OData.Core.V1.WebSocketChannel">
  <PropertyValue Property="Message" String="Channel for WebSocket connections"/>
  <PropertyValue Property="Documentation" String="Messages sent over the channel follow the ABAP Push Channel Protocol. To consume a channel, the client opens a web socket connection at the WebSocketBaseURL followed by URL parameters. Supported qualifiers and channel IDs: 'sideEffects' (Notifications about side effects to be triggered by the client)"/>
</Annotation>
```

--------------------------------

### OriginalProtocolVersion Annotation

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

The `OriginalProtocolVersion` annotation specifies the original protocol version of a converted (V4) CSDL document. Allowed values are '2.0' and '3.0'.

```APIDOC
## OriginalProtocolVersion

### Description
Original protocol version of a converted (V4) CSDL document, allowed values `2.0` and `3.0`.

### Method
N/A (Annotation)

### Endpoint
N/A (Annotation)

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **value** (string) - The original protocol version.

#### Response Example
```json
{
  "value": "3.0"
}
```
```

--------------------------------

### IsCopyAction Annotation for Deep Copy Actions

Source: https://sap.github.io/odata-vocabularies/vocabularies/UI

Demonstrates the IsCopyAction annotation, which signifies that a DataFieldForAction references an action that performs a deep copy of an entity instance. It outlines the requirements for the referenced action and its response.

```odata
Action CopyEntity @Common.IsCopyAction
  // ... action definition ...

Entity MyEntity @(Common.IsCopyAction : ActionImport.CopyEntity)
{
  // ... entity properties ...
}

```

--------------------------------

### DirectEdit Vocabulary - SideEffects

Source: https://sap.github.io/odata-vocabularies/vocabularies/DirectEdit

Defines the SideEffects term, used to determine side effects of client-side data modification. This is an experimental feature.

```APIDOC
## DirectEdit Vocabulary - SideEffects

### Description
Determine side effects of client-side data modification.

### Term
SideEffects

### Namespace
com.sap.vocabularies.DirectEdit.v1

### Type
SideEffectsType

### Status
Experimental
```

--------------------------------

### Define Nested Structures and Collections Term (CDS)

Source: https://sap.github.io/odata-vocabularies/docs/annotation-cheat-sheet-cap

Illustrates how to define an EDM term with nested complex types and collections, and how to structure the annotation value using nested JSON objects and arrays.

```cds
<Term Name="NestedTerm" Type="Collection(Vocab.YetAnotherComplex)" />

<ComplexType Name="YetAnotherComplex">
  <Property Name="StructuredField" Type="Vocab.Complex" />
  <Property Name="CollectionField" Type="Collection(Vocab.AnotherComplex)" />
</ComplexType>

<ComplexType Name="Complex">
  <Property Name="IntegerField" Type="Edm.Int32" />
</ComplexType>

<ComplexType Name="AnotherComplex">
  <Property Name="DateField" Type="Edm.Date" />
  <Property Name="TimeField" Type="Edm.TimeOfDay" DefaultValue="00:00:00" />
</ComplexType>

@Vocab.NestedTerm: {
  StructuredField: {
    IntegerField: 42
  },
  CollectionField: [
    {
      DateField: '2020-06-30',
      TimeField: '16:55:03'
    }
  ]
}
```

--------------------------------

### Hierarchy Vocabulary Actions

Source: https://sap.github.io/odata-vocabularies/vocabularies/Hierarchy

Details actions for manipulating hierarchical data, including moving nodes and copying sub-hierarchies.

```APIDOC
## OData Hierarchy Vocabulary Actions

### Template_ChangeNextSiblingAction

*   **Description**: Template for actions that move a node among its siblings. Named in `RecursiveHierarchyActions/ChangeNextSiblingAction`.
*   **Method**: POST (Implied by action template)
*   **Endpoint**: (Bound to a node)
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**:
        *   **Node** (EntityType) - Required - The node T to be moved.
        *   **NextSibling** (ComplexType?) - Optional - Key of the node's new next sibling S (null if the node becomes the last sibling).

### Template_CopyAction

*   **Description**: Template for actions that copy a node and its descendants. Named in `RecursiveHierarchyActions/CopyAction`. Copies a node A and its descendants, returning the copy of A. The parent of the copy can be specified via a subsequent PATCH request.
*   **Method**: POST (Implied by action template)
*   **Endpoint**: (Bound to a node)
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**:
        *   **Node** (EntityType) - Required - The node to be copied.
*   **Response Example (after subsequent PATCH)**:
    ```json
    {
      "requests": [
        {
          "id": "1",
          "method": "post",
          "url": "HierarchyDirectory(1)/Nodes('A')/CopyAction"
        },
        {
          "id": "2",
          "dependsOn": ["1"],
          "method": "patch",
          "url": "$1",
          "body": {
            "Superordinate@odata.bind": "Nodes('B')"
          }
        }
      ]
    }
    ```
```

--------------------------------

### SelectionVariantType

Source: https://sap.github.io/odata-vocabularies/vocabularies/UI

Defines criteria for selecting a subset of entities, including filters and select options.

```APIDOC
## SelectionVariantType

### Description
Defines criteria for selecting a subset of entities, including filters and select options.

### Properties

- **ID** (String?) - May contain identifier to reference this instance from an external context
- **Text** (String?) - Name of the selection variant
- **Parameters** ([ParameterAbstract]) - Parameters of the selection variant
- **FilterExpression** (String?) - Filter string for query part of URL, without `$filter=`
- **SelectOptions** ([SelectOptionType]) - ABAP Select Options Pattern
```

--------------------------------

### DirectEdit Vocabulary - SideEffectsType

Source: https://sap.github.io/odata-vocabularies/vocabularies/DirectEdit

Defines the SideEffectsType complex type, which specifies how to calculate side effects after a property change.

```APIDOC
## DirectEdit Vocabulary - SideEffectsType

### Description
After a change to a property whose path is contained in `Triggers`, the client should pass the entity with the changed property to the `CalculationFunction` and receive the entity with all changes that happen as side effects of the given change.

### Type
SideEffectsType

### Namespace
com.sap.vocabularies.DirectEdit.v1

### Status
Experimental

### Properties
#### Triggers
- **Type**: [String]
- **Description**: List of paths to the properties whose changes should trigger the side effects calculation.

#### CalculationFunction
- **Type**: QualifiedName
- **Description**: The operation calculating the side effects. While non-changing for the service, this technically is an action bound to the entity set so that the parameters can be sent in the POST request body. The action has the following non-binding parameters:
  * `Qualifier` (Core.SimpleIdentifier or cast-compatible): the qualifier of the `SideEffects` annotation
  * `Trigger` (Edm.String): the trigger of the side-effects determination, see `Triggers` property
  * `Data` (entity type or compatible complex type): the entity with the changed property.

**Return Type**: The return type of the action also needs to be either the entity type of the annotated entity set or structure-compatible with it, it can be the same type as for `Data`.
```

--------------------------------

### Define Collection Term with Array Annotation Value (CDS)

Source: https://sap.github.io/odata-vocabularies/docs/annotation-cheat-sheet-cap

Shows how to define an EDM term that expects a collection of primitive types (e.g., Decimal) and how to provide its annotation value as a JSON array.

```cds
<Term Name="CollectionTerm" Type="Collection(Edm.Decimal)" />

@Vocab.CollectionTerm: [ 2.78, 3.14 ]
```

--------------------------------

### Hierarchy Vocabulary Functions

Source: https://sap.github.io/odata-vocabularies/vocabularies/Hierarchy

Provides functions for retrieving hierarchical data, such as the TopLevels function for fetching specific levels of a hierarchy.

```APIDOC
## OData Hierarchy Vocabulary Functions

### TopLevels

*   **Description**: Returns the first n levels of a hierarchical collection in preorder with individual nodes expanded or collapsed. Can be used as an `$apply` transformation.
*   **Method**: GET (Implied by function usage in query)
*   **Endpoint**: (Applied to a collection)
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**:
        *   **$apply**: (String) - Required - Specifies the `TopLevels` transformation.
    *   **Binding Parameter**:
        *   **HierarchyNodes** ([EntityType]) - Required - A collection, given through a `$root` expression.
*   **Function Parameters (within $apply)**:
    *   **HierarchyQualifier** (HierarchyQualifier) - Required
    *   **NodeProperty** (String) - Required - Property path to the node identifier, evaluated relative to the binding parameter.
    *   **_Levels_** (Int64) - Optional - The number n of levels to be output, absent means all levels.
    *   **_Show_** ([String]) - Optional - Identifiers of nodes to be shown.
    *   **_ExpandLevels_** ([TopLevelsExpandType]) - Optional - Nodes to be expanded.
*   **Response**: ([EntityType]) - The limited hierarchy, sorted in preorder.
```

--------------------------------

### Element: edm:NavigationProperty Attributes

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

Details attributes for `edm:NavigationProperty`, specifically `creatable` and `creatable-path`, which control the creation of related entities.

```APIDOC
## Element `edm:NavigationProperty`

### Attributes for Navigation Properties

- **creatable**: `true` | New related entities can be created.
- **creatable-path**: `-` | Related entities can be created or not depending on the state of the source entity. The value of this attribute is a path expression that identifies a Boolean property in the context of the source entity type. The value of this property indicates whether related entities can be created or not. See section Combined Meaning for combined meaning of `creatable` and `creatable-path`.
- **filterable**: `true` | Can be used as a path segment for properties in `$filter` system query option.
```

--------------------------------

### Attribute: sap:parameter

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

Describes the `sap:parameter` attribute, indicating whether a property represents a mandatory or optional parameter.

```APIDOC
## Attribute `sap:parameter`

A property can be annotated with this attribute if it represents a parameter. The attribute can take the following values:

- **mandatory**: A value must be supplied for this parameter.
- **optional**: A value for this parameter can be left out by specifying an empty string (applicable only for parameter properties of type `Edm.String`). For parameters of other types, the default value conveyed in the metadata should be assigned if the parameter shall be omitted.
```

--------------------------------

### SAPObjectNodeTypeType

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

Provides information about an SAP Object Node Type.

```APIDOC
## SAPObjectNodeTypeType

### Description
Information about an SAP Object Node Type.

### Properties
- **Name** (String): The name of the SAP Object Node Type.
```

--------------------------------

### SAP Parameter Annotation

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

Indicates whether a property represents a parameter and its requirement. Parameters can be 'mandatory' or 'optional'.

```xml
<Property Name="CustomerName" Type="Edm.String" sap:parameter="mandatory" />
<Property Name="StartDate" Type="Edm.DateTime" sap:parameter="optional" />
```

--------------------------------

### Define Text Format Enum (XML)

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

This snippet defines the 'TextFormatType' enumeration, specifying different text formats for OData services. It includes 'plain' (0) for plain text with line breaks and 'html' (1) for text with valid HTML markup.

```xml
<EnumType Name="TextFormatType">
  <Member Name="plain">
    <PropertyValue Name="Value" Int="0"/>
    <Annotation Term="Org.OData.Core.V1.Description" String="Plain text, line breaks represented as the character 0x0A"/>
  </Member>
  <Member Name="html">
    <PropertyValue Name="Value" Int="1"/>
    <Annotation Term="Org.OData.Core.V1.Description" String="Plain text with markup that can validly appear directly within an HTML DIV element"/>
  </Member>
</EnumType>
```

--------------------------------

### Value Constraint for Function Import Parameters in OData

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

Illustrates the `sap:value-constraint` element used with function imports to define dependencies between parameters and entity set key properties, similar to referential constraints. It specifies an entity set and links function import parameters to its key properties.

```xml
<sap:value-constraint set="Regions">
     <sap: parameter-ref name="Country" />
     <sap:parameter-ref name="Region" />
</sap:value-constraint>
```

--------------------------------

### Define Collection of Structures Term (CDS)

Source: https://sap.github.io/odata-vocabularies/docs/annotation-cheat-sheet-cap

Demonstrates defining an EDM term typed as a collection of a structured type and providing its annotation value as an array of JSON objects. Properties can be omitted if nullable or have defaults.

```cds
<Term Name="StructuredCollectionTerm" Type="Collection(Vocab.AnotherComplex)" />

<ComplexType Name="AnotherComplex">
  <Property Name="DateField" Type="Edm.Date" />
  <Property Name="TimeField" Type="Edm.TimeOfDay" DefaultValue="00:00:00" />
</ComplexType>

@Vocab.StructuredCollectionTerm: [
  {
    DateField: '2020-06-30',
    TimeField: '16:55:03'
  },
  {
    DateField: '2020-07-01'
  },
  {
    TimeField: '23:59:59'
  }
]
```

--------------------------------

### Define Semantic Object Mapping Abstract Type (XML)

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

This snippet defines the abstract 'SemanticObjectMappingAbstract' type, used for mapping properties of a Semantic Object to properties of an entity type or a constant value. It serves as a base for derived types.

```xml
<ComplexType Name="SemanticObjectMappingAbstract" Abstract="true">
  <Property Name="SemanticObjectProperty" Type="Edm.String"/>
  <Annotation Term="Org.OData.Core.V1.Description" String="Maps a property of the Semantic Object to a property of the annotated entity type or a sibling property of the annotated property or a constant value"/>
</ComplexType>
```

--------------------------------

### IntervalType

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

Defines an interval with specified lower and upper boundaries, including whether the boundaries are included.

```APIDOC
## IntervalType

### Description
Defines an interval with specified lower and upper boundaries, including whether the boundaries are included.

### Properties
- **Label** (String?): A short, human-readable text suitable for labels and captions in UIs.
- **LowerBoundary** (PropertyPath): Property holding the lower interval boundary.
- **LowerBoundaryIncluded** (Boolean): Indicates if the lower boundary value is included in the interval.
- **UpperBoundary** (PropertyPath): Property holding the upper interval boundary.
- **UpperBoundaryIncluded** (Boolean): Indicates if the upper boundary value is included in the interval.
```

--------------------------------

### Define Primitive Property Path Type (XML)

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

This snippet defines the 'PrimitivePropertyPath' annotation, used for terms or properties whose type is a collection of Edm.PropertyPath. It ensures that the resolved path points to a primitive structural property.

```xml
<Annotation Term="Org.OData.Core.V1.PrimitivePropertyPath">
  <PropertyValue Property="Message" String="A term or term property with this tag whose type is (a collection of) Edm.PropertyPath MUST resolve to a primitive structural property"/>
</Annotation>
```

--------------------------------

### Define Referential Constraint Type (XML)

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

This snippet defines the 'ReferentialConstraint' annotation, used for referential constraints without a nullability requirement, as specified in OData CSDL XML.

```xml
<Annotation Term="Org.OData.Core.V1.ReferentialConstraint">
  <PropertyValue Property="Message" String="Referential constraints without nullability requirement"/>
  <PropertyValue Property="Documentation" String="Referential constraints without nullability requirement"/>
</Annotation>
```

--------------------------------

### ChangedAt Annotation

Source: https://sap.github.io/odata-vocabularies/vocabularies/Common

The `ChangedAt` annotation represents the last modification timestamp of a resource.

```APIDOC
## ChangedAt

### Description
Last modification timestamp.

### Method
N/A (Annotation)

### Endpoint
N/A (Annotation)

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **value** (DateTimeOffset?) - The last modification timestamp.

#### Response Example
```json
{
  "value": "2023-10-27T11:30:00Z"
}
```
```

--------------------------------

### Define Structured Term with Object Annotation Value (CDS)

Source: https://sap.github.io/odata-vocabularies/docs/annotation-cheat-sheet-cap

Explains how to define an EDM term with a structured type and represent its annotation value as a JSON object, mapping properties to their respective values.

```cds
<Term Name="StructuredTerm" Type="Vocab.Complex" />

<ComplexType Name="Complex">
  <Property Name="IntegerField" Type="Edm.Int32" />
</ComplexType>

@Vocab.StructuredTerm: {
  IntegerField: 42
}
```

--------------------------------

### Email Address Types for OData

Source: https://sap.github.io/odata-vocabularies/docs/v2-annotations

Specifies the different types of email addresses that can be associated with a contact. These types indicate whether an email address is for home, work, or is the preferred contact.

```odata
<Annotation Term="Common.IsEmailAddress" Bool="true" />
```
Tokens:
Raw