# How Fields Are Represented in Apache Ossie: A Complete Guide to the Data Model

> Learn how Apache Ossie represents fields using a hierarchical class system. Discover the base Field class and concrete types like StringField and IntegerField for robust data modeling.

- Repository: [The Apache Software Foundation/ossie](https://github.com/apache/ossie)
- Tags: how-to-guide
- Published: 2026-07-24

---

**Apache Ossie represents data fields through a hierarchical class system defined in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py), where a base `Field` class stores metadata and validation logic while concrete implementations like `StringField` and `IntegerField` enforce type-specific constraints.**

Apache Ossie uses a declarative field system to define data schemas across its converter ecosystem. The field representation architecture centers on the `models` module, which provides the foundation for type safety, validation, and serialization throughout the framework. Understanding how fields are represented is essential for working with Ossie's data transformation engines, including converters for Orion Belt, DBT, and GoodData.

## The Core Field Architecture

### Base Field Class in models.py

The foundation of Ossie's field representation is the `Field` base class located in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py). This class encapsulates the common metadata required for any model attribute, including the field name, data type, default values, and whether the field is required. 

The base class initializes with parameters for `required`, `default`, and constraint keywords, storing these in a `constraints` dictionary for subclass access. Each field instance maintains its own validation rules through the `validate` method, which concrete subclasses override to implement type-specific logic.

### Concrete Field Types

Ossie provides specialized field classes that inherit from the base `Field` class to handle specific data types:

- **StringField**: Stores textual data with optional regex validation and maximum length constraints. Used for attributes like names and identifiers.
- **IntegerField**: Handles whole numbers with support for minimum and maximum range checks.
- **FloatField**: Manages floating-point numbers with optional precision constraints and range validation.
- **BooleanField**: Represents true/false flags with configurable default values.
- **DateTimeField**: Stores timestamps and automatically parses ISO-8601 formatted strings.
- **ListField**: Contains ordered collections of another field type, enabling array-like structures.
- **ObjectField**: Embeds nested Ossie models to support hierarchical data structures through composition.

## Field Validation and Constraints

Each concrete field class implements a `validate` method that enforces type safety and constraint checking. When data passes through the system, the `validate` method checks incoming values against the field's configured constraints and raises a `ValidationError` if the data is malformed.

The validation system supports complex constraints such as regex patterns for strings, numeric ranges for integers and floats, and recursive validation for nested `ObjectField` and `ListField` instances. This ensures that data integrity is maintained throughout the serialization and deserialization processes.

## Model Integration and Schema Generation

### Pydantic BaseModel Integration

Field representations in Ossie are built on top of **Pydantic's** `BaseModel` infrastructure, providing automatic type coercion and schema generation capabilities. When you define a model class by subclassing `ossie.models.BaseModel`, class attributes that are instances of field classes automatically become part of the model's schema.

At runtime, Ossie constructs a `__fields__` dictionary on the model class that maps attribute names to their corresponding field instances. This dictionary enables the framework to walk the model structure for serialization tasks, converting model instances into plain Python dictionaries or JSON while applying necessary transformations like date formatting.

### Serialization and Deserialization

The field representation system supports bidirectional data transformation:

1. **Serialization**: Converts model instances into dictionaries or JSON, applying field-specific transformations such as formatting datetime objects as ISO strings.
2. **Deserialization**: Creates model instances from raw data, invoking each field's `validate` logic to enforce type safety before instantiation.

Because the architecture leverages Pydantic, Ossie automatically gains features like nested validation for complex types and OpenAPI-compatible JSON schema generation, which is useful for API documentation across converter implementations.

## Practical Field Implementation

The following example demonstrates how field classes are defined and used within Ossie's architecture:

```python

# python/src/ossie/models.py – simplified illustration

from pydantic import BaseModel, validator
from typing import Any

class Field:
    def __init__(self, *, required: bool = False, default: Any = None, **kwargs):
        self.required = required
        self.default = default
        self.constraints = kwargs

    def validate(self, value):
        # Basic placeholder – concrete subclasses override this

        return value

class StringField(Field):
    def validate(self, value):
        if not isinstance(value, str):
            raise ValueError("must be a string")
        max_len = self.constraints.get("max_length")
        if max_len and len(value) > max_len:
            raise ValueError(f"length exceeds {max_len}")
        return value

class IntegerField(Field):
    def validate(self, value):
        if not isinstance(value, int):
            raise ValueError("must be an integer")
        min_val = self.constraints.get("min")
        max_val = self.constraints.get("max")
        if min_val is not None and value < min_val:
            raise ValueError(f"must be >= {min_val}")
        if max_val is not None and value > max_val:
            raise ValueError(f"must be <= {max_val}")
        return value

# Example model using the field classes

class User(BaseModel):
    name = StringField(required=True, max_length=100)
    age = IntegerField(min=0)
    email = StringField(required=True)
    is_active = BooleanField(default=True)

# Creating an instance – validation runs automatically

user = User(name="Alice", age=30, email="alice@example.com")
print(user.json())

```

This pattern is consistent across all converters in the repository, where field definitions in [`python/src/ossie/__init__.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/__init__.py) expose the public API for downstream implementations.

## Summary

- **Base Class**: All fields inherit from `Field` in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py), which manages metadata and validation interfaces.
- **Type Safety**: Concrete classes like `StringField`, `IntegerField`, and `ObjectField` provide type-specific validation through overridden `validate` methods.
- **Model Schema**: The `__fields__` dictionary automatically maps model attributes to field instances, enabling runtime schema introspection.
- **Pydantic Integration**: Built on Pydantic's `BaseModel`, Ossie fields support automatic serialization, deserialization, and OpenAPI schema generation.
- **Converter Support**: Field definitions are reusable across Ossie's converter ecosystem, ensuring consistent data representation from Orion Belt to GoodData integrations.

## Frequently Asked Questions

### What is the base class for all fields in Apache Ossie?

The base class is `Field`, defined in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py). This class stores common metadata such as `required`, `default`, and constraint parameters, and provides the `validate` method interface that subclasses implement for type-specific checking.

### How does Ossie handle nested data structures?

Ossie uses `ObjectField` to embed nested models and `ListField` to contain ordered collections of other field types. These fields recursively validate their contents, ensuring that nested data maintains type safety throughout the model hierarchy.

### Where are field definitions typically declared in an Ossie project?

Field definitions are declared as class attributes on models that subclass `BaseModel` from `ossie.models`. The public API exposing these classes is located in [`python/src/ossie/__init__.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/__init__.py), which downstream converters import to build their data schemas.

### How does validation work when creating model instances?

When instantiating a model, Ossie walks the `__fields__` dictionary and invokes each field's `validate` method against the provided data. If any validation fails, the system raises a `ValidationError` before the instance is fully created, ensuring only valid data enters the pipeline.