---
schema_version: "1"
id: 92e7e6a9197866cb99af07f8ab3c2546abeb92fb3d5a57354e96a30bdc970c1f
title: APIkit for OData v2 Module Reference
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/apikit/latest/apikit-odatav2-extension-reference.md
canonical_url: https://docs.mulesoft.com/apikit/latest/apikit-odatav2-extension-reference
source_site: docs.mulesoft.com
content_type: documentation
content_hash: badc9151bc4bb03831e02667cd8b7074c52173a004dfe70f0e03ea7c544229d0
description: MuleSoft Documentation Site
release: 4.x
latest: true
---
---
product: APIkit
version: 4.x
is-latest-version: true
---

# APIkit for OData v2 Module Reference

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Integrate APIkit for OData v2 with APIkit for REST by declaring the Maven dependencies, namespaces,
and XML schema locations in this topic. Customize generated EntitySet names and router behavior from
your RAML types when you need endpoints that differ from default pluralization.

## Dependency Information

Declare the APIkit for OData v2 extension with the APIkit for REST module dependency:

<dependency>
    <groupId>org.mule.modules</groupId>
    <artifactId>mule-module-apikit-odata</artifactId>
    <version>2.2.0</version> **(1)**
    <classifier>mule-plugin</classifier>
</dependency>
<dependency>
    <groupId>org.mule.modules</groupId>
    <artifactId>mule-apikit-module</artifactId>
    <version>1.8.3</version> **(1)**
    <classifier>mule-plugin</classifier>
</dependency>

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>The tooling determines the appropriate version of each dependency when scaffolding to guarantee compatibility. Manually setting dependency versions produces issues. See the <a href="https://docs.mulesoft.com/release-notes/apikit/apikit-release-notes">APIkit release notes</a> before upgrading each component to the latest version.</td></tr></tbody></table>

> [!NOTE] Update the Anypoint Studio plugin to enable the tooling to determine the appropriate
> dependency combination.

## Namespace and Schema

xmlns:apikit="http://www.mulesoft.org/schema/mule/mule-apikit"
xsi:schemaLocation="http://www.mulesoft.org/schema/mule/mule-apikit
http://www.mulesoft.org/schema/mule/mule-apikit/current/mule-apikit.xsd"

## Customizing EntitySet Names

APIkit for OData v2 pluralizes entity type names automatically to create **EntitySet** endpoints
(for example, `Person` becomes `Persons`). For APIkit for OData 2.3.5 and later, override this
behavior by using these annotations in your RAML type definitions:

- **(odata.entitySet)**

- **(odata.entitySetEnabled)**

With these annotations, you control the **EntitySet** name exposed in metadata and in OData API URLs
and align endpoints with your domain (for example, change `Person` to `People`).

### Annotation Reference

Apply these annotations at the entity type level in your RAML library (for example, in
`odataLibrary.raml`):

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Annotation</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>(odata.entitySet)</code></p></div></div></td><td><div><div><p>String</p></div></div></td><td><div><div><p>Custom name for the entity set. Used only if <code>(odata.entitySetEnabled)</code> is <code>true</code> and the value is non-empty.</p></div></div></td></tr><tr><td><div><div><p><code>(odata.entitySetEnabled)</code></p></div></div></td><td><div><div><p>Boolean</p></div></div></td><td><div><div><p>If <code>true</code>, uses the custom name from <code>(odata.entitySet)</code>. If <code>false</code> or omitted, default pluralization is used for backward compatibility.</p></div></div></td></tr></tbody></table>

### Feature Flag: Enabling Custom EntitySet Names

The `(odata.entitySet)` and `(odata.entitySetEnabled)` entity annotations affect metadata generation
and OData API behavior as follows:

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Case</th><th><code>(odata.entitySetEnabled)</code></th><th><code>(odata.entitySet)</code></th><th>Effective EntitySet Name</th><th>Metadata and OData API Behavior</th></tr></thead><tbody><tr><td><div><div><p>1</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Present</p></div></div></td><td><div><div><p>Default pluralization (based on entity type)</p></div></div></td><td><div><div><p>Default EntitySet</p></div></div></td></tr><tr><td><div><div><p>2</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Not present</p></div></div></td><td><div><div><p>Default pluralization (based on entity type)</p></div></div></td><td><div><div><p>Default EntitySet</p></div></div></td></tr><tr><td><div><div><p>3</p></div></div></td><td><div><div><p>Not defined or present</p></div></div></td><td><div><div><p>Present</p></div></div></td><td><div><div><p>Default pluralization (based on entity type)</p></div></div></td><td><div><div><p>Default EntitySet</p></div></div></td></tr><tr><td><div><div><p>4</p></div></div></td><td><div><div><p>Not defined or present</p></div></div></td><td><div><div><p>Not present</p></div></div></td><td><div><div><p>Default pluralization (based on entity type)</p></div></div></td><td><div><div><p>Default EntitySet</p></div></div></td></tr><tr><td><div><div><p>5</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Present (non-empty)</p></div></div></td><td><div><div><p>Custom name from annotation</p></div></div></td><td><div><div><p>Custom EntitySet; metadata and APIs use the custom name</p></div></div></td></tr><tr><td><div><div><p>6</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Not present or empty</p></div></div></td><td><div><div><p>Default pluralization (based on entity type)</p></div></div></td><td><div><div><p>Default EntitySet</p></div></div></td></tr></tbody></table>

> [!NOTE] Custom names apply if `entitySetEnabled` is `true` and `entitySet` is provided with a
> non-empty value. If not, APIkit for OData v2 uses default pluralization.

### Example: Custom EntitySet Name in RAML

This example defines a `Person` entity and exposes it as the `EntitySet` `People`:

```raml
#%RAML 1.0 Library
uses:
  odata: libraries/odataLibrary.raml

types:
  Person:
    (odata.remote): Person
    (odata.entitySet): People
    (odata.entitySetEnabled): true
    properties:
      ID:
        type: integer
        required: true
        (odata.key): true
      Name:
        type: string
        required: true
      Price:
        type: number
```

The `EntitySet` appears as `People` in `$metadata` and in OData API URLs (for example,
`/api/odata.svc/People`) instead of the default `Persons`.

### Backward Compatibility

Existing flows and APIs don’t change unless you explicitly enable the feature. APIkit for OData v2
ignores custom `EntitySet` annotations unless `(odata.entitySetEnabled)` is set to `true`. If the
flag is `false` or missing, APIkit for OData v2 always uses default pluralization based on the
entity type, even if `(odata.entitySet)` is present. This ensures full backward compatibility with
existing APIkit for OData v2 applications.

## See Also

- [APIkit for REST Module Reference](https://docs.mulesoft.com/apikit/latest/apikit-4-xml-reference)