Query Adapter schema — API Protocol reference
Defines mapping rules between the internal unified query DSL (defined in data/query.zod.ts) and external API protocol formats: REST and OData.
API Query DSL Adapter Protocol
Defines mapping rules between the internal unified query DSL
(defined in data/query.zod.ts) and external API protocol formats:
REST and OData.
This enables ObjectStack to expose a single internal query representation
while supporting multiple API standards for external consumers.
See also: data/query.zod.ts - Unified internal query DSL
See also: api/rest-server.zod.ts - REST API configuration
See also: api/odata.zod.ts - OData API configuration
Source: packages/spec/src/api/query-adapter.zod.ts
import { ODataQueryAdapterSchema, OperatorMappingSchema, QueryAdapterConfigSchema, QueryAdapterTargetSchema, RestQueryAdapterSchema } from '@objectstack/spec/api';
import type { ODataQueryAdapter, OperatorMapping, QueryAdapterConfig, QueryAdapterTarget, RestQueryAdapter } from '@objectstack/spec/api';
// Validate data
const result = ODataQueryAdapterSchema.parse(data);
| Property | Type | Required | Description |
|---|
| version | Enum<'v2' | 'v4'> | optional (default: "v4") | OData version |
| usePrefix | boolean | optional (default: true) | Use $ prefix for system query options ($filter vs filter) |
| stringFunctions | Enum<'contains' | 'startswith' | 'endswith' | 'tolower' | 'toupper' | 'trim' | 'concat' | 'substring' | 'length'>[] | optional | Supported OData string functions |
| expand | { enabled?: boolean; maxDepth?: integer } | optional | $expand configuration |
| Property | Type | Required | Description |
|---|
| enabled | boolean | optional (default: true) | Enable $expand support |
| maxDepth | integer | optional (default: 3) | Maximum expand depth |
| Property | Type | Required | Description |
|---|
| operator | string | ✅ | Unified DSL operator |
| rest | string | optional | REST query parameter template |
| odata | string | optional | OData $filter expression template |
| Property | Type | Required | Description |
|---|
| operatorMappings | { operator: string; rest?: string; odata?: string }[] | optional | Custom operator mappings |
| rest | { filterStyle?: Enum<'bracket' | 'dot' | 'flat' | 'rsql'>; pagination?: object; sorting?: object; fieldsParam?: string } | optional | REST query adapter configuration |
| odata | { version?: Enum<'v2' | 'v4'>; usePrefix?: boolean; stringFunctions?: Enum<'contains' | 'startswith' | 'endswith' | 'tolower' | 'toupper' | 'trim' | …>[]; expand?: object } | optional | OData query adapter configuration |
| Property | Type | Required | Description |
|---|
| operator | string | ✅ | Unified DSL operator |
| rest | string | optional | REST query parameter template |
| odata | string | optional | OData $filter expression template |
| Property | Type | Required | Description |
|---|
| filterStyle | Enum<'bracket' | 'dot' | 'flat' | 'rsql'> | optional (default: "bracket") | REST filter parameter encoding style |
| pagination | { limitParam?: string; offsetParam?: string; cursorParam?: string; pageParam?: string } | optional | Pagination parameter name mappings |
| sorting | { param?: string; format?: Enum<'comma' | 'array' | 'pipe'> } | optional | Sort parameter mapping |
| fieldsParam | string | optional (default: "fields") | Field selection parameter name |
| Property | Type | Required | Description |
|---|
| version | Enum<'v2' | 'v4'> | optional (default: "v4") | OData version |
| usePrefix | boolean | optional (default: true) | Use $ prefix for system query options ($filter vs filter) |
| stringFunctions | Enum<'contains' | 'startswith' | 'endswith' | 'tolower' | 'toupper' | 'trim' | …>[] | optional | Supported OData string functions |
| expand | { enabled?: boolean; maxDepth?: integer } | optional | $expand configuration |
| Property | Type | Required | Description |
|---|
| filterStyle | Enum<'bracket' | 'dot' | 'flat' | 'rsql'> | optional (default: "bracket") | REST filter parameter encoding style |
| pagination | { limitParam?: string; offsetParam?: string; cursorParam?: string; pageParam?: string } | optional | Pagination parameter name mappings |
| sorting | { param?: string; format?: Enum<'comma' | 'array' | 'pipe'> } | optional | Sort parameter mapping |
| fieldsParam | string | optional (default: "fields") | Field selection parameter name |
| Property | Type | Required | Description |
|---|
| limitParam | string | optional (default: "limit") | Page size parameter name |
| offsetParam | string | optional (default: "offset") | Offset parameter name |
| cursorParam | string | optional (default: "cursor") | Cursor parameter name |
| pageParam | string | optional (default: "page") | Page number parameter name |
| Property | Type | Required | Description |
|---|
| param | string | optional (default: "sort") | Sort parameter name |
| format | Enum<'comma' | 'array' | 'pipe'> | optional (default: "comma") | Sort parameter encoding format |
ObjectStack