Skip to main content

Schema

Overview​

An OPRA document is a JSON/YAML object that describes a complete API — its metadata, shared data types, linked documents, and API transport definitions.

interface ApiDocument {
  // OPRA specification version. Always "1.0".
  spec: '1.0';

  // Optional URL where this document can be fetched.
  // Example: 'https://api.example.com/opra.json'
  url?: string;

  // Human-readable metadata about the document. → See: Document Info
  // Example: { title: 'Customer API', version: '1.0', description: 'Manages customer records.' }
  info?: DocumentInfo;

  // Named data types shared across the document. → See: Type Definitions
  // Example: { Customer: { kind: 'ComplexType', fields: { ... } } }
  types?: Record<string, DataType>;

  // Linked documents keyed by namespace alias. → See: References
  // Example: { cm: { url: 'https://api.example.com/customer-models/opra.json', info: { ... } } }
  references?: Record<string, DocumentReference>;

  // API transport definition. → See: HTTP API Schema / MQ API Schema / WebSocket API Schema
  // Example: { transport: 'http', name: 'CustomerApi', url: '/api', controllers: { ... } }
  api?: HttpApi | MQApi | WSApi;
}
FieldTypeDescription
specstringOPRA specification version. Always "1.0".
urlstringOptional URL where this document can be fetched.
infoDocumentInfoHuman-readable metadata (title, version, contact…).
typesRecord<string, DataType>Named data types shared across the document.
referencesRecord<string, DocumentReference>Linked documents, keyed by namespace.
apiHttpApi | MQApi | WSApiAPI transport definition.

Document Info​

The info object carries human-readable metadata about the document.

interface DocumentInfo {
  // Display name of the API.
  // Example: 'Customer API'
  title?: string;

  // API version string.
  // Example: '1.0'
  version?: string;

  // Long-form description of the API.
  // Example: 'Manages customer records and orders.'
  description?: string;

  // URL to the terms of service page.
  // Example: 'https://example.com/terms'
  termsOfService?: string;

  // List of contact persons. → See: ContactPerson
  // Example: [{ name: 'API Support', email: 'api@example.com', url: 'https://example.com/support' }]
  contact?: ContactPerson[];

  // License information. → See: LicenseInfo
  // Example: { name: 'MIT', url: 'https://opensource.org/licenses/MIT' }
  license?: LicenseInfo;
}

interface ContactPerson {
  // Full name of the contact person.
  name?: string;

  // Contact email address.
  email?: string;

  // Contact URL.
  url?: string;
}

interface LicenseInfo {
  // License identifier. Required.
  // Example: 'MIT'
  name: string;

  // URL to the full license text.
  // Example: 'https://opensource.org/licenses/MIT'
  url?: string;

  // Inline license text (alternative to url).
  content?: string;
}
FieldTypeDescription
titlestringDisplay name of the API.
versionstringAPI version string.
descriptionstringLong-form description.
termsOfServicestringURL to terms of service.
contactContactPerson[]List of contact persons.
licenseLicenseInfoLicense name and URL.

ContactPerson

FieldTypeDescription
namestringContact person's name.
emailstringContact email address.
urlstringContact URL.

LicenseInfo

FieldTypeDescription
namestringLicense name (e.g. "MIT"). Required.
urlstringURL to the license text.
contentstringInline license text.

Type Definitions​

The types field is a record of named data types. Each entry is keyed by the type name and has a kind field that identifies its category.

// All type definitions share these common fields.
interface DataTypeBase {
  // Type category. Required.
  kind: 'SimpleType' | 'EnumType' | 'ComplexType' | 'ArrayType'
      | 'MappedType' | 'MixinType' | 'UnionType';

  // Human-readable description of the type.
  // Example: 'A postal address with city and country.'
  description?: string;

  // When true, this type cannot be used directly in fields — only extended.
  abstract?: boolean;

  // Example values shown in schema documentation. → See: DataTypeExample
  // Example: [{ value: 'john@example.com', description: 'Standard email' }]
  examples?: DataTypeExample[];
}

interface DataTypeExample {
  // The example value.
  value?: any;

  // Optional label for this example.
  description?: string;
}

All type definitions share these common fields:

FieldTypeDescription
kindstringType category. One of SimpleType, EnumType, ComplexType, ArrayType, MappedType, MixinType, UnionType. Required.
descriptionstringHuman-readable description.
abstractbooleanCannot be used directly in fields — only extended.
examplesDataTypeExample[]Example values for documentation.

DataTypeExample

FieldTypeDescription
valueanyThe example value.
descriptionstringOptional label for this example.

SimpleType​

Represents a scalar value. Built on a named base type with optional attribute constraints.

interface SimpleType extends DataTypeBase {
  kind: 'SimpleType';

  // Name of the parent SimpleType to extend.
  // Built-in bases: 'string' | 'number' | 'integer' | 'boolean' | 'date' | 'uuid' | 'email' | …
  // → See: Simple Types > Built-in Simple Types
  base?: string;

  // Attribute values that constrain validation at encode/decode time.
  // → See: Simple Types > Type Attributes
  // Example: { minLength: 3, maxLength: 64, pattern: '^[a-z0-9-]+$' }
  properties?: Record<string, any>;

  // Maps the OPRA type name to language-specific type names.
  // Example: { js: 'string', json: 'string' }
  nameMappings?: Record<string, string>;
}
FieldTypeDescription
basestringName of the parent SimpleType (e.g. "string", "number").
propertiesRecord<string, any>Attribute values that constrain validation.
nameMappingsRecord<string, string>Maps the OPRA type name to language-specific names (e.g. { "js": "string" }).

EnumType​

A closed set of allowed values.

interface EnumType extends DataTypeBase {
  kind: 'EnumType';

  // Name of a parent EnumType whose values are inherited.
  // → See: Enum Types > Inheritance
  base?: string;

  // Map of accepted wire values to their metadata.
  // Keys are the values validated at runtime (e.g. 'M', not 'MALE').
  // → See: Enum Types > Encode / Decode Behaviour
  // Example: { M: { alias: 'MALE', description: 'Male' }, F: { alias: 'FEMALE', description: 'Female' } }
  attributes: Record<string, EnumValueInfo>;
}

interface EnumValueInfo {
  // Human-readable key (e.g. the enum key 'MALE' for wire value 'M').
  // Not accepted as a wire value at runtime.
  alias?: string;

  // Description of this value.
  description?: string;
}

Extending another EnumType with base:

// Extends the 'Gender' type, inheriting its values (M, F),
// and adds two more (O, U). → See: Enum Types > Inheritance
const AdministrativeGender: EnumType = {
  kind: 'EnumType',
  base: 'Gender',
  description: 'Extended gender classification for administrative use',
  attributes: {
    O: { alias: 'OTHER',   description: 'Other / non-binary' },
    U: { alias: 'UNKNOWN', description: 'Not specified' },
  },
};
FieldTypeDescription
basestringName of a parent EnumType to extend.
attributesRecord<string, ValueInfo>Map of accepted wire values to their metadata.

ValueInfo

FieldTypeDescription
aliasstringHuman-readable key (e.g. the enum key MALE for value "M").
descriptionstringDescription of this value.

ComplexType​

A structured object with named fields.

interface ComplexType extends DataTypeBase {
  kind: 'ComplexType';

  // Name of the parent ComplexType to inherit fields from.
  // → See: Complex Types > Inheritance
  base?: string;

  // Named field definitions.
  // → See: Field
  // Example: { city: { type: 'string', required: true }, street: { type: 'string' } }
  fields?: Record<string, Field>;

  // Policy for properties not declared as fields.
  // false | undefined → strip silently (default)
  // true             → allow any additional property
  // 'string'         → additional properties must match this type name
  // ['error']        → reject with a validation error
  // ['error', msg]   → reject with a custom message
  additionalFields?: boolean | string | ['error'] | ['error', string];

  // Field name used as the primary key for this type.
  // Example: '_id'
  keyField?: string;

  // Field used to identify the concrete type in a union. → See: Complex Types > Discriminator
  discriminatorField?: string;

  // Value of discriminatorField that maps to this type.
  discriminatorValue?: string;
}

interface Field {
  // Data type name or inline type definition. → See: Type Definitions
  // Example: 'string' | 'email' | 'Address' | { kind: 'EnumType', attributes: { ... } }
  type?: string | DataType;

  // Human-readable field description.
  description?: string;

  // Field must be present on create operations.
  required?: boolean;

  // Field cannot be modified after creation.
  readonly?: boolean;

  // Accepted on write, never returned on read.
  writeonly?: boolean;

  // Excluded from results unless explicitly requested.
  exclusive?: boolean;

  // Default value when the field is absent.
  default?: any;

  // Field is locked to this value and ignores input.
  fixed?: any;

  // Marks the field deprecated, optionally with a migration message.
  // Example: 'Use phoneNumbers instead'
  deprecated?: boolean | string;

  // Nested entity within the parent document.
  isNestedEntity?: boolean;

  // Key field name when the field holds an array of ComplexType items.
  keyField?: string;

  // Marks the field as a localization candidate.
  localization?: boolean;

  // Example values shown in schema documentation.
  // Example: ['john@example.com', 'jane@example.com']
  examples?: any[] | Record<string, any>;
}
FieldTypeDescription
basestringName of the parent ComplexType.
fieldsRecord<string, Field>Named field definitions.
additionalFieldsboolean | string | ['error'] | ['error', string]Policy for properties not declared as fields.
keyFieldstringField name used as the primary key.
discriminatorFieldstringField used to identify the concrete type in a union.
discriminatorValuestringValue of discriminatorField that maps to this type.

Field

FieldTypeDescription
typestring | DataTypeField data type name or inline type definition.
descriptionstringField description.
requiredbooleanMust be present.
readonlybooleanCannot be modified after creation.
writeonlybooleanAccepted on write, never returned on read.
exclusivebooleanExcluded from results unless explicitly requested.
defaultanyDefault value when absent.
fixedanyLocked value — ignores input.
deprecatedboolean | stringMarks the field deprecated, optionally with a message.
isNestedEntitybooleanNested entity within the parent document.
keyFieldstringKey field name for ComplexType array items.
localizationbooleanLocalization candidate.
examplesany[] | Record<string, any>Example values.

ArrayType​

A typed array wrapper.

interface ArrayType extends DataTypeBase {
  kind: 'ArrayType';

  // Element type name or inline type definition. → See: Type Definitions
  // Example: 'string' | 'Customer' | { kind: 'EnumType', attributes: { ... } }
  type?: string | DataType;

  // Minimum number of elements (inclusive).
  minOccurs?: number;

  // Maximum number of elements (inclusive).
  maxOccurs?: number;
}
FieldTypeDescription
typestring | DataTypeElement type name or inline type definition.
minOccursnumberMinimum number of elements.
maxOccursnumberMaximum number of elements.

MappedType​

A type derived from another by picking, omitting, or changing the optionality of its fields.

interface MappedType extends DataTypeBase {
  kind: 'MappedType';

  // Source type to transform. Required.
  // → See: Mapped Types
  base: string | DataType;

  // Keep only these fields (PickType equivalent). → See: Mapped Types > PickType
  // Example: ['_id', 'givenName', 'familyName']
  pick?: string[];

  // Remove these fields (OmitType equivalent). → See: Mapped Types > OmitType
  // Example: ['passwordHash', 'internalScore']
  omit?: string[];

  // Make all or listed fields optional (PartialType equivalent). → See: Mapped Types > PartialType
  // true → all fields optional | string[] → only listed fields
  partial?: boolean | string[];

  // Make all or listed fields required (RequiredType equivalent). → See: Mapped Types > RequiredType
  // true → all fields required | string[] → only listed fields
  required?: boolean | string[];

  // Discriminator field override.
  discriminatorField?: string;

  // Discriminator value override.
  discriminatorValue?: string;
}
FieldTypeDescription
basestring | DataTypeSource type to transform. Required.
pickstring[]Keep only these fields.
omitstring[]Remove these fields.
partialboolean | string[]Make all (or listed) fields optional.
requiredboolean | string[]Make all (or listed) fields required.
discriminatorFieldstringDiscriminator field override.
discriminatorValuestringDiscriminator value override.

MixinType​

A composite type that merges fields from multiple base types.

interface MixinType extends DataTypeBase {
  kind: 'MixinType';

  // Ordered list of base types to merge.
  // Fields are merged in array order — last type wins on name conflicts.
  // → See: Mixin Types > Field Merging
  // Example: ['Timestamped', 'SoftDeletable']
  types: (string | DataType)[];
}
FieldTypeDescription
types(string | DataType)[]Ordered list of base types to merge. Last-write-wins on field name conflicts.

UnionType​

A type that accepts one of several possible types at runtime.

interface UnionType extends DataTypeBase {
  kind: 'UnionType';

  // List of accepted types.
  // Each type should declare a discriminatorValue matching a value of the discriminator field.
  // → See: Complex Types > Discriminator
  // Example: ['Dog', 'Cat']
  types: (string | DataType)[];

  // Field name used to select the concrete type at decode time.
  // Example: 'kind'
  discriminator?: string;
}
FieldTypeDescription
types(string | DataType)[]List of accepted types.
discriminatorstringField name used to select the concrete type at decode time.

References​

The references field links external OPRA documents into the current document under a namespace alias. Linked types can be referenced as namespace:TypeName.

interface DocumentReference {
  // URL where the referenced document can be fetched.
  // Example: 'https://api.example.com/customer-models/opra.json'
  url?: string;

  // Metadata snapshot of the referenced document. → See: Document Info
  // Example: { title: 'Customer Models', version: '1.0' }
  info?: DocumentInfo;
}

// Usage: types from namespace 'cm' are referenced as 'cm:Customer'
const references: Record<string, DocumentReference> = {
  cm: {
    url: 'https://api.example.com/customer-models/opra.json',
    info: { title: 'Customer Models', version: '1.0' },
  },
};

DocumentReference

FieldTypeDescription
urlstringURL where the referenced document can be fetched.
infoDocumentInfoMetadata snapshot of the referenced document.

HTTP API Schema​

The api field holds the HTTP API definition when transport is "http".

interface HttpApi {
  // Transport identifier.
  transport: 'http';

  // API name.
  // Example: 'CustomerApi'
  name: string;

  // Human-readable description.
  description?: string;

  // Base URL path for all controllers.
  // Example: '/api'
  url?: string;

  // Named controller definitions. → See: HttpController
  // Example: { Customers: { kind: 'HttpController', path: '/customers', operations: { ... } } }
  controllers: Record<string, HttpController>;
}

HttpController​

Groups related operations under a shared path. Controllers can be nested.

interface HttpController {
  kind: 'HttpController';

  // Human-readable description.
  description?: string;

  // URL path segment appended to the parent path.
  // Example: '/customers'
  path?: string;

  // Parameters shared by all operations in this controller. → See: HttpParameter
  // Example: [{ name: 'tenantId', location: 'header', type: 'string', required: true }]
  parameters?: HttpParameter[];

  // Named operation definitions. → See: HttpOperation
  // Example: { Get: { kind: 'HttpOperation', method: 'GET', ... } }
  operations?: Record<string, HttpOperation>;

  // Nested child controllers (same structure, recursive). → See: HttpController
  // Example: { Orders: { kind: 'HttpController', path: '/:id/orders', ... } }
  controllers?: Record<string, HttpController>;

  // Local type definitions scoped to this controller. → See: Type Definitions
  types?: Record<string, DataType>;
}
FieldTypeDescription
kind"HttpController"Always "HttpController".
descriptionstringHuman-readable description.
pathstringURL path segment appended to the parent path.
parametersHttpParameter[]Parameters shared by all operations in this controller.
operationsRecord<string, HttpOperation>Named operation definitions.
controllersRecord<string, HttpController>Nested child controllers.
typesRecord<string, DataType>Local type definitions scoped to this controller.

HttpOperation​

A single HTTP endpoint.

interface HttpOperation {
  kind: 'HttpOperation';

  // HTTP method.
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'SEARCH';

  // URL path segment appended to the controller path unless mergePath is true.
  // Example: '/:id'
  path?: string;

  // When true, merges path into the parent instead of appending.
  mergePath?: boolean;

  // Human-readable description.
  description?: string;

  // Operation-level parameters. → See: HttpParameter
  // Example: [{ name: 'id', location: 'path', type: 'number', required: true }]
  parameters?: HttpParameter[];

  // Request body definition. → See: HttpRequestBody
  // Example: { required: true, content: [{ contentType: 'application/json', type: 'Customer' }] }
  requestBody?: HttpRequestBody;

  // Response definitions. → See: HttpOperationResponse
  // Example: [{ statusCode: 200, contentType: 'application/json', type: 'Customer' }]
  responses?: HttpOperationResponse[];

  // Local type definitions scoped to this operation. → See: Type Definitions
  types?: Record<string, DataType>;
}
FieldTypeDescription
kind"HttpOperation"Always "HttpOperation".
methodstringHTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, SEARCH.
pathstringURL path segment. Appended to the controller path unless mergePath is true.
mergePathbooleanMerge path into the parent instead of appending.
descriptionstringHuman-readable description.
parametersHttpParameter[]Operation-level parameters.
requestBodyHttpRequestBodyRequest body definition.
responsesHttpOperationResponse[]Response definitions.
typesRecord<string, DataType>Local type definitions scoped to this operation.

HttpParameter​

A query, path, header, or cookie parameter.

interface HttpParameter {
  // Parameter name.
  // Example: 'id'
  name: string;

  // Parameter location.
  location: 'query' | 'path' | 'header' | 'cookie';

  // Parameter data type name or inline definition. → See: Type Definitions
  // Example: 'number' | 'string' | { kind: 'EnumType', attributes: { ... } }
  type?: string | DataType;

  // Parameter must be provided.
  required?: boolean;

  // Default value when the parameter is absent.
  default?: any;

  // Marks the parameter deprecated, optionally with a migration message.
  deprecated?: boolean | string;

  // Identifies this as the primary key parameter.
  keyParam?: boolean;

  // Separator character for array-valued query parameters.
  // Example: ',' for comma-separated values
  arraySeparator?: string;

  // Human-readable description.
  description?: string;
}
FieldTypeDescription
namestringParameter name.
locationstring"query", "path", "header", or "cookie".
typestring | DataTypeParameter data type.
requiredbooleanParameter must be provided.
defaultanyDefault value when absent.
deprecatedboolean | stringMarks the parameter deprecated.
keyParambooleanIdentifies this as the primary key parameter.
arraySeparatorstringSeparator character for array-valued query parameters.
descriptionstringHuman-readable description.

HttpRequestBody​

The request body accepted by an operation.

interface HttpRequestBody {
  // Body must be present.
  required?: boolean;

  // Treat all fields as optional.
  // true → top-level fields optional | 'deep' → recursively optional (useful for PATCH)
  partial?: boolean | 'deep';

  // Allow patch operator expressions (e.g. $set, $unset) in the body.
  allowPatchOperators?: boolean;

  // Maximum allowed body size in bytes.
  // Example: 1048576 (1 MB)
  maxContentSize?: number;

  // Accepted media type definitions. → See: HttpMediaType
  // Example: [{ contentType: 'application/json', type: 'Customer' }]
  content: HttpMediaType[];
}
FieldTypeDescription
requiredbooleanBody must be present.
partialboolean | "deep"Treat all fields as optional (for PATCH operations).
allowPatchOperatorsbooleanAllow patch operator expressions in the body.
maxContentSizenumberMaximum allowed body size in bytes.
contentHttpMediaType[]Accepted media type definitions.

HttpMediaType​

Defines a single accepted or returned media type.

interface HttpMediaType {
  // MIME type or range. Omit to accept any content type.
  // Example: 'application/json' | 'multipart/form-data'
  contentType?: string | string[];

  // Data type of the body. → See: Type Definitions
  // Example: 'Customer' | { kind: 'ComplexType', fields: { ... } }
  type?: string | DataType;

  // Content encoding.
  // Example: 'gzip'
  contentEncoding?: string;

  // Inline example value.
  example?: string;

  // Named example values.
  // Example: { minimal: '{"name":"Jane"}', full: '{"name":"Jane","email":"..."}' }
  examples?: Record<string, string>;

  // Multipart field definitions (for multipart/form-data uploads).
  multipartFields?: HttpMultipartField[];

  // Maximum number of non-file fields.
  maxFields?: number;

  // Maximum total size of non-file fields in bytes.
  maxFieldsSize?: number;

  // Maximum number of uploaded files.
  maxFiles?: number;

  // Maximum size per file in bytes.
  // Example: 10485760 (10 MB)
  maxFileSize?: number;

  // Maximum combined size of all files in bytes.
  // Example: 52428800 (50 MB)
  maxTotalFileSize?: number;

  // Minimum size per file in bytes.
  minFileSize?: number;
}

For multipart file uploads:

const uploadBody: HttpMediaType = {
  contentType: 'multipart/form-data',
  maxFields: 10,
  maxFieldsSize: 65536,
  maxFiles: 5,
  maxFileSize: 10485760,      // 10 MB per file
  maxTotalFileSize: 52428800, // 50 MB total
  minFileSize: 1,
};
FieldTypeDescription
contentTypestring | string[]MIME type or range.
typestring | DataTypeData type of the body.
contentEncodingstringContent encoding.
examplestringInline example value.
examplesRecord<string, string>Named example values.
multipartFieldsHttpMultipartField[]Multipart field definitions.
maxFieldsnumberMaximum number of non-file fields.
maxFieldsSizenumberMaximum total size of non-file fields in bytes.
maxFilesnumberMaximum number of uploaded files.
maxFileSizenumberMaximum size per file in bytes.
maxTotalFileSizenumberMaximum combined size of all files in bytes.
minFileSizenumberMinimum size per file in bytes.

HttpOperationResponse​

A response returned by an operation. Extends HttpMediaType with status code and response-specific fields.

interface HttpOperationResponse extends HttpMediaType {
  // HTTP status code(s) this response applies to.
  // Single code: 200 | Range string: '2xx' | List: [200, 201]
  statusCode: number | string | (number | string)[];

  // Response header parameters. → See: HttpParameter
  // Example: [{ name: 'X-Request-Id', location: 'header', type: 'string' }]
  parameters?: HttpParameter[];

  // Response fields may be partially present.
  partial?: boolean | 'deep';
}
FieldTypeDescription
statusCodenumber | string | (number | string)[]HTTP status code(s) this response applies to (e.g. 200, "2xx").
parametersHttpParameter[]Response header parameters.
partialboolean | "deep"Response fields may be partially present.

Message Queue API Schema​

The api field holds the MQ API definition when transport is "mq".

interface MQApi {
  // Transport identifier.
  transport: 'mq';

  // API name.
  // Example: 'CustomerEvents'
  name: string;

  // Messaging platform.
  // Example: 'Kafka' | 'RabbitMQ'
  platform: string;

  // Human-readable description.
  description?: string;

  // Named controller definitions. → See: MQController
  // Example: { CustomerEvents: { kind: 'MQController', operations: { ... } } }
  controllers: Record<string, MQController>;
}

MQController​

Groups related message operations.

interface MQController {
  kind: 'MQController';

  // Human-readable description.
  description?: string;

  // Message headers shared by all operations.
  // Example: [{ name: 'correlationId', type: 'string' }]
  headers?: MQHeader[];

  // Named operation definitions. → See: MQOperation
  // Example: { CustomerCreated: { kind: 'MQOperation', channel: 'customer.created', type: 'CustomerCreatedEvent' } }
  operations?: Record<string, MQOperation>;

  // Local type definitions scoped to this controller. → See: Type Definitions
  types?: Record<string, DataType>;
}
FieldTypeDescription
kind"MQController"Always "MQController".
descriptionstringHuman-readable description.
headersMQHeader[]Headers shared by all operations.
operationsRecord<string, MQOperation>Named operation definitions.
typesRecord<string, DataType>Local type definitions.

MQOperation​

A single message channel subscription or publication.

interface MQOperation {
  kind: 'MQOperation';

  // Channel name or pattern this operation listens on.
  // Example: 'customer.created' | ['customer.created', 'customer.updated']
  channel: string | string[];

  // Message payload type name or inline definition. → See: Type Definitions
  // Example: 'CustomerCreatedEvent'
  type: string | DataType;

  // Message key type (for keyed messages, e.g. Kafka partition key).
  // Example: 'string'
  keyType?: string | DataType;

  // Operation-level message headers.
  headers?: MQHeader[];

  // Human-readable description.
  description?: string;

  // Optional response message definition. → See: MQOperationResponse
  // Example: { channel: 'customer.created.ack', type: 'Ack' }
  response?: MQOperationResponse;

  // Local type definitions scoped to this operation. → See: Type Definitions
  types?: Record<string, DataType>;
}

interface MQOperationResponse {
  // Response channel name or pattern.
  // Example: 'customer.created.ack'
  channel?: string | string[];

  // Response payload type name or inline definition. → See: Type Definitions
  type: string | DataType;

  // Response message key type.
  keyType?: string | DataType;

  // Response message headers.
  headers?: MQHeader[];

  // Human-readable description.
  description?: string;
}
FieldTypeDescription
kind"MQOperation"Always "MQOperation".
channelstring | string[]Channel name or pattern this operation listens on.
typestring | DataTypeMessage payload type.
keyTypestring | DataTypeMessage key type (for keyed messages, e.g. Kafka).
headersMQHeader[]Operation-level message headers.
descriptionstringHuman-readable description.
responseMQOperationResponseOptional response message definition.
typesRecord<string, DataType>Local type definitions.

WebSocket API Schema​

The api field holds the WebSocket API definition when transport is "ws".

interface WSApi {
  // Transport identifier.
  transport: 'ws';

  // API name.
  // Example: 'NotificationApi'
  name: string;

  // WebSocket platform.
  // Example: 'Socketio'
  platform?: string;

  // Human-readable description.
  description?: string;

  // Named controller definitions. → See: WSController
  // Example: { Notifications: { kind: 'WSController', operations: { ... } } }
  controllers: Record<string, WSController>;
}

WSController​

Groups related WebSocket event handlers.

interface WSController {
  kind: 'WSController';

  // Human-readable description.
  description?: string;

  // Named operation definitions. → See: WSOperation
  // Example: { OnNotification: { kind: 'WSOperation', event: 'notification', arguments: ['Notification'] } }
  operations?: Record<string, WSOperation>;

  // Local type definitions scoped to this controller. → See: Type Definitions
  types?: Record<string, DataType>;
}
FieldTypeDescription
kind"WSController"Always "WSController".
descriptionstringHuman-readable description.
operationsRecord<string, WSOperation>Named operation definitions.
typesRecord<string, DataType>Local type definitions.

WSOperation​

A single WebSocket event handler.

interface WSOperation {
  kind: 'WSOperation';

  // WebSocket event name this operation handles.
  // Example: 'notification'
  event: string;

  // Ordered list of argument types. → See: Type Definitions
  // Example: ['Notification'] | ['string', 'NotificationOptions']
  arguments?: (string | DataType)[];

  // Response type returned to the caller. → See: Type Definitions
  // Example: 'Ack' | { kind: 'ComplexType', fields: { success: { type: 'boolean' } } }
  response?: string | DataType;

  // Human-readable description.
  description?: string;

  // Local type definitions scoped to this operation. → See: Type Definitions
  types?: Record<string, DataType>;
}
FieldTypeDescription
kind"WSOperation"Always "WSOperation".
eventstringEvent name this operation handles.
arguments(string | DataType)[]Ordered list of argument types.
responsestring | DataTypeResponse type returned to the caller.
descriptionstringHuman-readable description.
typesRecord<string, DataType>Local type definitions.