M↓ View as Markdown ↗

Open Semantic Interchange Format

Actian AI Analyst can export a Workspace's models and metrics in the Open Semantic Interchange (OSI) format, so you can share them with other BI, analytics and AI tools. You can also import OSI files. See Import OSI Format.

To create an OSI file, go to Settings → Import / export, click Export and choose Open Semantic Interchange. See Export Semantic Layer & Agents.

What is OSI?

OSI is a vendor-neutral, open specification for exchanging semantic models. AI Analyst targets OSI core specification version 0.1.1.

How AI Analyst maps to OSI

An OSI export is a single YAML file with one semantic_model entry.

AI Analyst	OSI	Notes
Workspace	semantic_model	name is an internal name, not the Workspace name.
Model	datasets	One dataset per model, with name and description.
Model source	datasets.source	<data connection>.<schema>.<table> for a table, or the SQL text for a custom-query model.
Model agent guidance	datasets.ai_context.instructions
Dimensions and measures	datasets.fields	Each field has only name and expression. Dimensions and measures are listed together.
Data connection name	datasets.custom_extensions	An entry with vendor_name: AI_ANALYST whose data is a JSON string such as {"data_source_name":"mydb"}. AI Analyst uses it when you import the file again.
Relationship	relationships	name, from, to, from_columns and to_columns.
Metric	metrics	name, description, expression.dialects with an ANSI_SQL expression, and ai_context.instructions (the metric's agent guidance).

What's not exported in OSI

OSI is a lightweight interchange format. An OSI export leaves out:

• Glossary terms.
• AI analysts.
• Model filters.
• Model grain and primary keys.
• Dimension and measure descriptions, dimension types, time grains, enum values and sample values.
• Measure units and precision.
• Relationship types (cardinality) and join types.
• A metric's anchor model, time dimension, time grains, joins, unit and precision.

Info

For complete backups that preserve all details, use the Lossless format instead (see Actian AI Analyst Lossless Format).

Example OSI file

semantic_model:
  - name: Production
    datasets:
      - name: orders
        source: mydb.analytics.orders
        description: Order transactions
        ai_context:
          instructions: Use for order questions
        fields:
          - name: order_date
            expression: order_date
          - name: total_amount
            expression: SUM(amount)
        custom_extensions:
          - vendor_name: AI_ANALYST
            data: '{"data_source_name":"mydb"}'
    relationships:
      - name: orders_to_customers
        from: orders
        to: customers
        from_columns: [customer_id]
        to_columns: [id]
    metrics:
      - name: total_revenue
        description: Total revenue
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: SUM(orders.amount)
        ai_context:
          instructions: ""

The file has no header comments. Values are illustrative.

Re-importing an OSI export

Because each dataset names its data connection in the AI_ANALYST extension, you can import an OSI export back into AI Analyst through Settings → Import / export. Only models, relationships and metrics are imported, and the details listed above are not restored. See Import OSI Format for how the import works.