---
title: Odata
description: Odata protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

OData v4 Protocol Support

Open Data Protocol (OData) v4 is an industry-standard protocol for building

and consuming RESTful APIs. It provides a uniform way to expose, structure,

query, and manipulate data.

## Overview

OData v4 provides standardized URL conventions for querying data including:

- $select: Choose which fields to return

- $filter: Filter results with complex expressions

- $orderby: Sort results

- $top/$skip: Pagination

- $expand: Include related entities

- $count: Get total count

## Use Cases

1. **Enterprise Integration**

- Integrate with Microsoft Dynamics 365

- Connect to SharePoint Online

- SAP OData services

2. **API Standardization**

- Provide consistent query interface

- Standard pagination and filtering

- Industry-recognized protocol

3. **External Data Sources**

- Connect to OData-compliant systems

- Federated queries

- Data virtualization

@see https://www.odata.org/documentation/

@see https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html

@example OData Query

```

GET /api/odata/customers?

$select=name,email&

$filter=country eq 'US' and revenue gt 100000&

$orderby=revenue desc&

$top=10&

$skip=20&

$expand=orders&

$count=true

```

@example Programmatic Use

```typescript

const query: ODataQuery = \{

select: ['name', 'email'],

filter: "country eq 'US' and revenue gt 100000",

orderby: 'revenue desc',

top: 10,

skip: 20,

expand: ['orders'],

count: true

\}

```

<Callout type="info">
**Source:** `packages/spec/src/api/odata.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { ODataConfig, ODataError, ODataFilterFunction, ODataFilterOperator, ODataMetadata, ODataQuery, ODataResponse } from '@objectstack/spec/api';
import type { ODataConfig, ODataError, ODataFilterFunction, ODataFilterOperator, ODataMetadata, ODataQuery, ODataResponse } from '@objectstack/spec/api';

// Validate data
const result = ODataConfig.parse(data);
```

---

## ODataConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable OData API |
| **path** | `string` | ✅ | OData endpoint path |
| **metadata** | `Object` | optional | OData metadata configuration |


---

## ODataError

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **error** | `Object` | ✅ |  |


---

## ODataFilterFunction

### Allowed Values

* `contains`
* `startswith`
* `endswith`
* `length`
* `indexof`
* `substring`
* `tolower`
* `toupper`
* `trim`
* `concat`
* `year`
* `month`
* `day`
* `hour`
* `minute`
* `second`
* `date`
* `time`
* `now`
* `maxdatetime`
* `mindatetime`
* `round`
* `floor`
* `ceiling`
* `cast`
* `isof`
* `any`
* `all`


---

## ODataFilterOperator

### Allowed Values

* `eq`
* `ne`
* `lt`
* `le`
* `gt`
* `ge`
* `and`
* `or`
* `not`
* `(`
* `)`
* `in`
* `has`


---

## ODataMetadata

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **namespace** | `string` | ✅ | Service namespace |
| **entityTypes** | `Object[]` | ✅ | Entity types |
| **entitySets** | `Object[]` | ✅ | Entity sets |


---

## ODataQuery

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **$select** | `string \| string[]` | optional | Fields to select |
| **$filter** | `string` | optional | Filter expression (OData filter syntax) |
| **$orderby** | `string \| string[]` | optional | Sort order |
| **$top** | `integer` | optional | Max results to return |
| **$skip** | `integer` | optional | Results to skip |
| **$expand** | `string \| string[]` | optional | Navigation properties to expand (lookup/master_detail fields) |
| **$count** | `boolean` | optional | Include total count |
| **$search** | `string` | optional | Search expression |
| **$format** | `Enum<'json' \| 'xml' \| 'atom'>` | optional | Response format |
| **$apply** | `string` | optional | Aggregation expression |


---

## ODataResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **@odata.context** | `string` | optional | Metadata context URL |
| **@odata.count** | `integer` | optional | Total results count |
| **@odata.nextLink** | `string` | optional | Next page URL |
| **value** | `Record<string, any>[]` | ✅ | Results array |


---

