Data Models & Type System

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_tap_oracle_wms/settings.py
• src/flext_tap_oracle_wms/README.md
• meltano.yml
• pyproject.toml
• tests/unit/test_config.py
• src/flext_tap_oracle_wms/__init__.py

Introduction

The Data Models & Type System of the flext-tap-oracle-wms project provides a robust, validated framework for managing configurations and data structures required to extract data from Oracle Warehouse Management Systems (WMS). It leverages modern Python typing, including Pydantic for settings validation and Singer SDK patterns for stream data modeling.

The system ensures that all configurations—ranging from authentication credentials to complex entity filtering rules—are strictly typed and validated against domain-specific business rules before the tap initiates connection with the Oracle WMS API.

Sources: src/flext_tap_oracle_wms/README.md, src/flext_tap_oracle_wms/settings.py:17-25

Configuration Models

The primary configuration model is FlextTapOracleWmsSettings, which inherits from FlextSettingsBase. This model defines the environment-aware configuration schema for the tap, using an FLEXT_TAP_ORACLE_WMS_ prefix for environment variables.

Core Configuration Fields

Field	Type	Description
base_url	str | t.AnyUrl	The base URL for the Oracle WMS instance.
username	str	Credentials for Basic Authentication.
password	str | t.SecretStr	Sensitive credential, masked in logs.
api_version	str	Targeted WMS API version (e.g., "v10").
page_size	int	Number of records to fetch per API request.
include_entities	t.StrSequence	Explicit list of WMS entities to discover.

Sources: src/flext_tap_oracle_wms/settings.py:20-75, meltano.yml:43-120

Validation Logic

The type system implements multiple layers of validation:

1. Structural Validation: Ensuring types match (e.g., page_size is an integer).
2. Format Validation: Using regex to ensure start_date and end_date follow ISO 8601 patterns.
3. Business Rule Validation: Logic to prevent conflicting configurations, such as an entity being present in both include_entities and exclude_entities.

def validate_business_rules(self) -> p.Result[bool]:
    overlap = set(self.include_entities) & set(self.exclude_entities)
    if overlap:
        return r[bool].fail(f"Entities {overlap} cannot be both included and excluded")
    if self.start_date and self.end_date and self.start_date > self.end_date:
        return r[bool].fail("start_date must be <= end_date")
    return r[bool].ok(True)

Sources: src/flext_tap_oracle_wms/settings.py:157-167, tests/unit/test_config.py:141-160

Type Mapping & Singer Integration

The module translates Oracle WMS internal data types into Singer-compliant JSON schemas. This allows for seamless integration with different targets (Postgres, Snowflake, etc.) within the Meltano/Singer ecosystem.

Type Conversion Flow

The following diagram illustrates how the system processes configuration into valid runtime settings.

The flow ensures that only validated settings reach the FlextTapOracleWms class.

Sources: src/flext_tap_oracle_wms/README.md, src/flext_tap_oracle_wms/settings.py:20-25

Domain Models & Entities

The tap discovers various WMS entities and models them as Singer streams. These entities represent core warehouse operations.

Entity Categories

Based on the project configuration, entities are categorized by their operational role:

• Inventory: item, location, inventory, cycle_count
• Orders: order_hdr, order_dtl, shipment, shipment_dtl
• Receiving: receipt, receipt_dtl, asn
• System: company, facility, user

Replication Strategies

The type system defines how data is updated for different models:

Entity	Replication Method	Replication Key
item	FULL_TABLE	N/A
inventory	INCREMENTAL	last_updated_ts
order_hdr	INCREMENTAL	last_updated_ts

Sources: meltano.yml:158-185, meltano.yml:211-215

Module Exports & Lazy Loading

The project uses a lazy loading mechanism to expose data models and types efficiently. The __init__.py file utilizes install_lazy_exports to manage the public surface of the type system.

Public Type Aliases

The system provides several shorthand namespaces for developers:

• m: Models (Pydantic/Singer)
• t: Typings (Type hints, protocols)
• c: Constants (Status codes, default values)
• p: Protocols (Interfaces)

Conclusion

The Data Models & Type System in flext-tap-oracle-wms acts as the project's foundation for reliability and scalability. By centralizing configuration in a Pydantic-based FlextTapOracleWmsSettings model and strictly defining entity replication strategies in meltano.yml, the project maintains a high standard of data integrity. This structured approach facilitates easier refactoring and provides clear contracts for both developers and the Singer ecosystem.

Sources: src/flext_tap_oracle_wms/README.md, pyproject.toml:23-35