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

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. 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 (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.
• 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.

Optional Metadata Attributes

• dimension – An OSIDimension object (typically marking is_time=True) that flags the field as a temporal dimension. Located at OSIField.dimension.
• label – A human-readable string for UI rendering. See OSIField.label.
• description – Free-form documentation explaining the field's business purpose. See OSIField.description.
• ai_context – An OSIAIContextObject or plain string containing AI-generated instructions, synonyms, or examples to assist downstream AI assistants. Defined at OSIField.ai_context.
• custom_extensions – A list of OSICustomExtension objects for vendor-specific metadata (e.g., Snowflake hints). See OSIField.custom_extensions.

Supporting Types for Field Definitions

OSSIE field definitions rely on several supporting Pydantic models defined in the same 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:

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:

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:

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 – 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 – 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}