# Structure for Defining Fields in Apache Ossie: The OSIField Model Guide

> Learn the OSIField model structure for defining fields in Apache Ossie. Discover name, expression, time dimensions, AI context, labels, and extensions.

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

---

**In Apache Ossie, fields are defined using the `OSIField` Pydantic model, which requires a `name` identifier and a dialect-aware `expression`, while optionally supporting time dimensions, AI context, labels, and vendor-specific extensions.**

The structure for defining fields in Ossie centers on the `OSIField` class located in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py). This model enables semantic portability across analytics platforms by encapsulating both the logical definition of a row-level attribute and its physical implementation across query languages like Snowflake SQL and MDX. Each field serves as a reusable component for grouping, filtering, or metric calculations within an OSSIE semantic document.

## Core Components of the OSIField Model

The `OSIField` definition in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py) (starting at line 101) consists of two required fields and five optional metadata attributes.

### Required Fields

Every Ossie field must declare:

- **`name`** – The string identifier used to reference the field within datasets. Defined at [`OSIField.name`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py#L101).
- **`expression`** – An `OSIExpression` object containing one or more `OSIDialectExpression` instances that specify how to compute the field's value per target language. Defined at [`OSIField.expression`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py#L102).

### Optional Metadata Attributes

- **`dimension`** – An `OSIDimension` object (typically marking `is_time=True`) that flags the field as a temporal dimension. Located at [`OSIField.dimension`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py#L103).
- **`label`** – A human-readable string for UI rendering. See [`OSIField.label`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py#L104).
- **`description`** – Free-form documentation explaining the field's business purpose. See [`OSIField.description`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py#L105).
- **`ai_context`** – An `OSIAIContextObject` or plain string containing AI-generated instructions, synonyms, or examples to assist downstream AI assistants. Defined at [`OSIField.ai_context`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py#L106).
- **`custom_extensions`** – A list of `OSICustomExtension` objects for vendor-specific metadata (e.g., Snowflake hints). See [`OSIField.custom_extensions`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py#L107).

## Supporting Types for Field Definitions

OSSIE field definitions rely on several supporting Pydantic models defined in the same [`models.py`](https://github.com/apache/ossie/blob/main/models.py) file.

### OSIExpression and OSIDialectExpression

The `OSIExpression` class (lines 80-86) acts as a container for multiple dialect-specific implementations. It holds a list of `OSIDialectExpression` objects (lines 71-78), each pairing a `dialect` enum member (e.g., `OSIDialect.SNOWFLAKE` or `OSIDialect.MDX`) with the raw `expression` string. This architecture allows a single logical field to translate natively across different database engines.

### OSIDimension

The `OSIDimension` model (lines 88-94) currently captures a boolean `is_time` property. When `is_time=True`, the field is treated as a time dimension for time-series analysis and date hierarchy navigation.

### OSIAIContextObject and OSICustomExtension

For AI-assisted analytics, the `OSIAIContextObject` (lines 49-57) structures optional `instructions`, `synonyms`, and `examples`. For vendor-specific extensions, `OSICustomExtension` (lines 62-68) stores a `vendor_name` and serialized JSON `data` string, enabling platform-specific optimizations without breaking cross-platform compatibility.

## Practical Field Definition Examples

The following examples demonstrate how to construct `OSIField` instances for common scenarios.

### Simple Aggregated Field

Define a basic metric with a single Snowflake SQL expression:

```python
from ossie.models import OSIField, OSIExpression, OSIDialectExpression, OSIDialect

field = OSIField(
    name="order_total",
    expression=OSIExpression(
        dialects=[
            OSIDialectExpression(
                dialect=OSIDialect.SNOWFLAKE,
                expression="SUM(order_amount)"
            )
        ]
    ),
    label="Order Total",
    description="Aggregated order amount per row."
)

```

### Multi-Dialect Time Dimension

Create a date field supporting both SQL and MDX dialects while marking it as temporal:

```python
from ossie.models import (
    OSIField,
    OSIExpression,
    OSIDialectExpression,
    OSIDialect,
    OSIDimension,
)

field = OSIField(
    name="order_date",
    expression=OSIExpression(
        dialects=[
            OSIDialectExpression(
                dialect=OSIDialect.SNOWFLAKE,
                expression="order_timestamp::DATE"
            ),
            OSIDialectExpression(
                dialect=OSIDialect.MDX,
                expression="[Order].[Order Date].CurrentMember.Member_Value"
            ),
        ]
    ),
    dimension=OSIDimension(is_time=True),
    label="Order Date",
    description="Date component of the order timestamp."
)

```

### AI-Enriched Field with Custom Extensions

Add AI context and Snowflake-specific metadata to a segmentation field:

```python
from ossie.models import (
    OSIField,
    OSIExpression,
    OSIDialectExpression,
    OSIDialect,
    OSIAIContextObject,
    OSICustomExtension,
)

field = OSIField(
    name="customer_segment",
    expression=OSIExpression(
        dialects=[
            OSIDialectExpression(
                dialect=OSIDialect.SNOWFLAKE,
                expression="CASE WHEN revenue > 10000 THEN 'VIP' ELSE 'Regular' END"
            )
        ]
    ),
    ai_context=OSIAIContextObject(
        instructions="Use this field for segment-based cohort analysis.",
        synonyms=["segment", "group"]
    ),
    custom_extensions=[
        OSICustomExtension(
            vendor_name="SNOWFLAKE",
            data='{"comment":"Generated via Snowflake UDF"}'
        )
    ]
)

```

## Key Implementation Files

Understanding the structure for defining fields in Ossie requires familiarity with these source files:

- **[`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py)** – Contains the core `OSIField` definition (line 101) and all supporting types including `OSIExpression` (lines 80-86), `OSIDialectExpression` (lines 71-78), and `OSIDimension` (lines 88-94).
- **[`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py)** – Implements schema validation logic that enforces OSSIE compliance when loading field definitions from YAML or JSON documents.
- **`converters/*/src/*`** – Directory containing platform-specific converters that translate `OSIField` instances into target artifacts such as DBT models, GoodData LDM, or native Snowflake SQL.

## Summary

- The **structure for defining fields in Ossie** relies on the `OSIField` Pydantic model, requiring a `name` and `expression` while supporting optional metadata.
- **Expressions are dialect-aware** through the `OSIExpression` container, enabling multi-platform deployment from a single definition.
- **Time dimensions** are flagged via the `OSIDimension` object with `is_time=True`.
- **AI context** and **custom extensions** provide extensibility for AI assistants and vendor-specific optimizations without breaking portability.

## Frequently Asked Questions

### What is the minimum required configuration for an Ossie field?

The absolute minimum requires two fields: `name` (a string identifier) and `expression` (an `OSIExpression` object containing at least one `OSIDialectExpression`). All other attributes—including `label`, `description`, and `dimension`—are optional according to the `OSIField` definition in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py).

### How does Ossie handle different SQL dialects for the same field?

Ossie uses the `OSIExpression` class to hold multiple `OSIDialectExpression` objects, each mapping a specific dialect enum (e.g., `OSIDialect.SNOWFLAKE`, `OSIDialect.MDX`) to its corresponding expression string. During conversion, the appropriate dialect expression is selected based on the target platform specified in the converter.

### Can I add vendor-specific hints to an Ossie field without breaking cross-platform compatibility?

Yes. Use the `custom_extensions` field, which accepts a list of `OSICustomExtension` objects. Each extension specifies a `vendor_name` and serialized JSON `data`, allowing you to embed platform-specific metadata (like Snowflake comments or indexing hints) while maintaining a valid OSSIE schema that other converters can ignore safely.

### What is the purpose of the `ai_context` field in OSIField?

The `ai_context` field accepts either a plain string or an `OSIAIContextObject` containing structured `instructions`, `synonyms`, and `examples`. This metadata helps downstream AI assistants understand the semantic purpose of the field, improving natural language querying and automated documentation generation without affecting the physical query execution.