openapi: 3.0.3 info: x-product-infos: - $ref: './node_modules/@zerobias-org/product-zerobias-zerobias/catalog.yml#/Product' x-impl-name: DynamicDataProducer version: 1.2.33 title: '@zerobias-org/module-interface-dataproducer' description: Dynamic Data Producer Interface paths: # Object Operations /objects: get: tags: - objects summary: Get root object description: Returns the root object with id and name of '/' operationId: getRootObject responses: '200': description: Root object content: application/json: schema: $ref: '#/components/schemas/DataProducerObject' /objects/{objectId}: get: tags: - objects summary: Get object by ID description: Retrieve a specific object by its unique identifier operationId: getObject parameters: - $ref: '#/components/parameters/objectId' responses: '200': description: Object details content: application/json: schema: $ref: '#/components/schemas/DataProducerObject' /objects/{objectId}/children: post: tags: - objects summary: Create child object description: Creates a new object as a child of the specified parent container operationId: createChildObject parameters: - $ref: '#/components/parameters/objectId' requestBody: required: true description: Child object properties (id is optional and will be generated if not provided) content: application/json: schema: $ref: '#/components/schemas/CreateObjectRequest' responses: '201': description: Child object created content: application/json: schema: $ref: '#/components/schemas/DataProducerObject' get: tags: - objects summary: Get child objects description: Returns paged results of objects that are children of the specified object operationId: getChildren # Parameter order is load-bearing: codegen mirrors it into TypeScript # positional args. New optional params (pageTokenParam) are appended # at the end so existing callers from 1.2.x / 2.0.x continue to # compile against 2.1.x. Don't insert in the middle. parameters: - $ref: '#/components/parameters/objectId' - $ref: '#/components/parameters/pageNumberParam' - $ref: '#/components/parameters/pageSizeParam' - $ref: '#/components/parameters/sortByParam' - $ref: '#/components/parameters/sortDirParam' - name: type in: query required: false description: Optional object class filter schema: type: array items: $ref: '#/components/schemas/ObjectClass' - name: tags in: query required: false description: Optional tags filter - returns objects containing any of the specified tags schema: type: array items: type: string - $ref: '#/components/parameters/pageTokenParam' responses: '200': description: List of child objects headers: link: $ref: '#/components/headers/pagedLinkHeader' count: $ref: '#/components/headers/pageCountHeader' pageToken: $ref: '#/components/headers/pageTokenHeader' content: application/json: schema: type: array items: $ref: '#/components/schemas/DataProducerObject' put: tags: - objects summary: Update object description: Updates object metadata and properties operationId: updateObject parameters: - $ref: '#/components/parameters/objectId' - name: If-Match in: header description: ETag for optimistic concurrency control schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateObjectRequest' responses: '200': description: Object updated content: application/json: schema: $ref: '#/components/schemas/DataProducerObject' delete: tags: - objects summary: Delete object description: Deletes an object and optionally its children operationId: deleteObject parameters: - $ref: '#/components/parameters/objectId' - name: recursive in: query description: Delete children recursively (containers only) schema: type: boolean default: false responses: '204': description: Object deleted /objects/{objectId}/search: get: tags: - objects summary: Search objects description: Performs keyword search or filtered search within object hierarchy. Either keywords or filter must be provided, but not both. operationId: objectSearch # New optional params (pageTokenParam, propertiesParam) appended at # the end to keep the positional TS signature stable for 1.2.x / 2.0.x # callers. See note on getChildren above. parameters: - $ref: '#/components/parameters/objectId' - $ref: '#/components/parameters/pageNumberParam' - $ref: '#/components/parameters/pageSizeParam' - $ref: '#/components/parameters/sortByParam' - $ref: '#/components/parameters/sortDirParam' - $ref: '#/components/parameters/scopeParam' - name: keywords in: query required: false description: Search keywords (mutually exclusive with filter) schema: type: array items: type: string - name: filter in: query required: false description: RFC4515 structured filter expression (mutually exclusive with keywords) schema: type: string - $ref: '#/components/parameters/pageTokenParam' - $ref: '#/components/parameters/propertiesParam' responses: '200': description: Search results headers: link: $ref: '#/components/headers/pagedLinkHeader' count: $ref: '#/components/headers/pageCountHeader' pageToken: $ref: '#/components/headers/pageTokenHeader' content: application/json: schema: type: array items: $ref: '#/components/schemas/DataProducerObject' /objects/{objectId}/searchChildren: get: tags: - objects summary: Search child objects with filtering and property selection description: | Advanced search and filtering of child objects within a container. Supports RFC4515 filters for child object metadata and dot notation property selection. Differences from /children: - /children: Simple listing with basic type/tag filters - /searchChildren: Advanced RFC4515 filtering + property projection operationId: searchChildObjects # New endpoint in 2.x — no positional compat to preserve, but ordering # follows the same convention as the other paginated ops: opt-in # cursor/projection params at the end. parameters: - $ref: '#/components/parameters/objectId' - $ref: '#/components/parameters/pageNumberParam' - $ref: '#/components/parameters/pageSizeParam' - $ref: '#/components/parameters/sortByParam' - $ref: '#/components/parameters/sortDirParam' - name: filter in: query required: false description: RFC4515 filter expression for child object properties schema: type: string example: "(&(objectClass=document)(tags=*important*)(modified>=2023-01-01))" - $ref: '#/components/parameters/scopeParam' - $ref: '#/components/parameters/pageTokenParam' - $ref: '#/components/parameters/propertiesParam' - name: includeCount in: query required: false description: Include total count in response headers (may be expensive) schema: type: boolean default: false responses: '200': description: Filtered child objects with property selection applied headers: link: $ref: '#/components/headers/pagedLinkHeader' count: $ref: '#/components/headers/pageCountHeader' pageToken: $ref: '#/components/headers/pageTokenHeader' content: application/json: schema: type: array items: $ref: '#/components/schemas/DataProducerObject' # Collection Operations /objects/{objectId}/collection/elements: get: tags: - collections summary: Get collection elements description: Returns paged collection data for collection objects operationId: getCollectionElements # New optional params appended; see note on getChildren above. parameters: - $ref: '#/components/parameters/objectId' - $ref: '#/components/parameters/pageNumberParam' - $ref: '#/components/parameters/pageSizeParam' - $ref: '#/components/parameters/sortByParam' - $ref: '#/components/parameters/sortDirParam' - $ref: '#/components/parameters/pageTokenParam' - $ref: '#/components/parameters/propertiesParam' responses: '200': description: Collection elements headers: link: $ref: '#/components/headers/pagedLinkHeader' count: $ref: '#/components/headers/pageCountHeader' pageToken: $ref: '#/components/headers/pageTokenHeader' content: application/json: schema: type: array items: type: object additionalProperties: true post: tags: - collections summary: Add collection element description: Adds a new element to the collection (requires collection schema with primary key properties) operationId: addCollectionElement parameters: - $ref: '#/components/parameters/objectId' requestBody: required: true content: application/json: schema: type: object additionalProperties: true responses: '201': description: Element added content: application/json: schema: type: object additionalProperties: true /objects/{objectId}/collection/bulk: post: tags: - collections summary: Execute bulk operations on collection description: Perform multiple create/update/delete operations in a single request operationId: executeBulkOperations parameters: - $ref: '#/components/parameters/objectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkOperationRequest' responses: '200': description: Bulk operation results content: application/json: schema: $ref: '#/components/schemas/BulkOperationResponse' /objects/{objectId}/collection/elements/{elementKey}: get: tags: - collections summary: Get collection element by key description: Retrieves a specific collection element by its primary key operationId: getCollectionElement parameters: - $ref: '#/components/parameters/objectId' - name: elementKey in: path required: true description: Primary key value(s) separated by commas for composite keys schema: type: string responses: '200': description: Collection element content: application/json: schema: type: object additionalProperties: true put: tags: - collections summary: Update collection element description: Updates a specific collection element by its primary key operationId: updateCollectionElement parameters: - $ref: '#/components/parameters/objectId' - name: elementKey in: path required: true description: Primary key value(s) separated by commas for composite keys schema: type: string - name: If-Match in: header description: ETag for optimistic concurrency control schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: true responses: '200': description: Element updated content: application/json: schema: type: object additionalProperties: true delete: tags: - collections summary: Delete collection element description: Deletes a specific collection element by its primary key operationId: deleteCollectionElement parameters: - $ref: '#/components/parameters/objectId' - name: elementKey in: path required: true description: Primary key value(s) separated by commas for composite keys schema: type: string responses: '204': description: Element deleted /objects/{objectId}/collection/search: get: tags: - collections summary: Search collection elements description: Filtered search within collection data operationId: searchCollectionElements # New optional params appended; see note on getChildren above. parameters: - $ref: '#/components/parameters/objectId' - $ref: '#/components/parameters/pageNumberParam' - $ref: '#/components/parameters/pageSizeParam' - name: filter in: query required: false description: RFC4515 structured filter expression schema: type: string - $ref: '#/components/parameters/sortByParam' - $ref: '#/components/parameters/sortDirParam' - $ref: '#/components/parameters/pageTokenParam' - $ref: '#/components/parameters/propertiesParam' responses: '200': description: Filtered collection elements headers: link: $ref: '#/components/headers/pagedLinkHeader' count: $ref: '#/components/headers/pageCountHeader' pageToken: $ref: '#/components/headers/pageTokenHeader' content: application/json: schema: type: array items: type: object additionalProperties: true # Function Operations /objects/{objectId}/invoke: post: tags: - functions summary: Invoke function description: Execute function with input parameters operationId: invokeFunction parameters: - $ref: '#/components/parameters/objectId' requestBody: required: false description: Function input parameters (must conform to inputSchema if specified) content: application/json: schema: type: object additionalProperties: true responses: '200': description: Function execution result content: application/json: schema: type: object additionalProperties: true # Binary Operations - Content Upload/Update /objects/{objectId}/upload: post: tags: - binary summary: Upload binary content description: Uploads or replaces binary content for binary objects operationId: uploadBinaryContent parameters: - $ref: '#/components/parameters/objectId' requestBody: required: true content: '*/*': schema: type: string format: binary responses: '201': description: Content uploaded content: application/json: schema: $ref: '#/components/schemas/DataProducerObject' # Document Operations /objects/{objectId}/document: get: tags: - documents summary: Get document data description: Returns JSON document for document objects operationId: getDocumentData parameters: - $ref: '#/components/parameters/objectId' responses: '200': description: Document data content: application/json: schema: type: object additionalProperties: true put: tags: - documents summary: Update document data description: Updates JSON document content for document objects operationId: updateDocumentData parameters: - $ref: '#/components/parameters/objectId' - name: If-Match in: header description: ETag for optimistic concurrency control schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: true responses: '200': description: Document updated content: application/json: schema: type: object additionalProperties: true # Binary Operations /objects/{objectId}/download: get: tags: - binary summary: Download binary content description: Download binary content with streaming and resumable support operationId: downloadBinary parameters: - $ref: '#/components/parameters/objectId' responses: '200': description: Binary file download content: '*/*': schema: type: string format: binary '206': description: Partial content (range request) content: '*/*': schema: type: string format: binary # Enhanced Function Operations /objects/{objectId}/validate: post: tags: - functions summary: Validate function input description: Validate input parameters against function schema without execution operationId: validateFunctionInput parameters: - $ref: '#/components/parameters/objectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ValidateFunctionInputRequest' responses: '200': description: Validation results content: application/json: schema: $ref: '#/components/schemas/ValidationResult' # Schema Operations /schemas/{schemaId}: get: tags: - schemas summary: Get schema by ID description: | Retrieve schema metadata and structure for a given schema ID. The `schemaId` path parameter must be URL-encoded because canonical schema IDs contain `:` and `.` characters (e.g. `schema:table:mydb.public.customers`). Implementations are expected to cache schema lookups (recommended TTL: 5 minutes). operationId: getSchema parameters: - name: schemaId in: path required: true description: | URL-encoded canonical schema identifier. See the `SchemaId` schema for the full format specification. schema: $ref: '#/components/schemas/SchemaId' responses: '200': description: Schema details content: application/json: schema: $ref: '#/components/schemas/Schema' components: parameters: objectId: name: objectId in: path required: true description: Unique object identifier schema: type: string pageTokenParam: name: pageToken in: query description: | Opaque cursor for cursor-based pagination. When provided, pageNumber is ignored. Use the token from the previous response's pageToken header to get the next page. schema: type: string pageNumberParam: name: pageNumber in: query description: The requested page (1-indexed). Ignored when pageToken is provided. schema: type: integer format: int32 default: 1 minimum: 1 pageSizeParam: name: pageSize in: query description: The number of items in each page schema: type: integer format: int32 default: 100 minimum: 1 maximum: 1000 propertiesParam: name: properties in: query description: | Dot notation property selection array. Controls which properties are returned in results. Examples: - ["email"] - Return only email field (fuzzy matches e-mail, email_address, etc.) - ["contact.phone", "contact.email"] - Return contact object with only phone and email - ["contact"] - Return entire contact object - [] or omitted - Return all properties (default) Fuzzy matching applies to field names (email matches e-mail, email_address, emailAddress). For nested objects, specify full dot path to include only specific sub-properties. schema: type: array items: type: string style: form explode: false sortByParam: $ref: './node_modules/@zerobias-org/types-core/schema/sortByParam.yml' sortDirParam: $ref: './node_modules/@zerobias-org/types-core/schema/sortDirParam.yml' scopeParam: name: scope in: query required: false description: Search scope depth schema: $ref: '#/components/schemas/SearchScope' headers: pageCountHeader: description: The total count of elements in the result set schema: type: integer format: int64 pageTokenHeader: description: Opaque cursor token for fetching the next page. Absence indicates last page. schema: type: string pagedLinkHeader: description: Links for paging results (first, prev, next, last) schema: type: array items: type: string responses: NoSuchObjectError: description: Object not found content: application/json: schema: $ref: './node_modules/@zerobias-org/types-core/schema/errors/noSuchObjectError.yml' UnsupportedOperationError: description: Operation not supported by this object type content: application/json: schema: $ref: './node_modules/@zerobias-org/types-core/schema/errors/illegalArgumentError.yml' schemas: SchemaId: type: string description: | Canonical schema identifier in the form `schema:{type}:{catalog}.{schema}.{name}[:{direction}]`. Type discriminators: - `table` — database table (e.g. `schema:table:mydb.public.customers`) - `view` — database view (e.g. `schema:view:mydb.public.active_customers`) - `function` — function input/output, requires `:input` or `:output` suffix (e.g. `schema:function:mydb.public.calc_tax:input`) - `type` — custom/composite type (e.g. `schema:type:mydb.public.address`) - `enum` — enumerated type (e.g. `schema:enum:mydb.public.order_status`) - `shared` — reusable, non-database-scoped schema, form `schema:shared:{name}` (e.g. `schema:shared:address`) Discriminators are required because databases allow a table, view, type, and domain to share the same name; a discriminator-less ID would be ambiguous. pattern: '^(schema:(table|view|type|enum):[^:.]+\.[^:.]+\.[^:.]+|schema:function:[^:.]+\.[^:.]+\.[^:.]+:(input|output)|schema:shared:[^:]+)$' example: 'schema:table:mydb.public.customers' DataProducerObject: type: object required: - id - name properties: id: type: string description: Immutable primary key (unique identifier) name: type: string description: Human-readable name description: type: string description: Optional description path: type: array items: type: string description: Documentary path array from root to object thumbnail: type: string format: uri description: Public URL or data URI for visual representation tags: type: array items: type: string description: Optional organizational tags created: type: string format: date-time description: Creation timestamp modified: type: string format: date-time description: Last modification timestamp etag: type: string description: Entity tag for optimistic concurrency control versionId: type: string description: Version identifier for object versioning objectClass: type: array items: $ref: '#/components/schemas/ObjectClass' description: Capability indicators # Container properties # Collection properties collectionSchema: allOf: - $ref: '#/components/schemas/SchemaId' description: Schema ID for collection elements (collection objects only) collectionSize: type: integer format: int64 description: Number of elements in collection (collection objects only) # Function properties inputSchema: allOf: - $ref: '#/components/schemas/SchemaId' description: Schema ID for function inputs (function objects only) outputSchema: allOf: - $ref: '#/components/schemas/SchemaId' description: Schema ID for function outputs (function objects only) throws: type: object additionalProperties: $ref: '#/components/schemas/SchemaId' description: Map of error codes to error Schema IDs (function objects only) # Document properties documentSchema: allOf: - $ref: '#/components/schemas/SchemaId' description: Schema ID for document structure (document objects only) # Binary properties mimeType: type: string description: MIME type of binary content (binary objects only) fileName: type: string description: Original filename (binary objects only) size: type: integer format: int64 description: Content size in bytes (binary objects only) checksum: type: string description: >- Content digest that changes if and only if the object's content changes. Used for change detection (e.g. deciding whether to re-fetch a copy). Opaque, source-defined value (e.g. git blob SHA, S3 ETag, content hash); compare for equality only. Distinct from etag, which is a metadata entity tag for optimistic concurrency. ObjectClass: type: string description: Object capability indicator enum: - container - collection - function - document - binary SearchScope: type: string description: Search scope depth for hierarchical searches enum: - one_level - subtree default: one_level Schema: type: object description: Metadata describing data structure and relationships required: - id - dataTypes - properties properties: id: allOf: - $ref: '#/components/schemas/SchemaId' description: Unique, immutable schema identifier dataTypes: type: array items: $ref: './node_modules/@zerobias-org/types-core/schema/type.yml' description: Array of DataType entities used by this schema properties: type: array items: $ref: '#/components/schemas/Property' description: Array of property definitions Property: type: object required: - name - dataType properties: name: type: string description: JavaScript-compatible property name description: type: string description: Optional property description required: type: boolean default: false description: Whether property is required multi: type: boolean default: false description: Whether property accepts multiple values primaryKey: type: boolean default: false description: Whether property is part of the primary key dataType: type: string description: Name of DataType entity format: type: string description: Format specification for data display/input (e.g., date format, number format) references: type: object properties: schemaId: allOf: - $ref: '#/components/schemas/SchemaId' description: Referenced schema ID propertyName: type: string description: Referenced property name description: Schema and property reference for relationships ValidationResult: type: object properties: valid: type: boolean description: Whether input is valid errors: type: array description: List of validation errors items: type: object properties: path: type: string description: Path to invalid field message: type: string description: Error message code: type: string description: Error code warnings: type: array description: List of validation warnings items: type: object properties: path: type: string description: Path to field with warning message: type: string description: Warning message ValidateFunctionInputRequest: type: object properties: input: description: Input to validate additionalProperties: true strict: type: boolean description: Strict validation mode default: false BulkOperation: type: object required: - action properties: action: type: string enum: [create, update, delete] description: Operation type key: type: string description: Element key (for update/delete) data: description: Data for operation additionalProperties: true BulkOperationRequest: type: object required: - operations properties: operations: type: array description: List of operations to execute items: $ref: '#/components/schemas/BulkOperation' atomic: type: boolean description: All or nothing execution default: false continueOnError: type: boolean description: Continue processing on errors default: true BulkOperationResponse: type: object properties: results: type: array description: Individual operation results items: type: object properties: success: type: boolean description: Whether the operation succeeded data: description: Result data (if successful) additionalProperties: true error: description: Error information (if failed) additionalProperties: true summary: type: object description: Aggregated execution summary properties: total: type: integer description: Total number of operations succeeded: type: integer description: Number of successful operations failed: type: integer description: Number of failed operations CreateObjectRequest: type: object properties: id: type: string description: Optional object ID (will be generated if not provided) name: type: string description: Human-readable name description: type: string description: Optional description thumbnail: type: string format: uri description: Public URL or data URI for visual representation tags: type: array items: type: string description: Optional organizational tags objectClass: type: array items: $ref: '#/components/schemas/ObjectClass' description: Capability indicators # Collection properties collectionSchema: allOf: - $ref: '#/components/schemas/SchemaId' description: Schema ID for collection elements (collection objects only) # Function properties inputSchema: allOf: - $ref: '#/components/schemas/SchemaId' description: Schema ID for function inputs (function objects only) outputSchema: allOf: - $ref: '#/components/schemas/SchemaId' description: Schema ID for function outputs (function objects only) throws: type: object additionalProperties: $ref: '#/components/schemas/SchemaId' description: Map of error codes to error Schema IDs (function objects only) # Document properties documentSchema: allOf: - $ref: '#/components/schemas/SchemaId' description: Schema ID for document structure (document objects only) # Binary properties mimeType: type: string description: MIME type of binary content (binary objects only) fileName: type: string description: Original filename (binary objects only) required: - name - objectClass UpdateObjectRequest: type: object properties: name: type: string description: Human-readable name description: type: string description: Optional description thumbnail: type: string format: uri description: Public URL or data URI for visual representation tags: type: array items: type: string description: Optional organizational tags # Collection properties collectionSchema: allOf: - $ref: '#/components/schemas/SchemaId' description: Schema ID for collection elements (collection objects only) # Function properties inputSchema: allOf: - $ref: '#/components/schemas/SchemaId' description: Schema ID for function inputs (function objects only) outputSchema: allOf: - $ref: '#/components/schemas/SchemaId' description: Schema ID for function outputs (function objects only) throws: type: object additionalProperties: $ref: '#/components/schemas/SchemaId' description: Map of error codes to error Schema IDs (function objects only) # Document properties documentSchema: allOf: - $ref: '#/components/schemas/SchemaId' description: Schema ID for document structure (document objects only) # Binary properties mimeType: type: string description: MIME type of binary content (binary objects only) fileName: type: string description: Original filename (binary objects only)