# How to Configure AI Synonyms for Ossie Fields: A Complete Guide

> Configure AI synonyms for Ossie fields using the ai_context attribute with a synonyms array in the OSIField model. Enhance AI tool references with this guide.

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

---

**AI synonyms for Ossie fields are configured using the `ai_context` attribute with a `synonyms` array in the `OSIField` model, enabling natural-language references for AI tools.**

Apache Ossie enables AI-enhanced metadata management through the **`ai_context`** attribute, which can be attached to any model element. For fields specifically, this mechanism allows you to define alternative natural-language names that AI systems can use to refer to columns. Understanding how to configure AI synonyms for Ossie fields ensures your semantic models are accessible to both human analysts and automated tools.

## Understanding the AI Context Architecture

The synonym configuration relies on two core Pydantic models defined in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py).

First, the **`OSIAIContextObject`** model (lines 49-57) serves as the container for AI metadata. It stores optional `instructions`, `synonyms`, and `examples` for any construct within the Ossie ecosystem.

Second, the **`OSIField`** definition (lines 96-107) includes an optional `ai_context` property of type `OSIAIContextObject`. This is where field-level synonyms are supplied when defining dataset columns or semantic model fields.

The official OSI schema specification in [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md) (lines 575-579) formally declares the `synonyms` property for AI context, describing it as an array of alternative names that AI tools should recognize as equivalent to the field's canonical name.

## Configuring Synonyms in Python

When building Ossie models programmatically, instantiate `OSIAIContextObject` with a tuple or list of synonym strings and assign it to the `ai_context` parameter of `OSIField`.

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

field = OSIField(
    name="order_date",
    expression=OSIExpression(
        dialects=[OSIDialectExpression(dialect="ANSI_SQL", expression="order_date")]
    ),
    dimension={"is_time": True},
    ai_context=OSIAIContextObject(
        synonyms=("order date", "date of purchase", "transaction day")
    ),
)

```

The `synonyms` parameter accepts any iterable of strings. Pydantic deserializes this into the model when parsing Ossie documents.

## Configuring Synonyms in YAML

For declarative configuration, add an `ai_context` block containing a `synonyms` list under any field definition. The official example in [`examples/tpcds_semantic_model.yaml`](https://github.com/apache/ossie/blob/main/examples/tpcds_semantic_model.yaml) demonstrates this pattern for the `ss_sold_date_sk` field (lines 56-59).

```yaml
- name: order_date
  expression:
    dialects:
      - dialect: ANSI_SQL
        expression: order_date
  dimension:
    is_time: true
  ai_context:
    synonyms:
      - "order date"
      - "date of purchase"
      - "transaction day"

```

This YAML structure maps directly to the `OSIAIContextObject` model. The `ss_sold_date_sk` field in the TPC-DS example uses synonyms like "sale date" and "transaction date" to provide AI systems with contextual alternatives to the technical column name.

## How Synonyms Are Processed

When Ossie documents are parsed, the `ai_context` (including synonyms) is deserialized by Pydantic into the model objects. Converters and integrations extract these values through dedicated helper methods.

For example, the Snowflake YAML converter uses the **`_extract_synonyms`** helper function to retrieve synonym lists from field definitions. According to the test suite in [`converters/snowflake/tests/test_osi_to_snowflake_yaml_converter.py`](https://github.com/apache/ossie/blob/main/converters/snowflake/tests/test_osi_to_snowflake_yaml_converter.py) (lines 54-75), this function returns a copy of the list when present, otherwise `None`. This ensures downstream AI tools receive clean, immutable arrays of alternative field names.

## Summary

- **AI synonyms** are configured via the `ai_context` attribute on `OSIField` instances in Apache Ossie.
- The **`OSIAIContextObject`** model in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py) stores the `synonyms` array along with optional instructions and examples.
- You can define synonyms **programmatically** using Python Pydantic models or **declaratively** in YAML configuration files.
- The official specification in [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md) defines the schema for the `synonyms` property as an array of alternative natural-language names.
- Converters like the Snowflake implementation use `_extract_synonyms` to retrieve these values for AI tool integration.

## Frequently Asked Questions

### What is the purpose of AI synonyms in Ossie?

AI synonyms provide alternative natural-language names for technical fields, allowing AI tools and large language models to understand user queries that reference columns by common business terms rather than exact database column names. This bridges the gap between technical schemas and business vocabulary.

### Can I add synonyms to elements other than fields?

Yes. While this article focuses on field configuration, the `ai_context` attribute can be attached to any model element in Ossie, including semantic models, datasets, relationships, and metrics. All these constructs use the same `OSIAIContextObject` model defined in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py).

### How are synonyms validated during parsing?

Synonyms are validated by Pydantic during deserialization of the `OSIAIContextObject` model. The `synonyms` field accepts an array of strings. If the YAML or Python code contains non-string values or malformed structures, Pydantic raises validation errors before the model is instantiated.

### Are synonyms used by all Ossie converters?

Not all converters utilize synonyms, but they are available to any integration that chooses to implement them. The Snowflake converter demonstrates this pattern with its `_extract_synonyms` helper function in [`converters/snowflake/tests/test_osi_to_snowflake_yaml_converter.py`](https://github.com/apache/ossie/blob/main/converters/snowflake/tests/test_osi_to_snowflake_yaml_converter.py), which extracts synonyms for AI-specific YAML generation.