You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ossie.apache.org by jb...@apache.org on 2026/09/01 19:04:47 UTC
(ossie) branch main updated: Adding ontology converters (#147)
This is an automated email from the ASF dual-hosted git repository.
jbonofre pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ossie.git
The following commit(s) were added to refs/heads/main by this push:
new ae3ee40f Adding ontology converters (#147)
ae3ee40f is described below
commit ae3ee40fa5013091b0cc4aa13b231224d7ba86f6
Author: Vadim Mihalovski <10...@users.noreply.github.com>
AuthorDate: Tue Sep 1 21:04:41 2026 +0200
Adding ontology converters (#147)
* Adding ontology Python project to the converters folder
* Updated OSI Spec
* Added `is_component` to the Concept
* Added FormulaFactory protocol as an entry point for some FormulaParser
* Extended FormulaFactory
* Updated OsiParser
* Exclude builtin concepts from top sort
* Added parent for mappings
* Pass SemanticModel parameter to FormulaFactory
* Added MappingFormulaFactory
* Updated OsiParser
* Updated OsiToSpecConverter to emit all non-built-in concepts.
* Emmit only component concepts
* Updated Palantir converter to handle cases where no identifying fields are found
* Added emission of ontology-level requires
* Updated dump_yaml method
* Updated parsers interface + convert top level spec requires
* Refactored after the Copilot code review
* Refactored after the Copilot code review
* Refactored after the Copilot code review
* Added tests
* Updated pyproject.toml file
* Refactored after the Copilot code review
* Refactored after the Copilot code review
* Refactored after the Copilot code review
* Refactored after the internal code review
* Refactored after the Copilot code review
* Migrated to a new flatten Ossie structure
* Addressed review comments
* Make Palantir status handling overridable and tolerate more export shapes
* Fix(ontology): wrong output and conversion aborts in the Palantir converter and shared model.
---------
Co-authored-by: Kurt Stirewalt <ku...@relational.ai>
---
.github/workflows/converter-ontology-ci.yml | 60 +
converters/ontology/.gitignore | 59 +
converters/ontology/README.md | 114 ++
converters/ontology/pyproject.toml | 47 +
converters/ontology/requirements.lock | 21 +
converters/ontology/scripts/palantir_to_ossie.py | 69 ++
converters/ontology/src/ossie_ontology/__init__.py | 91 ++
.../ontology/src/ossie_ontology/common/__init__.py | 16 +
.../src/ossie_ontology/common/file_utils.py | 129 +++
.../ontology/src/ossie_ontology/common/graph.py | 206 ++++
.../ontology/src/ossie_ontology/common/utils.py | 67 ++
.../src/ossie_ontology/converter/__init__.py | 16 +
.../converter/ossie_to_spec/__init__.py | 16 +
.../converter/ossie_to_spec/converter.py | 287 +++++
.../converter/palantir_to_ossie/__init__.py | 16 +
.../converter/palantir_to_ossie/converter.py | 1058 +++++++++++++++++
.../converter/spec_to_ossie/__init__.py | 16 +
.../converter/spec_to_ossie/converter.py | 541 +++++++++
.../src/ossie_ontology/external/__init__.py | 16 +
.../ossie_ontology/external/palantir/__init__.py | 16 +
.../src/ossie_ontology/external/palantir/model.py | 628 ++++++++++
.../external/palantir/parser/__init__.py | 800 +++++++++++++
converters/ontology/src/ossie_ontology/model.py | 1207 +++++++++++++++++++
.../ontology/src/ossie_ontology/parser/__init__.py | 70 ++
converters/ontology/src/ossie_ontology/spec.py | 272 +++++
converters/ontology/tests/__init__.py | 16 +
converters/ontology/tests/conftest.py | 101 ++
converters/ontology/tests/fixtures/flights.yaml | 1111 ++++++++++++++++++
.../flights_roundtrip.yaml | 1180 +++++++++++++++++++
.../flights_structure.txt | 183 +++
converters/ontology/tests/test_concept_lookup.py | 94 ++
converters/ontology/tests/test_examples_in_sync.py | 51 +
converters/ontology/tests/test_flights_snapshot.py | 75 ++
converters/ontology/tests/test_graph.py | 91 ++
converters/ontology/tests/test_ossie_parser.py | 301 +++++
.../ontology/tests/test_palantir_converter.py | 1212 ++++++++++++++++++++
converters/ontology/tests/test_palantir_parser.py | 343 ++++++
converters/ontology/tests/test_roles.py | 91 ++
.../ontology/tests/test_verbalization_parsing.py | 201 ++++
.../ontology/tests/test_verbalization_strings.py | 123 ++
40 files changed, 11011 insertions(+)
diff --git a/.github/workflows/converter-ontology-ci.yml b/.github/workflows/converter-ontology-ci.yml
new file mode 100644
index 00000000..ad9ec3da
--- /dev/null
+++ b/.github/workflows/converter-ontology-ci.yml
@@ -0,0 +1,60 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+name: Converters Ontology CI
+
+on:
+ push:
+ branches: [ "main" ]
+ paths:
+ - 'converters/ontology/**'
+ - '.github/workflows/converter-ontology-ci.yml'
+ pull_request:
+ branches: [ "main" ]
+ paths:
+ - 'converters/ontology/**'
+ - '.github/workflows/converter-ontology-ci.yml'
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ strategy:
+ matrix:
+ python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+ steps:
+ - name: Checkout project
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+ - name: Set up Python ${{ matrix.python-version }}
+ uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: ${{ matrix.python-version }}
+
+ - name: Install dependencies
+ working-directory: converters/ontology
+ run: |
+ python -m pip install --upgrade pip
+ pip install -r requirements.lock
+ pip install -e ".[dev]"
+
+ - name: Unit Tests
+ working-directory: converters/ontology
+ run: |
+ pytest
\ No newline at end of file
diff --git a/converters/ontology/.gitignore b/converters/ontology/.gitignore
new file mode 100644
index 00000000..553c47ac
--- /dev/null
+++ b/converters/ontology/.gitignore
@@ -0,0 +1,59 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# pyenv
+.python-version
+
+# Build / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Mypy
+.mypy_cache/
+
+# Ruff
+.ruff_cache/
+
+# VS Code
+.vscode/
+*.code-workspace
+.history/
+
+# JetBrains (PyCharm, IntelliJ, etc.)
+.idea/
+*.iml
+*.iws
+*.ipr
\ No newline at end of file
diff --git a/converters/ontology/README.md b/converters/ontology/README.md
new file mode 100644
index 00000000..1e7077ee
--- /dev/null
+++ b/converters/ontology/README.md
@@ -0,0 +1,114 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Ossie Ontology Converters
+
+Converters between Ossie, Palantir, and Spec ontology formats.
+
+| Converter | Direction |
+|---------------------|-----------|
+| `palantir_to_ossie` | Palantir ontology → Ossie model |
+| `ossie_to_spec` | Ossie model → Spec YAML |
+| `spec_to_ossie` | Spec YAML → Ossie model |
+
+## Prerequisites
+
+- [pyenv](https://github.com/pyenv/pyenv) — manages the Python version
+
+Install pyenv if you don't have it:
+
+```bash
+brew install pyenv
+```
+
+Add to your shell profile (`~/.zshrc` or `~/.bashrc`) and restart the shell:
+
+```bash
+export PYENV_ROOT="$HOME/.pyenv"
+export PATH="$PYENV_ROOT/bin:$PATH"
+eval "$(pyenv init -)"
+```
+
+## Setup
+
+```bash
+pyenv install 3.11
+pyenv local 3.11
+pip install --upgrade pip
+pip install virtualenv
+python -m virtualenv venv
+source ./venv/bin/activate
+pip install -r requirements.lock
+pip install -e ".[dev]"
+```
+
+## Generating / updating the lock file
+
+`requirements.lock` is produced by [pip-tools](https://github.com/jazzband/pip-tools) from `pyproject.toml`.
+Run this whenever you add or change a dependency:
+
+```bash
+pip-compile --output-file requirements.lock pyproject.toml
+```
+
+## Usage
+
+The package is importable as `ossie_ontology` after installation:
+
+```python
+from ossie_ontology.converter.palantir_to_ossie.converter import PalantirToOssieConverter
+from ossie_ontology.converter.ossie_to_spec.converter import OssieToSpecConverter
+from ossie_ontology.converter.spec_to_ossie.converter import SpecToOssieConverter
+```
+
+## Scripts
+
+### `scripts/palantir_to_ossie.py`
+
+Converts a Palantir ontology export (a `.zip` archive or an already extracted folder containing a Palantir ontology JSON and a `data_sets` folder of one or more dataset spec JSON files) into an Ossie-compliant YAML representation, printed to stdout.
+
+**Usage:**
+
+```bash
+python scripts/palantir_to_ossie.py path/to/palantir_export.zip
+# or an extracted folder:
+python scripts/palantir_to_ossie.py path/to/palantir_export/
+```
+
+Warnings are written to stderr; the Ossie YAML is written to stdout.
+
+**Environment variables (optional):**
+
+| Variable | Default | Description |
+|---------------------------|------------|----------------------------------------------------------|
+| `SNOWFLAKE_DATABASE_NAME` | `PALANTIR` | Snowflake database name used to qualify table references |
+| `SNOWFLAKE_SCHEMA_NAME` | `PALANTIR` | Snowflake schema name used to qualify table references |
+
+If already set in your environment they will be picked up automatically. To override them for a single run:
+
+```bash
+SNOWFLAKE_DATABASE_NAME=MY_DB SNOWFLAKE_SCHEMA_NAME=MY_SCHEMA \
+ python scripts/palantir_to_ossie.py path/to/palantir_export.zip
+```
+
+## Deactivating the environment
+
+```bash
+deactivate
+```
diff --git a/converters/ontology/pyproject.toml b/converters/ontology/pyproject.toml
new file mode 100644
index 00000000..201705d2
--- /dev/null
+++ b/converters/ontology/pyproject.toml
@@ -0,0 +1,47 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[project]
+name = "apache-ossie-ontology"
+version = "0.1.0"
+description = "Ossie ontology converters — Palantir → Ossie, Ossie → Spec, Spec → Ossie"
+readme = "README.md"
+authors = [
+ { name = "RelationalAI", email = "support@relational.ai" },
+]
+requires-python = ">= 3.11"
+dependencies = [
+ "pydantic",
+ "pyyaml",
+]
+
+[project.optional-dependencies]
+dev = [
+ "pytest==9.0.3",
+ "pytest-snapshot",
+ "pip-tools",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.pyright]
+pythonVersion = "3.11"
diff --git a/converters/ontology/requirements.lock b/converters/ontology/requirements.lock
new file mode 100644
index 00000000..bc25bab0
--- /dev/null
+++ b/converters/ontology/requirements.lock
@@ -0,0 +1,21 @@
+#
+# This file is autogenerated by pip-compile with Python 3.11
+# by the following command:
+#
+# pip-compile --output-file=requirements.lock pyproject.toml
+#
+annotated-types==0.7.0
+ # via pydantic
+pydantic==2.13.4
+ # via apache-ossie-ontology (pyproject.toml)
+pydantic-core==2.46.4
+ # via pydantic
+pyyaml==6.0.3
+ # via apache-ossie-ontology (pyproject.toml)
+typing-extensions==4.15.0
+ # via
+ # pydantic
+ # pydantic-core
+ # typing-inspection
+typing-inspection==0.4.2
+ # via pydantic
diff --git a/converters/ontology/scripts/palantir_to_ossie.py b/converters/ontology/scripts/palantir_to_ossie.py
new file mode 100644
index 00000000..e1166c66
--- /dev/null
+++ b/converters/ontology/scripts/palantir_to_ossie.py
@@ -0,0 +1,69 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Description:
+#
+# This script converts a Palantir ontology export into an Ossie compliant YAML
+# representation of that ontology, using environment variables to configure the
+# Snowflake database and schema names. The export may be supplied either as a
+# zip archive or as an already extracted folder, and must contain:
+# 1. A Palantir ontology (JSON file) and
+# 2. A 'data_sets' folder containing one or more Palantir dataset specs (JSON files)
+#
+# Usage:
+#
+# $ python palantir_to_ossie.py <path_to_zip_or_folder>
+#
+# Environment variables used:
+#
+# - SNOWFLAKE_DATABASE_NAME
+# - SNOWFLAKE_SCHEMA_NAME
+#
+# The tables that populate the ontology are named
+# "{SNOWFLAKE_DATABASE_NAME}.{SNOWFLAKE_SCHEMA_NAME}.{TABLE_NAME}"
+# where TABLE_NAME is the name of a data set that is referenced in
+# the Palantir ontology.
+#
+# Outputs:
+#
+# - stderr: Warnings
+#
+import os
+import sys
+from pathlib import Path
+
+from ossie_ontology.converter.palantir_to_ossie.converter import PalantirToOssieConverter
+from ossie_ontology.converter.ossie_to_spec.converter import OssieToSpecConverter
+
+from ossie_ontology.external.palantir.parser import PalantirParser
+
+if __name__ == "__main__":
+ db_name = os.environ.get("SNOWFLAKE_DATABASE_NAME", "PALANTIR")
+ schema_name = os.environ.get("SNOWFLAKE_SCHEMA_NAME", "PALANTIR")
+
+ if len(sys.argv) != 2:
+ sys.exit(f"Usage: {sys.argv[0]} <path to Palantir sources (.zip or folder)>")
+
+ path = Path(sys.argv[1])
+
+ parser = PalantirParser()
+ palantir_model = parser.parse(path)
+
+ ontology_model = PalantirToOssieConverter().convert(palantir_model, db_name, schema_name)
+
+ ossie_spec = OssieToSpecConverter.convert(ontology_model)
+ print(ossie_spec.dump_yaml())
diff --git a/converters/ontology/src/ossie_ontology/__init__.py b/converters/ontology/src/ossie_ontology/__init__.py
new file mode 100644
index 00000000..9579ef3b
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/__init__.py
@@ -0,0 +1,91 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+Public API surface for ossie.
+
+Consumers should import from here rather than from deep sub-paths.
+"""
+
+from ossie_ontology.model import (
+ Concept,
+ ConceptMapping,
+ ConceptType,
+ CustomExtension,
+ Dataset,
+ DatasetField,
+ DialectExpression,
+ DialectExpressionSet,
+ Formula,
+ FormulaFactory,
+ JoinPath,
+ LinkMapping,
+ Metric,
+ ObjectMapping,
+ OntologyComponent,
+ OntologyMapping,
+ OssieOntology,
+ ReferentMapping,
+ Relationship,
+ RelationshipMultiplicity,
+ Role,
+ SemanticModel,
+)
+from ossie_ontology.spec import OssieSpec
+from ossie_ontology.parser import OssieParser
+from ossie_ontology.external.palantir.parser import PalantirParser
+from ossie_ontology.converter.spec_to_ossie.converter import SpecToOssieConverter
+from ossie_ontology.converter.ossie_to_spec.converter import OssieToSpecConverter
+from ossie_ontology.converter.palantir_to_ossie.converter import PalantirToOssieConverter
+
+__all__ = [
+ # Model — ontology layer
+ "Concept",
+ "ConceptType",
+ "Relationship",
+ "RelationshipMultiplicity",
+ "Role",
+ "Formula",
+ # Model — semantic layer
+ "Dataset",
+ "DatasetField",
+ "DialectExpression",
+ "DialectExpressionSet",
+ "JoinPath",
+ "Metric",
+ "SemanticModel",
+ # Model — mapping layer
+ "ObjectMapping",
+ "ReferentMapping",
+ "LinkMapping",
+ "ConceptMapping",
+ "OntologyMapping",
+ "OntologyComponent",
+ "OssieOntology",
+ # Supporting types
+ "CustomExtension",
+ "FormulaFactory",
+ # Spec DTO
+ "OssieSpec",
+ # Parsers
+ "OssieParser",
+ "PalantirParser",
+ # Converters
+ "SpecToOssieConverter",
+ "OssieToSpecConverter",
+ "PalantirToOssieConverter",
+]
diff --git a/converters/ontology/src/ossie_ontology/common/__init__.py b/converters/ontology/src/ossie_ontology/common/__init__.py
new file mode 100644
index 00000000..13a83393
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/common/__init__.py
@@ -0,0 +1,16 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
diff --git a/converters/ontology/src/ossie_ontology/common/file_utils.py b/converters/ontology/src/ossie_ontology/common/file_utils.py
new file mode 100644
index 00000000..834d6a48
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/common/file_utils.py
@@ -0,0 +1,129 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+import io
+import warnings
+import zipfile
+from pathlib import Path
+from typing import Iterable
+
+
+def iter_json_files_from_dir_in_zip(zf: zipfile.ZipFile, dir_prefix: str) -> Iterable[tuple[str, io.IOBase]]:
+ names = zf.namelist()
+ base_prefix = dir_prefix.rstrip("/") + "/"
+ roots = {n.split("/", 1)[0] for n in names if "/" in n}
+ candidate_prefixes = [base_prefix]
+ if len(roots) == 1:
+ root = next(iter(roots))
+ candidate_prefixes.append(f"{root}/{base_prefix}")
+
+ seen = set()
+ for name in names:
+ if name.endswith("/") or not name.lower().endswith(".json"):
+ continue
+ if any(name.startswith(p) for p in candidate_prefixes):
+ if name in seen:
+ continue
+ seen.add(name)
+ with zf.open(name, "r") as fp:
+ yield name, io.BytesIO(fp.read())
+
+def open_top_level_file_from_zip(zf: zipfile.ZipFile, filename: str) -> io.IOBase:
+ names = set(zf.namelist())
+
+ def _open_to_io_base(n: str) -> io.IOBase:
+ with zf.open(n, "r") as fp:
+ return io.BytesIO(fp.read())
+
+ if filename in names:
+ return _open_to_io_base(filename)
+
+ roots = {n.split("/", 1)[0] for n in names if "/" in n}
+ if len(roots) == 1:
+ candidate = f"{next(iter(roots))}/{filename}"
+ if candidate in names:
+ return _open_to_io_base(candidate)
+
+ raise FileNotFoundError(f"Missing required top-level file: {filename}")
+
+
+# The directory helpers below mirror the ZIP helpers above, but operate on an
+# extracted folder rather than a ZIP archive. Like the ZIP variants, they accept
+# either a folder whose top level directly contains the Palantir files, or a
+# folder wrapping a single root directory that contains them.
+
+def _resolve_dir_root(base_dir: Path) -> Path:
+ """Return the directory that holds the top-level Palantir files.
+
+ Either ``base_dir`` itself, or its single child directory when the export
+ was extracted under one wrapping folder (mirrors the single-root handling
+ used for ZIP archives).
+ """
+ entries = list(base_dir.iterdir())
+ if len(entries) == 1 and entries[0].is_dir():
+ return entries[0]
+ return base_dir
+
+
+def iter_json_files_from_dir(base_dir: Path, dir_prefix: str) -> Iterable[tuple[str, io.IOBase]]:
+ root = _resolve_dir_root(base_dir)
+ data_dir = root / dir_prefix.rstrip("/")
+ if not data_dir.is_dir():
+ return
+ for path in sorted(data_dir.rglob("*")):
+ if path.is_file() and path.suffix.lower() == ".json":
+ # Yield a stable, root-relative name (posix separators) to mirror the
+ # ZIP variant and avoid leaking host-specific absolute paths.
+ name = path.relative_to(root).as_posix()
+ with path.open("rb") as fp:
+ yield name, io.BytesIO(fp.read())
+
+
+def get_top_level_json_file_from_dir(base_dir: Path) -> Path:
+ root = _resolve_dir_root(base_dir)
+ candidates = [
+ p for p in sorted(root.iterdir())
+ if p.is_file() and p.suffix.lower() == ".json"
+ ]
+ if len(candidates) == 0:
+ raise ValueError("Directory must contain exactly one top-level JSON file (none found)")
+ if len(candidates) > 1:
+ raise ValueError("Directory must contain exactly one top-level JSON file (multiple found)")
+ return candidates[0]
+
+
+def validate_dir(base_dir: Path) -> None:
+ """Warn when the extracted folder carries no 'data_sets/' directory.
+
+ Not an error. Object types, properties, keys and links all come from the
+ ontology JSON, so the ontology that results is structurally complete and
+ valid on its own — SDK-extracted exports routinely ship this way.
+
+ What is lost is the weaving: datasets are what tie each concept back to the
+ table behind it, so without them the model has no mappings to any source.
+ It will build and type-check, and every query against it will return no
+ rows. Supply the datasets (or add the mappings by hand) before pointing it
+ at data.
+ """
+ root = _resolve_dir_root(base_dir)
+ if not (root / "data_sets").is_dir():
+ warnings.warn(
+ "Directory contains no 'data_sets' folder. The ontology will be built "
+ "from the ontology JSON alone: valid, but with no mappings connecting "
+ "its concepts to source tables, so queries against it return nothing.",
+ stacklevel=2,
+ )
diff --git a/converters/ontology/src/ossie_ontology/common/graph.py b/converters/ontology/src/ossie_ontology/common/graph.py
new file mode 100644
index 00000000..51cf42cb
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/common/graph.py
@@ -0,0 +1,206 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from __future__ import annotations
+
+import warnings
+from collections import defaultdict
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def topological_sort(nodes: list[T], edges: list[tuple[T, T]]) -> list[T]:
+ order = _topological_sort(nodes, edges)
+ if order is None:
+ raise ValueError("The graph contains a cycle")
+ return order
+
+
+def topological_sort_break_cycles(nodes: list[T], edges: list[tuple[T, T]]) -> tuple[list[T], list[tuple[T, T]]]:
+ order, removed_edges = _topological_sort_break_cycles(nodes, edges)
+ # `order` should always exist; defensive check:
+ if order is None:
+ raise ValueError("Could not break cycles to obtain a topological order")
+
+ return order, removed_edges
+
+
+def is_acyclic_graph(nodes: list[T], edges: list[tuple[T, T]]) -> bool:
+ return _topological_sort(nodes, edges) is not None
+
+
+def _find_cycle_closing_edge_index(
+ nodes: list[T],
+ edge_list: defaultdict[T, list[tuple[T, int]]],
+ active: list[bool],
+ remaining_set: set[T],
+) -> int | None:
+ """
+ Find a cycle in the active subgraph induced by remaining_set and return the
+ index of a "cycle-closing" edge (a back-edge u->v where v is on the recursion stack).
+ """
+ visited: set[T] = set()
+ on_stack: set[T] = set()
+
+ def dfs(u: T) -> int | None:
+ visited.add(u)
+ on_stack.add(u)
+
+ for v, eidx in edge_list.get(u, []):
+ if not active[eidx]:
+ continue
+ if v not in remaining_set:
+ continue
+
+ if v not in visited:
+ found = dfs(v)
+ if found is not None:
+ return found
+ elif v in on_stack:
+ # Back-edge found: u -> v closes a directed cycle
+ return eidx
+
+ on_stack.remove(u)
+ return None
+
+ for start in nodes:
+ if start in remaining_set and start not in visited:
+ found = dfs(start)
+ if found is not None:
+ return found
+
+ return None
+
+
+def _topological_sort_break_cycles(nodes: list[T], edges: list[tuple[T, T]]) -> tuple[list[T] | None, list[tuple[T, T]]]:
+ """
+ Returns (topological_order, removed_edges).
+
+ Strategy:
+ - Run a Kahn-like process.
+ - When it gets stuck, detect a real cycle in the remaining subgraph via DFS
+ and remove the cycle-closing edge (back-edge) from that cycle.
+ - Continue until all nodes can be processed.
+ - Then run a clean topological sort once on the pruned edge list.
+ """
+ node_set = set(nodes)
+
+ edge_list: defaultdict[T, list[tuple[T, int]]] = defaultdict(list)
+ active = [True] * len(edges)
+
+ in_degree: dict[T, int] = {n: 0 for n in nodes}
+ for idx, (src, tgt) in enumerate(edges):
+ if src not in node_set or tgt not in node_set:
+ active[idx] = False
+ continue
+ edge_list[src].append((tgt, idx))
+ in_degree[tgt] += 1
+
+ processed: set[T] = set()
+ removed_edges: list[tuple[T, T]] = []
+
+ work: list[T] = [n for n in nodes if in_degree.get(n, 0) == 0]
+
+ while len(processed) < len(nodes):
+ if work:
+ n = work.pop()
+ if n in processed:
+ continue
+ processed.add(n)
+
+ for neighbour, eidx in edge_list.get(n, []):
+ if not active[eidx]:
+ continue
+ in_degree[neighbour] -= 1
+ if in_degree[neighbour] == 0:
+ work.append(neighbour)
+ continue
+
+ remaining_set = {n for n in nodes if n not in processed}
+
+ edge_idx = _find_cycle_closing_edge_index(
+ nodes=nodes,
+ edge_list=edge_list,
+ active=active,
+ remaining_set=remaining_set,
+ )
+ if edge_idx is None:
+ raise ValueError("Cycle suspected but could not identify a cycle edge to remove")
+
+ src, tgt = edges[edge_idx]
+ active[edge_idx] = False
+ removed_edges.append((src, tgt))
+ warnings.warn(f"Cycle detected: removing cycle-closing edge {src!r} -> {tgt!r}")
+
+ # Update in_degree to reflect edge removal
+ in_degree[tgt] -= 1
+ if in_degree[tgt] == 0:
+ work.append(tgt)
+
+ cleaned_edges = [e for i, e in enumerate(edges) if active[i]]
+ order = _topological_sort(nodes, cleaned_edges)
+ if order is None:
+ raise ValueError("Graph is still cyclic after cycle-breaking edge removals")
+
+ return order, removed_edges
+
+
+def _topological_sort(nodes: list[T], edges: list[tuple[T, T]]) -> list[T] | None:
+ order = []
+
+ # An edge to or from something outside `nodes` constrains no ordering among
+ # them, and leaving it in would stall Kahn's algorithm on a node whose
+ # in-degree nothing can decrement — reported as a cycle, which it is not.
+ # Dropped here as `_topological_sort_break_cycles` drops it, so returning
+ # None means a cycle and the caller keeps the right to say what a dangling
+ # endpoint of its own means.
+ node_set = set(nodes)
+ edges = [(src, tgt) for src, tgt in edges if src in node_set and tgt in node_set]
+
+ # simple implementation of Kahn's Algorithm
+
+ # index edges
+ edge_list = defaultdict(list)
+ for src, tgt in edges:
+ edge_list[src].append(tgt)
+
+ # compute in_degree of nodes
+ in_degree = dict()
+ for _, tgt in edges:
+ if tgt in in_degree:
+ in_degree[tgt] = in_degree[tgt] + 1
+ else:
+ in_degree[tgt] = 1
+
+ # start the working list with nodes that don't have incoming edges
+ work = list(filter(lambda n: n not in in_degree, nodes))
+ while work:
+ n = work.pop()
+ order.append(n)
+ for neighbour in edge_list[n]:
+ new_in_degree = in_degree[neighbour] - 1
+ in_degree[neighbour] = new_in_degree
+ if new_in_degree == 0:
+ work.append(neighbour)
+
+ # all nodes sorted, return the order
+ if len(order) == len(nodes):
+ return order
+
+ # some nodes were not sorted, so the graph is cyclic, return None
+ return None
diff --git a/converters/ontology/src/ossie_ontology/common/utils.py b/converters/ontology/src/ossie_ontology/common/utils.py
new file mode 100644
index 00000000..d3686f12
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/common/utils.py
@@ -0,0 +1,67 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+import logging
+import re
+from keyword import iskeyword
+
+
+def camel_to_snake(name: str) -> str:
+ return re.sub(r'(?<!^)(?=[A-Z])', '_', name).lower()
+
+digit_names = {'0': 'Zero', '1': 'One', '2': 'Two', '3': 'Three', '4': 'Four',
+ '5': 'Five', '6': 'Six', '7': 'Seven', '8': 'Eight', '9': 'Nine'}
+
+def to_pascal_case(text: str) -> str:
+ name = ''.join(capitalize_first(word) for word in re.split(r'[\s_\-\(\)<>:]+', text))\
+ .replace('[', '')\
+ .replace(']', '_')\
+ .replace('&', 'And')
+ # A leading digit is no more legal in a concept name than in a verbalization
+ # string, and this one reaches the formula lexer: spell it out, keeping the
+ # rest pascal-cased ('3m corp' -> 'ThreeMCorp').
+ if name and name[0].isdigit():
+ name = digit_names[name[0]] + capitalize_first(name[1:])
+ return name
+
+def capitalize_first(s):
+ return s[0].upper() + s[1:] if s else s
+
+def to_verbalization_string(verb_string: str) -> str:
+ canonical_name = verb_string.lower().strip()
+ # replace ' ' and '-' with '_'
+ canonical_name = re.sub(r'[-\s]', '_', canonical_name)
+ # drop subsequent '_'
+ canonical_name = re.sub(r'_+', '_', canonical_name)
+ # replace unsupported symbols with '_'
+ new_name = re.sub(r'[^a-zA-Z0-9_-]', '_', canonical_name)
+
+ if not new_name:
+ raise ValueError(f"Verbalization string {verb_string!r} reduces to an empty identifier after normalisation")
+
+ if new_name != canonical_name:
+ logging.warning(f"Verbalization string {verb_string} has unsupported symbols. Replacing them with '_'")
+
+ # replace leading digits with alpha; after the comparison above, which is
+ # only about the symbol substitution
+ if new_name[0].isdigit():
+ new_name = digit_names[new_name[0]] + new_name[1:]
+
+ if iskeyword(new_name):
+ new_name = f"{new_name}_k"
+ logging.warning(f"Verbalization string {verb_string} is a reserved keyword. Appending '_k' suffix.")
+ return new_name
diff --git a/converters/ontology/src/ossie_ontology/converter/__init__.py b/converters/ontology/src/ossie_ontology/converter/__init__.py
new file mode 100644
index 00000000..13a83393
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/converter/__init__.py
@@ -0,0 +1,16 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
diff --git a/converters/ontology/src/ossie_ontology/converter/ossie_to_spec/__init__.py b/converters/ontology/src/ossie_ontology/converter/ossie_to_spec/__init__.py
new file mode 100644
index 00000000..13a83393
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/converter/ossie_to_spec/__init__.py
@@ -0,0 +1,16 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
diff --git a/converters/ontology/src/ossie_ontology/converter/ossie_to_spec/converter.py b/converters/ontology/src/ossie_ontology/converter/ossie_to_spec/converter.py
new file mode 100644
index 00000000..f6841f41
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/converter/ossie_to_spec/converter.py
@@ -0,0 +1,287 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Reverse converter: OssieOntology (runtime) -> OssieSpec (Pydantic DTO).
+
+Pairs with spec_to_ossie.SpecToOssieConverter so a full round-trip
+yaml -> spec -> model -> spec -> yaml is structurally stable."""
+
+from __future__ import annotations
+
+from ossie_ontology.model import (
+ Concept,
+ ConceptMapping,
+ ConceptType,
+ CustomExtension,
+ Dataset,
+ DatasetField,
+ DialectExpressionSet,
+ Dimension,
+ JoinPath,
+ LinkMapping,
+ SemanticModel,
+ Metric,
+ ObjectMapping,
+ OntologyComponent,
+ OntologyMapping,
+ ReferentMapping,
+ Relationship,
+ OssieOntology,
+)
+from ossie_ontology.spec import (
+ ConceptComponent,
+ ConceptMapping as SpecConceptMapping,
+ CustomExtension as SpecCustomExtension,
+ Dataset as SpecDataset,
+ DatasetField as SpecDatasetField,
+ DialectExpression as SpecDialectExpression,
+ Dimension as SpecDimension,
+ Expression as SpecExpression,
+ JoinPath as SpecJoinPath,
+ LinkMapping as SpecLinkMapping,
+ SemanticModel as SpecSemanticModel,
+ Metric as SpecMetric,
+ ObjectMapping as SpecObjectMapping,
+ OntologyMapping as SpecOntologyMapping,
+ OssieSpec,
+ ReferentMapping as SpecReferentMapping,
+ Relationship as SpecRelationship,
+ Role as SpecRole,
+)
+
+
+class OssieToSpecConverter:
+ """Top-level reverse converter."""
+
+ @staticmethod
+ def convert(model: OssieOntology) -> OssieSpec:
+ ont = model.ontology
+ ontology_mappings = [_convert_ontology_mapping(ontology_mapping) for ontology_mapping in model.ontology_mappings]
+ return OssieSpec(
+ version=model.version,
+ name=model.name,
+ description=model.description,
+ ai_context=model.ai_context,
+ requires=[f.raw_expr for f in ont.requires],
+ ontology=_convert_ontology_concepts(ont),
+ ontology_mappings=ontology_mappings,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Ontology
+# ---------------------------------------------------------------------------
+
+def _convert_ontology_concepts(ont: OntologyComponent) -> list[ConceptComponent]:
+ components: list[ConceptComponent] = []
+ # Group once: `ont.relationships` rebuilds a list on every access, so scanning
+ # it per concept is O(concepts x relationships). Keyed on id() to keep the
+ # identity comparison a per-concept scan would do.
+ by_container: dict[int, list[Relationship]] = {}
+ for rel in ont.relationships:
+ by_container.setdefault(id(rel.container), []).append(rel)
+
+ for concept in ont.concepts():
+ if not concept.is_component:
+ continue
+ components.append(_convert_concept(concept, by_container.get(id(concept), [])))
+ return components
+
+
+def _convert_concept(concept: Concept, rels: list[Relationship]) -> ConceptComponent:
+ type_value: str | None = None
+ if isinstance(concept.type, ConceptType):
+ type_value = concept.type.value # type: ignore[union-attr]
+ extends = [p.name for p in concept.extends] if concept.extends else None
+
+ return ConceptComponent(
+ concept=concept.name,
+ type=type_value, # type: ignore[arg-type]
+ description=concept.description,
+ extends=extends,
+ identify_by=[rel.name for rel in concept.identify_by.values()],
+ derived_by=[f.raw_expr for f in concept.derived_by],
+ requires=[f.raw_expr for f in concept.requires],
+ relationships=[_convert_relationship(rel) for rel in rels],
+ )
+
+
+def _convert_relationship(rel: Relationship) -> SpecRelationship:
+ extra_roles = list(rel.roles)[1:]
+ roles = [SpecRole(concept=role.player.name, name=role.explicit_name) for role in extra_roles]
+
+ multiplicity = rel.multiplicity.value if rel.multiplicity is not None else None
+ verbalizes = rel.verbalizes_raw if rel.verbalizes_raw is not None else []
+
+ return SpecRelationship(
+ name=rel.name,
+ description=rel.description,
+ roles=roles,
+ verbalizes=verbalizes,
+ multiplicity=multiplicity, # type: ignore[arg-type]
+ derived_by=[f.raw_expr for f in rel.derived_by],
+ requires=[f.raw_expr for f in rel.requires],
+ )
+
+
+# ---------------------------------------------------------------------------
+# Semantic model
+# ---------------------------------------------------------------------------
+
+def _convert_semantic_model(semantic_model: SemanticModel) -> SpecSemanticModel:
+ return SpecSemanticModel(
+ name=semantic_model.name,
+ description=semantic_model.description,
+ ai_context=semantic_model.ai_context,
+ datasets=[_convert_dataset(ds) for ds in semantic_model.datasets],
+ relationships=[_convert_join_path(jp) for jp in semantic_model.join_paths],
+ metrics=[_convert_metric(metric) for metric in semantic_model.metrics],
+ custom_extensions=[_convert_custom_extension(ce) for ce in semantic_model.custom_extensions],
+ )
+
+
+def _convert_dataset(ds: Dataset) -> SpecDataset:
+ return SpecDataset(
+ name=ds.name,
+ source=ds.source,
+ primary_key=ds.primary_key,
+ unique_keys=ds.unique_keys,
+ description=ds.description,
+ ai_context=ds.ai_context,
+ fields=[_convert_dataset_field(fl) for fl in ds.fields],
+ custom_extensions=[_convert_custom_extension(ce) for ce in ds.custom_extensions],
+ )
+
+
+def _convert_dataset_field(fl: DatasetField) -> SpecDatasetField:
+ return SpecDatasetField(
+ name=fl.name,
+ expression=_convert_expression(fl.expression),
+ dimension=_convert_dimension(fl.dimension),
+ label=fl.label,
+ description=fl.description,
+ ai_context=fl.ai_context,
+ custom_extensions=[_convert_custom_extension(ce) for ce in fl.custom_extensions],
+ )
+
+
+def _convert_expression(es: DialectExpressionSet) -> SpecExpression:
+ return SpecExpression(
+ dialects=[SpecDialectExpression(dialect=d.dialect, expression=d.expression) for d in es.dialects]
+ )
+
+
+def _convert_dimension(dim: Dimension | None) -> SpecDimension | None:
+ if dim is None:
+ return None
+ return SpecDimension(is_time=dim.is_time)
+
+
+def _convert_join_path(jp: JoinPath) -> SpecJoinPath:
+ return SpecJoinPath(
+ name=jp.name,
+ **{"from": jp.from_dataset.name}, # `from` is a reserved word in Python
+ to=jp.to_dataset.name,
+ from_columns=[from_col.name for from_col in jp.from_columns],
+ to_columns=[to_col.name for to_col in jp.to_columns],
+ ai_context=jp.ai_context,
+ custom_extensions=[_convert_custom_extension(ce) for ce in jp.custom_extensions],
+ )
+
+
+def _convert_metric(metric: Metric) -> SpecMetric:
+ return SpecMetric(
+ name=metric.name,
+ expression=_convert_expression(metric.expression),
+ description=metric.description,
+ ai_context=metric.ai_context,
+ custom_extensions=[_convert_custom_extension(ce) for ce in metric.custom_extensions],
+ )
+
+
+def _convert_custom_extension(ce: CustomExtension) -> SpecCustomExtension:
+ return SpecCustomExtension(vendor_name=ce.vendor_name, data=ce.data)
+
+
+# ---------------------------------------------------------------------------
+# Ontology mapping (tree)
+# ---------------------------------------------------------------------------
+
+def _convert_ontology_mapping(ontology_mapping: OntologyMapping) -> SpecOntologyMapping:
+ return SpecOntologyMapping(
+ name=ontology_mapping.name,
+ description=ontology_mapping.description,
+ semantic_model=_convert_semantic_model(ontology_mapping.semantic_model),
+ concept_mappings=[_convert_concept_mapping(concept_mapping) for concept_mapping in ontology_mapping.concept_mappings],
+ )
+
+
+def _convert_concept_mapping(concept_mapping: ConceptMapping) -> SpecConceptMapping:
+ return SpecConceptMapping(
+ concept=concept_mapping.concept.name,
+ object_mappings=[_convert_object_mapping(object_mapping) for object_mapping in concept_mapping.object_mappings],
+ link_mappings=[_convert_link_mapping(link_mapping) for link_mapping in concept_mapping.link_mappings],
+ )
+
+
+def _convert_object_mapping(object_mapping: ObjectMapping) -> SpecObjectMapping:
+ referent_mappings = None
+ if object_mapping.referent_mappings is not None:
+ referent_mappings = [_convert_referent_mapping(rm) for rm in object_mapping.referent_mappings]
+ return SpecObjectMapping(
+ concept=object_mapping.concept.name if object_mapping.concept is not None else None,
+ expression=_render_mapping_expression(object_mapping.expression),
+ referent_mappings=referent_mappings,
+ )
+
+
+def _convert_referent_mapping(referent_mapping: ReferentMapping) -> SpecReferentMapping:
+ nested = None
+ if referent_mapping.referent_mappings is not None:
+ nested = [_convert_referent_mapping(child) for child in referent_mapping.referent_mappings]
+ return SpecReferentMapping(
+ relationship=referent_mapping.relationship.name,
+ expression=_render_mapping_expression(referent_mapping.expression),
+ referent_mappings=nested,
+ )
+
+
+def _render_mapping_expression(expr) -> str | None:
+ """Reconstruct the source string for a parsed mapping expression. The
+ runtime model carries either a `DatasetField` (single field reference)
+ or a `Formula` (richer expression); both round-trip back to the same
+ string the forward converter saw in the spec."""
+ if expr is None:
+ return None
+ from ossie_ontology.model import DatasetField as _DF, Formula as _F
+ if isinstance(expr, _DF):
+ ds = expr.dataset
+ return f"{ds.name}.{expr.name}" if ds is not None else expr.name
+ if isinstance(expr, _F):
+ return expr.raw_expr
+ return str(expr)
+
+
+def _convert_link_mapping(link_mapping: LinkMapping) -> SpecLinkMapping:
+ children = None
+ if link_mapping.children is not None:
+ children = [_convert_link_mapping(child) for child in link_mapping.children]
+ return SpecLinkMapping(
+ object_mapping=_convert_object_mapping(link_mapping.object_mapping),
+ relationship=link_mapping.relationship.name if link_mapping.relationship is not None else None,
+ children=children,
+ )
diff --git a/converters/ontology/src/ossie_ontology/converter/palantir_to_ossie/__init__.py b/converters/ontology/src/ossie_ontology/converter/palantir_to_ossie/__init__.py
new file mode 100644
index 00000000..13a83393
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/converter/palantir_to_ossie/__init__.py
@@ -0,0 +1,16 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
diff --git a/converters/ontology/src/ossie_ontology/converter/palantir_to_ossie/converter.py b/converters/ontology/src/ossie_ontology/converter/palantir_to_ossie/converter.py
new file mode 100644
index 00000000..c87ef7ac
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/converter/palantir_to_ossie/converter.py
@@ -0,0 +1,1058 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Palantir `Ontology` -> `OssieOntology`."""
+
+from __future__ import annotations
+
+import re
+import warnings
+
+from ossie_ontology.common.graph import topological_sort_break_cycles
+from ossie_ontology.common.utils import to_pascal_case, to_verbalization_string
+from ossie_ontology.external.palantir.model import (
+ ArrayDataType,
+ DataSet as PalantirDataSet,
+ DataSetColumn,
+ DataType,
+ IntermediaryRelation,
+ ManyToManyRelation,
+ ManyToOneRelation,
+ ObjectType,
+ Ontology as PalantirOntology,
+ Property as PalantirProperty,
+ Relation,
+ Resource,
+ Status,
+)
+from ossie_ontology.model import (
+ BUILTIN_CONCEPTS,
+ sanitize_identifier,
+ Concept,
+ ConceptMapping,
+ ConceptType,
+ Dataset,
+ DatasetField,
+ DialectExpression,
+ DialectExpressionSet,
+ Formula,
+ FormulaFactory,
+ LinkMapping,
+ SemanticModel,
+ ObjectMapping,
+ OntologyComponent,
+ OntologyMapping,
+ ReferentMapping,
+ Relationship,
+ RelationshipMultiplicity,
+ OssieOntology
+)
+
+
+_DEFAULT_DIALECT = "ANSI_SQL"
+
+# A column whose name is already an identifier needs no quoting in the emitted SQL.
+_BARE_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+class PalantirToOssieConverter:
+ """Converts a Palantir Ontology to OssieOntology.
+
+ Pass a *formula_factory* to control how Formula objects are created.
+ The default produces plain ``Formula`` instances; downstream packages can
+ inject a factory that returns enriched subclasses (e.g. with an AST).
+
+ model = PalantirToOssieConverter().convert(palantir_ontology)
+ model = PalantirToOssieConverter(formula_factory=my_parser).convert(palantir_ontology)
+ """
+
+ depths_role_names = {1: "fst", 2: "snd", 3: "thd", 4: "frt"}
+
+ OBJECT_TYPE_STATUSES: frozenset = frozenset({Status.ACTIVE, Status.ENDORSED, Status.INTERMEDIARY})
+ PROPERTY_STATUSES: frozenset = frozenset({Status.ACTIVE, Status.EXPERIMENTAL, Status.INTERMEDIARY})
+ MAPPING_PROPERTY_STATUSES: frozenset = frozenset({Status.ACTIVE, Status.INTERMEDIARY})
+ RELATION_STATUSES: frozenset = frozenset({Status.ACTIVE, Status.INTERMEDIARY})
+ RELATION_ENDPOINT_STATUSES: frozenset = frozenset({Status.ACTIVE})
+ SUBTYPE_RELATION_STATUSES: frozenset = frozenset({Status.ACTIVE})
+
+ def allowed_object_type_statuses(self) -> frozenset:
+ """Statuses an object type must have to become a concept."""
+ return self.OBJECT_TYPE_STATUSES
+
+ def allowed_property_statuses(self) -> frozenset:
+ """Statuses a property must have to become a concept relationship."""
+ return self.PROPERTY_STATUSES
+
+ def allowed_mapping_property_statuses(self) -> frozenset:
+ """Statuses a property must have to be wired into a concept mapping."""
+ return self.MAPPING_PROPERTY_STATUSES
+
+ def allowed_relation_statuses(self) -> frozenset:
+ """Statuses a relation must have to be converted outright.
+
+ Separate from this, an EXPERIMENTAL relation is still converted when
+ every object type it connects is allowed by
+ :meth:`allowed_relation_endpoint_statuses`.
+ """
+ return self.RELATION_STATUSES
+
+ def allowed_relation_endpoint_statuses(self) -> frozenset:
+ """Statuses required of the endpoints of an EXPERIMENTAL relation."""
+ return self.RELATION_ENDPOINT_STATUSES
+
+ def allowed_subtype_relation_statuses(self) -> frozenset:
+ """Statuses a relation must have to be read as inheritance.
+
+ Narrower than :meth:`allowed_relation_statuses` by default: an ordinary
+ relation that turns out to be unusable costs one relationship, while a
+ subtype relation restructures the concept graph — the subtype loses its
+ own identifiers and inherits the supertype's — so only settled ones are
+ honoured. As with plain relations, an EXPERIMENTAL subtype relation is
+ still read when both endpoints pass
+ :meth:`allowed_relation_endpoint_statuses`.
+ """
+ return self.SUBTYPE_RELATION_STATUSES
+
+ def _object_type_allowed(self, ot: ObjectType) -> bool:
+ return ot.status() in self.allowed_object_type_statuses()
+
+ def _relation_endpoint_allowed(self, ot: ObjectType) -> bool:
+ return ot.status() in self.allowed_relation_endpoint_statuses()
+
+ @staticmethod
+ def _allowed(resource: Resource, statuses: frozenset) -> bool:
+ return resource.status() in statuses
+
+ def __init__(self, formula_factory: FormulaFactory | None = None):
+ self._formula_factory = formula_factory or FormulaFactory()
+
+ # ------------------------------------------------------------------
+ # Entry point
+ # ------------------------------------------------------------------
+
+ def convert(
+ self,
+ palantir_ontology: PalantirOntology,
+ db_name: str = "palantir",
+ schema_name: str = "palantir",
+ ) -> OssieOntology:
+ ontology = OntologyComponent()
+ model = OssieOntology(name="Palantir model", ontology=ontology, version="0.1.0")
+
+ semantic_model = SemanticModel(name="Palantir semantic model")
+
+ ontology_mapping = OntologyMapping(name="palantir_map", ontology=ontology, semantic_model=semantic_model)
+ model.add_ontology_mapping(ontology_mapping)
+
+ # Per-(concept, dataset) ConceptMappings accumulate here as datasets
+ # get created; emitted into the OntologyMapping at the end so they appear in a stable order.
+ concept_mappings: list[ConceptMapping] = []
+
+ consumed_subtype_relation_ids = self._convert_concepts(
+ ontology, semantic_model, palantir_ontology, concept_mappings, db_name, schema_name
+ )
+ self._convert_relationships(
+ ontology, palantir_ontology, concept_mappings, semantic_model, consumed_subtype_relation_ids
+ )
+
+ for cm in concept_mappings:
+ ontology_mapping.add_concept_mapping(cm)
+
+ return model
+
+ # ------------------------------------------------------------------
+ # Concepts
+ # ------------------------------------------------------------------
+
+ def _subtype_relations(self, palantir_ontology: PalantirOntology) -> dict[ObjectType, ManyToOneRelation]:
+ """The relations to read as inheritance, keyed by the subtype object type.
+
+ Palantir has no subtype construct. Inheritance shows up as a M:1
+ relation whose property map pairs primary key to primary key on both
+ sides: every instance of the one side is an instance of the many side,
+ identified the same way — which is what an Ossie `extends` says. A
+ relation that maps anything else is an ordinary reference and is
+ converted as one.
+
+ Reading it here rather than on the Palantir model keeps the status
+ policy in one place: a converter that admits experimental object types
+ sees the experimental inheritance between them by overriding the same
+ kind of hook it already overrides for everything else.
+ """
+ relation_statuses = self.allowed_subtype_relation_statuses()
+
+ result: dict[ObjectType, ManyToOneRelation] = {}
+ for rel in palantir_ontology.relations().values():
+ if not isinstance(rel, ManyToOneRelation):
+ continue
+
+ one_ot = rel.one_object_type()
+ many_ot = rel.many_object_type()
+
+ allowed = self._allowed(rel, relation_statuses) or (
+ rel.experimental()
+ and self._relation_endpoint_allowed(one_ot)
+ and self._relation_endpoint_allowed(many_ot)
+ )
+ if not allowed:
+ continue
+
+ property_map = rel.property_map()
+ if not property_map:
+ continue
+
+ # Every parent (many-side) primary key must be mapped: _convert_mappings
+ # resolves each of them through property_map, so a partially mapped
+ # composite key would raise a bare KeyError there. It is also the more
+ # accurate reading — identity carried over in part is an ordinary FK.
+ is_subtype = all(
+ mprop in many_ot.primary_keys() and oprop in one_ot.primary_keys()
+ for mprop, oprop in property_map.items()
+ ) and all(pk in property_map for pk in many_ot.primary_keys())
+
+ if is_subtype:
+ result[one_ot] = rel
+
+ return result
+
+ def _convert_concepts(
+ self,
+ ontology: OntologyComponent,
+ semantic_model: SemanticModel,
+ palantir_ontology: PalantirOntology,
+ concept_mappings: list[ConceptMapping],
+ db_name: str,
+ schema_name: str,
+ ) -> set[str]:
+ """Convert the object types, returning the relations read as inheritance.
+
+ The returned guids are what `_convert_relationships` must leave alone:
+ they are already carried by an `extends` and would otherwise be emitted
+ a second time as ordinary references. This is narrower than
+ `_subtype_relations()` — a subtype edge dropped below to break a cycle,
+ or one whose concept was already converted, stays an ordinary relation —
+ so only this method can say which ones were actually consumed.
+ """
+ subtype_relations = self._subtype_relations(palantir_ontology)
+
+ nodes = [ot.guid() for ot in palantir_ontology.object_types().values()]
+ edges: list[tuple[str, str]] = []
+ edge_to_relation_guid: dict[tuple[str, str], str] = {}
+ for child, rel in subtype_relations.items():
+ parent = rel.many_object_type()
+ if child == parent:
+ continue
+ edge = (parent.guid(), child.guid())
+ edges.append(edge)
+ edge_to_relation_guid[edge] = rel.guid()
+
+ order, removed_edges = topological_sort_break_cycles(nodes, edges)
+ # Subtype edges that would form cycles get dropped by the topo sort —
+ # treat them as ignored inheritance below.
+ ignore_subtype_relation_ids = {edge_to_relation_guid[e] for e in removed_edges}
+
+ consumed_subtype_relation_ids: set[str] = set()
+ for ot_guid in order:
+ ot = palantir_ontology.object_types()[ot_guid]
+ if self._object_type_allowed(ot):
+ consumed = self._convert_object_type(
+ ontology,
+ semantic_model,
+ ot,
+ subtype_relations,
+ ignore_subtype_relation_ids,
+ concept_mappings,
+ db_name,
+ schema_name,
+ )
+ if consumed is not None:
+ consumed_subtype_relation_ids.add(consumed)
+
+ return consumed_subtype_relation_ids
+
+ def _convert_object_type(
+ self,
+ ontology: OntologyComponent,
+ semantic_model: SemanticModel,
+ ot: ObjectType,
+ subtype_relations: dict[ObjectType, ManyToOneRelation],
+ ignore_subtype_relation_ids: set[str],
+ concept_mappings: list[ConceptMapping],
+ db_name: str,
+ schema_name: str,
+ ) -> str | None:
+ """Returns the guid of the relation converted to an `extends`, if any."""
+ concept_name = PalantirToOssieConverter._concept_name(ot)
+ if concept_name in BUILTIN_CONCEPTS:
+ # Nothing good happens if it goes through: the entity takes the
+ # builtin's name, and every column of that builtin type is then typed
+ # by this object type. Reported like any other concept-name collision.
+ raise ValueError(
+ f"ObjectType '{ot.name()}' converts to the concept name '{concept_name}', which is "
+ f"a builtin value type. Rename the object type in the export, or exclude it: a "
+ f"builtin cannot also be an entity type."
+ )
+ relevant_props = [
+ p for p in ot.properties().values()
+ if self._allowed(p, self.allowed_property_statuses())
+ ]
+ concept: Concept | None = None
+ consumed_subtype_relation_id: str | None = None
+
+ if ontology.lookup_concept(concept_name) is None:
+ is_subtype = ot in subtype_relations
+ subtype_relation = subtype_relations.get(ot)
+ ignore_subtype = bool(
+ subtype_relation and subtype_relation.guid() in ignore_subtype_relation_ids
+ )
+
+ if is_subtype and not ignore_subtype:
+ parent_ot = subtype_relation.many_object_type() # type: ignore[union-attr]
+ parent_name = PalantirToOssieConverter._concept_name(parent_ot)
+ parent = ontology.lookup_concept(parent_name)
+ if parent is None:
+ raise ValueError(
+ f"ObjectType '{ot.name()}' is a subtype of '{parent_ot.name()}', but the "
+ f"parent concept '{parent_name}' was not converted — the object-type status "
+ f"policy excluded it while the subtype-relation policy admitted the relation. "
+ f"Widen the allowed object-type statuses, or narrow the subtype-relation "
+ f"statuses, so the two agree."
+ )
+ concept = Concept(name=concept_name, type=ConceptType.ENTITY_TYPE, extends=[parent])
+ consumed_subtype_relation_id = subtype_relation.guid() # type: ignore[union-attr]
+ else:
+ concept = Concept(name=concept_name, type=ConceptType.ENTITY_TYPE)
+ ontology.add_concept(concept)
+
+ for prop in relevant_props:
+ self._convert_property(ontology, concept, prop)
+
+ if not is_subtype or ignore_subtype:
+ identifiers: dict[str, Relationship] = {}
+ # primary_keys() is a set; sort by readable_id so identify_by
+ # ordering (and the resulting YAML) is stable across runs.
+ for prop in sorted(ot.primary_keys(), key=lambda p: p.readable_id()):
+ prop_name = PalantirToOssieConverter._attribute_name(prop)
+ rel = ontology.lookup_concept_relationship(concept, prop_name)
+ if rel is None:
+ raise ValueError(
+ f"Identifier relationship '{concept_name}.{prop_name}' not found "
+ f"while wiring primary keys for ObjectType '{ot.name()}'."
+ )
+ identifiers[rel.full_name] = rel
+ concept.set_identify_by(identifiers)
+ # Set multiplicities now that we know which relationship is the sole identifier.
+ # A non-composite identifier is OneToOne; all others stay ManyToOne.
+ sole = next(iter(identifiers.values())) if len(identifiers) == 1 else None
+ for prop in relevant_props:
+ prop_name = PalantirToOssieConverter._attribute_name(prop)
+ prop_rel = ontology.lookup_concept_relationship(concept, prop_name)
+ if prop_rel is not None:
+ mult = RelationshipMultiplicity.ONE_TO_ONE if prop_rel is sole else RelationshipMultiplicity.MANY_TO_ONE
+ prop_rel.set_multiplicity(mult)
+ else:
+ concept = ontology.lookup_concept(concept_name)
+ assert concept is not None
+ # Re-encountered concept (multiple datasets feeding the same OT).
+ # Verify every relevant property already has its relationship —
+ # otherwise the second dataset is contributing fields the first
+ # didn't declare, which produces an asymmetric model.
+ for prop in relevant_props:
+ prop_name = PalantirToOssieConverter._attribute_name(prop)
+ if ontology.lookup_concept_relationship(concept, prop_name) is None:
+ raise ValueError(
+ f"Concept '{concept_name}' refers to multiple datasets but not all "
+ f"contain the '{prop_name}' property."
+ )
+
+ self._convert_mappings(
+ ontology, semantic_model, ot, subtype_relations, concept, concept_mappings, db_name, schema_name
+ )
+
+ return consumed_subtype_relation_id
+
+ def _convert_property(self, ontology: OntologyComponent, concept: Concept, prop: PalantirProperty) -> None:
+ def madlib_decl(c: Concept, p: PalantirProperty) -> str:
+ return (
+ f"{{{c}}} {p.readable_id()} "
+ f"{PalantirToOssieConverter._type_to_madlib_suffix(p.type())}"
+ )
+
+ prop_name = PalantirToOssieConverter._attribute_name(prop)
+ if ontology.lookup_concept_relationship(concept, prop_name) is not None:
+ return
+
+ relates = self._convert_property_type_roles(ontology, [], prop.type())
+
+ ontology.add_relationship(Relationship(
+ name=prop_name,
+ container=concept,
+ relates=relates,
+ verbalizes=[madlib_decl(concept, prop)],
+ ))
+
+ # ------------------------------------------------------------------
+ # Mappings: ConceptMapping per (concept, dataset)
+ # ------------------------------------------------------------------
+
+ def _convert_mappings(
+ self,
+ ontology: OntologyComponent,
+ semantic_model: SemanticModel,
+ ot: ObjectType,
+ subtype_relations: dict[ObjectType, ManyToOneRelation],
+ concept: Concept,
+ concept_mappings: list[ConceptMapping],
+ db_name: str,
+ schema_name: str,
+ ) -> None:
+ if not ot.has_syncs_from():
+ return
+
+ parent_concept: Concept | None = None
+ subtype_relation = subtype_relations.get(ot)
+
+ if subtype_relation is not None:
+ parent_ot = subtype_relation.many_object_type()
+ parent_concept = ontology.lookup_concept(
+ PalantirToOssieConverter._concept_name(parent_ot)
+ )
+ property_map = subtype_relation.property_map()
+ # primary_keys() is a set; sort by readable_id — as identify_by does
+ # above — so referent_mappings (and the resulting YAML) come out in
+ # the same order on every run.
+ identifier_props = sorted(parent_ot.primary_keys(), key=lambda p: p.readable_id())
+
+ def resolve(p: PalantirProperty) -> PalantirProperty:
+ return property_map[p]
+ else:
+ identifier_props = sorted(ot.primary_keys(), key=lambda p: p.readable_id())
+
+ def resolve(p: PalantirProperty) -> PalantirProperty:
+ return p
+
+ for palantir_ds in ot.syncs_from():
+ dataset = self._convert_dataset(semantic_model, ontology, ot, palantir_ds, db_name, schema_name)
+
+ # Build referent_mappings that locate `concept` instances by
+ # walking the (effective) identifying relationships against this
+ # dataset's columns.
+ id_referents: list[ReferentMapping] = []
+ for prop in identifier_props:
+ prop_name = PalantirToOssieConverter._attribute_name(prop)
+ # For subtypes, identifying relationships live on the parent
+ # concept; the child reaches them via `lookup_concept_relationship`.
+ rel = ontology.lookup_concept_relationship(concept, prop_name)
+ if rel is None:
+ continue
+ field = PalantirToOssieConverter._get_dataset_field_by_palantir_property(
+ resolve(prop), palantir_ds, dataset
+ )
+ if field is None:
+ continue
+ id_referents.append(ReferentMapping(relationship=rel, expression=field))
+
+ if not id_referents:
+ warnings.warn(
+ f"No identifying fields found for concept '{concept.name}' in dataset "
+ f"'{dataset.name}'; skipping concept mapping."
+ )
+ continue
+
+ cm = ConceptMapping(concept=concept)
+
+ # object_mappings: how to construct/identify this concept's
+ # instances from this dataset. Always uses referent_mappings to
+ # walk the identifying relationships (whether own or inherited).
+ cm.object_mappings.append(
+ ObjectMapping(
+ concept=parent_concept,
+ referent_mappings=id_referents,
+ )
+ )
+
+ # link_mappings: the root identifies the source object (same as
+ # object_mapping), children populate each property relationship.
+ children: list[LinkMapping] = []
+ primary_keys = set(ot.primary_keys())
+ for prop in ot.properties().values():
+ if not self._allowed(prop, self.allowed_mapping_property_statuses()):
+ continue
+ if prop in primary_keys:
+ continue
+ if not prop.pk_mapping() and prop.datasource_resource_id() != palantir_ds.guid():
+ continue
+ if isinstance(prop.type(), ArrayDataType):
+ warnings.warn(
+ f"Skipping property '{prop.readable_id()}'. Array datatype is not supported"
+ )
+ continue
+
+ prop_name = PalantirToOssieConverter._attribute_name(prop)
+ relationship = ontology.lookup_concept_relationship(concept, prop_name)
+ if relationship is None:
+ continue
+ field = PalantirToOssieConverter._get_dataset_field_by_palantir_property(
+ prop, palantir_ds, dataset
+ )
+ if field is None:
+ continue
+ value_concept = relationship.last_role.player
+ children.append(
+ LinkMapping(
+ object_mapping=ObjectMapping(concept=value_concept, expression=field),
+ relationship=relationship,
+ )
+ )
+
+ if children:
+ cm.link_mappings.append(
+ LinkMapping(
+ object_mapping=ObjectMapping(
+ concept=parent_concept,
+ referent_mappings=id_referents,
+ ),
+ children=children,
+ )
+ )
+
+ concept_mappings.append(cm)
+
+ # ------------------------------------------------------------------
+ # Relations (M:1, M:M, intermediary)
+ # ------------------------------------------------------------------
+
+ def _convert_relationships(
+ self,
+ ontology: OntologyComponent,
+ palantir_ontology: PalantirOntology,
+ concept_mappings: list[ConceptMapping],
+ semantic_model: SemanticModel,
+ consumed_subtype_relation_ids: set[str],
+ ) -> None:
+ for rel in palantir_ontology.relations().values():
+ # Already converted as an `extends` on the subtype concept; emitting
+ # it here as well would state the same fact twice.
+ if rel.guid() in consumed_subtype_relation_ids:
+ continue
+ if self._allowed(rel, self.allowed_relation_statuses()):
+ self._convert_relation(ontology, rel, concept_mappings, semantic_model)
+ elif (
+ isinstance(rel, ManyToOneRelation)
+ and rel.experimental()
+ and self._relation_endpoint_allowed(rel.one_object_type())
+ and self._relation_endpoint_allowed(rel.many_object_type())
+ ):
+ self._convert_relation(ontology, rel, concept_mappings, semantic_model)
+
+ for ir in palantir_ontology.intermediary_relations().values():
+ if self._allowed(ir, self.allowed_relation_statuses()):
+ self._convert_intermediary_relation(ontology, palantir_ontology, ir)
+ elif (
+ ir.experimental()
+ and self._relation_endpoint_allowed(ir.role_a_player())
+ and self._relation_endpoint_allowed(ir.role_b_player())
+ and self._relation_endpoint_allowed(ir.intermediary_player())
+ ):
+ self._convert_intermediary_relation(ontology, palantir_ontology, ir)
+
+ def _convert_relation(
+ self,
+ ontology: OntologyComponent,
+ relation: Relation,
+ concept_mappings: list[ConceptMapping],
+ semantic_model: SemanticModel,
+ ) -> None:
+ if isinstance(relation, ManyToOneRelation):
+ self._convert_many_to_one(ontology, relation, concept_mappings, semantic_model)
+ elif isinstance(relation, ManyToManyRelation):
+ self._convert_many_to_many(ontology, relation)
+
+ def _add_relationship_if_name_free(
+ self, ontology: OntologyComponent, concept: Concept, relationship: Relationship
+ ) -> bool:
+ """Add *relationship* unless its name is already taken on *concept*.
+
+ `add_relationship` raises on a duplicate name, which would abort the
+ whole conversion over one relation. An export where a property and a link
+ share a name is ordinary — the FK column and the link it backs are often
+ named alike — so the link is dropped and the run continues.
+ `_convert_property` skips the same collision from the other side.
+
+ Renaming instead (suffixing, as `to_verbalization_string` does for
+ keywords) would keep the link, at the cost of emitted names that no
+ longer match the export.
+ """
+ if ontology.lookup_concept_relationship(concept, relationship.name) is not None:
+ warnings.warn(
+ f"Relation '{relationship.full_name}' collides with an existing relationship on "
+ f"the concept (a property and a link, or two links, sharing a name); "
+ f"skipping the link."
+ )
+ return False
+ ontology.add_relationship(relationship)
+ return True
+
+ def _convert_many_to_one(
+ self,
+ ontology: OntologyComponent,
+ rel: ManyToOneRelation,
+ concept_mappings: list[ConceptMapping],
+ semantic_model: SemanticModel,
+ ) -> None:
+ mot = rel.many_object_type()
+ mot_name = PalantirToOssieConverter._concept_name(mot)
+ mot_concept = ontology.lookup_concept(mot_name)
+ oot = rel.one_object_type()
+ oot_name = PalantirToOssieConverter._concept_name(oot)
+ oot_concept = ontology.lookup_concept(oot_name)
+ if mot_concept is None or oot_concept is None:
+ return
+ prop_name = PalantirToOssieConverter._attribute_name(rel)
+
+ if mot_concept is oot_concept:
+ verbalize = f"{{{mot_concept}}} {prop_name} {{{oot_concept}:snd}}"
+ relates: list[tuple[Concept, str | None]] = [(oot_concept, "snd")]
+ else:
+ verbalize = f"{{{mot_concept}}} {prop_name} {{{oot_concept}}}"
+ relates = [(oot_concept, None)]
+
+ relationship = Relationship(
+ name=prop_name,
+ container=mot_concept,
+ relates=relates,
+ verbalizes=[verbalize],
+ multiplicity=RelationshipMultiplicity.MANY_TO_ONE,
+ )
+ if not self._add_relationship_if_name_free(ontology, mot_concept, relationship):
+ return
+
+ if mot.has_syncs_from():
+ self._attach_link_to_concept_mappings(
+ ontology, rel, relationship, mot, mot_concept, oot_concept, concept_mappings, semantic_model
+ )
+ else:
+ # No many-side datasets: fall back to a derived_by formula that
+ # equates FK columns.
+ frags = [
+ f"{relationship.first_role.name}.{PalantirToOssieConverter._attribute_name(mprop)}"
+ f" == {relationship.last_role.name}.{PalantirToOssieConverter._attribute_name(oprop)}"
+ for mprop, oprop in rel.property_map().items()
+ ]
+ if frags:
+ formula = self._formula_factory(raw_expr=" AND ".join(frags), parent=relationship, ontology=ontology)
+ relationship.add_derived_by(formula)
+
+ def _attach_link_to_concept_mappings(
+ self,
+ ontology: OntologyComponent,
+ rel: ManyToOneRelation,
+ relationship: Relationship,
+ mot: ObjectType,
+ mot_concept: Concept,
+ oot_concept: Concept,
+ concept_mappings: list[ConceptMapping],
+ semantic_model: SemanticModel,
+ ) -> None:
+ """For each (mot_concept, dataset) ConceptMapping, append a link_mapping
+ child that walks the target concept's identifying relationships through
+ the source's FK columns."""
+ property_map = rel.property_map()
+ if not property_map:
+ return
+
+ # Resolve target (oot) identifying relationships once.
+ target_id_rels: list[tuple[Relationship, PalantirProperty]] = []
+ for mprop, oprop in property_map.items():
+ oot_attr = PalantirToOssieConverter._attribute_name(oprop)
+ id_rel = ontology.lookup_concept_relationship(oot_concept, oot_attr)
+ if id_rel is None:
+ return
+ target_id_rels.append((id_rel, mprop))
+
+ for palantir_ds in mot.syncs_from():
+ ds_name = (
+ f"{PalantirToOssieConverter._concept_name(mot)}_{palantir_ds.readable_id()}"
+ )
+ dataset = semantic_model.lookup_dataset(ds_name)
+ if dataset is None:
+ continue
+
+ cm = PalantirToOssieConverter._find_concept_mapping(concept_mappings, mot_concept, dataset)
+ if cm is None:
+ warnings.warn(
+ f"No ConceptMapping for entity '{mot_concept.name}' and dataset "
+ f"'{ds_name}'; cannot attach link '{relationship.full_name}'"
+ )
+ continue
+
+ # Build referent_mappings that look up the target via FK columns.
+ referents: list[ReferentMapping] = []
+ resolved = True
+ for id_rel, mprop in target_id_rels:
+ fk_field = PalantirToOssieConverter._get_dataset_field_by_palantir_property(
+ mprop, palantir_ds, dataset
+ )
+ if fk_field is None:
+ resolved = False
+ break
+ referents.append(ReferentMapping(relationship=id_rel, expression=fk_field))
+ if not resolved:
+ continue
+
+ child = LinkMapping(
+ object_mapping=ObjectMapping(concept=oot_concept, referent_mappings=referents),
+ relationship=relationship,
+ )
+ # Attach as a child on the root link_mapping (the identifying tree).
+ if cm.link_mappings:
+ root = cm.link_mappings[0]
+ if root.children is None:
+ root.children = []
+ root.children.append(child)
+ else:
+ if not cm.object_mappings:
+ raise ValueError(
+ f"Cannot attach link '{relationship.full_name}': concept "
+ f"'{mot_concept.name}' has no identifying object mapping "
+ f"to use as the link root."
+ )
+ root_om = cm.object_mappings[0]
+ cm.link_mappings.append(LinkMapping(
+ object_mapping=ObjectMapping(
+ concept=root_om.concept,
+ referent_mappings=root_om.referent_mappings,
+ ),
+ children=[child],
+ ))
+
+ @staticmethod
+ def _find_concept_mapping(
+ concept_mappings: list[ConceptMapping],
+ concept: Concept,
+ dataset: Dataset,
+ ) -> ConceptMapping | None:
+ """Resolve the ConceptMapping built for this (concept, dataset).
+
+ When several datasets feed the same concept there is one ConceptMapping
+ per dataset, and only the one identified by *this* dataset's columns will
+ do: the caller attaches expressions built from this dataset to whatever
+ comes back, so any other mapping would join two unrelated tables. There
+ is no useful second choice, and a concept whose mapping for this dataset
+ was dropped (nothing in it identified the concept) has none at all — so
+ None, and the caller reports the link it cannot attach.
+ """
+ return next(
+ (
+ cm
+ for cm in concept_mappings
+ if cm.concept is concept
+ and PalantirToOssieConverter._references_dataset(cm, dataset)
+ ),
+ None,
+ )
+
+ @staticmethod
+ def _references_dataset(cm: ConceptMapping, dataset: Dataset) -> bool:
+ """True iff an identifying expression in `cm` points to a field of `dataset`.
+
+ Covers both shapes an ObjectMapping identifies objects by — an
+ expression of its own, or referent mappings walking the identifying
+ relationships — since either can be the one naming the dataset.
+ """
+ def is_field_of(expression: DatasetField | Formula | None) -> bool:
+ return isinstance(expression, DatasetField) and expression.dataset is dataset
+
+ return any(
+ is_field_of(om.expression)
+ or any(is_field_of(rm.expression) for rm in (om.referent_mappings or []))
+ for om in cm.object_mappings
+ )
+
+ def _convert_many_to_many(self, ontology: OntologyComponent, rel: ManyToManyRelation) -> None:
+ aot = rel.role_a_player()
+ aot_concept = ontology.lookup_concept(PalantirToOssieConverter._concept_name(aot))
+ bot = rel.role_b_player()
+ bot_concept = ontology.lookup_concept(PalantirToOssieConverter._concept_name(bot))
+ if aot_concept is None or bot_concept is None:
+ return
+ rel_name = PalantirToOssieConverter._attribute_name(rel)
+
+ if aot_concept is bot_concept:
+ verbalize = f"{{{aot_concept}}} {rel_name} {{{bot_concept}:snd}}"
+ relates: list[tuple[Concept, str | None]] = [(bot_concept, "snd")]
+ else:
+ verbalize = f"{{{aot_concept}}} {rel_name} {{{bot_concept}}}"
+ relates = [(bot_concept, None)]
+
+ relationship = Relationship(
+ name=rel_name,
+ container=aot_concept,
+ relates=relates,
+ verbalizes=[verbalize],
+ multiplicity=None,
+ )
+ self._add_relationship_if_name_free(ontology, aot_concept, relationship)
+
+ def _convert_intermediary_relation(
+ self,
+ ontology: OntologyComponent,
+ palantir_ontology: PalantirOntology,
+ rel: IntermediaryRelation,
+ ) -> None:
+ aot = rel.role_a_player()
+ aot_name = PalantirToOssieConverter._concept_name(aot)
+ aot_concept = ontology.lookup_concept(aot_name)
+ bot = rel.role_b_player()
+ bot_name = PalantirToOssieConverter._concept_name(bot)
+ bot_concept = ontology.lookup_concept(bot_name)
+ if aot_concept is None or bot_concept is None:
+ return
+ rel_name = PalantirToOssieConverter._attribute_name(rel)
+
+ if aot_concept is bot_concept:
+ verbalize = f"{{{aot_concept}}} {rel_name} {{{bot_concept}:snd}}"
+ relates: list[tuple[Concept, str | None]] = [(bot_concept, "snd")]
+ else:
+ verbalize = f"{{{aot_concept}}} {rel_name} {{{bot_concept}}}"
+ relates = [(bot_concept, None)]
+
+ relationship = Relationship(
+ name=rel_name,
+ container=aot_concept,
+ relates=relates,
+ verbalizes=[verbalize],
+ )
+ if not self._add_relationship_if_name_free(ontology, aot_concept, relationship):
+ return
+
+ rel_a = palantir_ontology.relations()[rel.relation_a()]
+ rel_a_name = PalantirToOssieConverter._attribute_name(rel_a)
+ rel_b = palantir_ontology.relations()[rel.relation_b()]
+ rel_b_name = PalantirToOssieConverter._attribute_name(rel_b)
+
+ fp_a_ot, sp_a_ot = PalantirToOssieConverter._relation_players(rel_a)
+ fp_a = PalantirToOssieConverter._concept_name(fp_a_ot)
+ sp_a = PalantirToOssieConverter._concept_name(sp_a_ot)
+ fp_b_ot, sp_b_ot = PalantirToOssieConverter._relation_players(rel_b)
+ fp_b = PalantirToOssieConverter._concept_name(fp_b_ot)
+ sp_b = PalantirToOssieConverter._concept_name(sp_b_ot)
+
+ assert (aot_name == fp_a and bot_name == fp_b) or (
+ aot_name == sp_a and bot_name == sp_b
+ ), f"Invalid intermediary relation '{rel_name}' arguments."
+
+ join_condition = (
+ f"{fp_a}.{rel_a_name}({relationship.first_role.name}) AND "
+ f"{fp_b}.{rel_b_name}({relationship.last_role.name})"
+ )
+ formula = self._formula_factory(raw_expr=join_condition, parent=relationship, ontology=ontology)
+ relationship.add_derived_by(formula)
+
+ # ------------------------------------------------------------------
+ # Datasets
+ # ------------------------------------------------------------------
+
+ def _convert_dataset(
+ self,
+ semantic_model: SemanticModel,
+ ontology: OntologyComponent,
+ ot: ObjectType,
+ palantir_ds: PalantirDataSet,
+ db_name: str,
+ schema_name: str,
+ ) -> Dataset:
+ ds_name = f"{PalantirToOssieConverter._concept_name(ot)}_{palantir_ds.readable_id()}"
+ existing = semantic_model.lookup_dataset(ds_name)
+ if existing is not None:
+ return existing
+
+ fields: list[DatasetField] = []
+ for column in palantir_ds.columns():
+ # type() may be None for a partially-specified schema; only ARRAY
+ # columns are skipped, and a missing type falls back to String below.
+ col_type = column.type()
+ if col_type is not None and col_type.upper() == "ARRAY":
+ continue
+ field_name = PalantirToOssieConverter._normalize_field_name(column.name())
+ fields.append(
+ DatasetField(
+ name=field_name,
+ expression=DialectExpressionSet(
+ dialects=[
+ DialectExpression(
+ dialect=_DEFAULT_DIALECT,
+ expression=PalantirToOssieConverter._column_expression(column.name()),
+ )
+ ]
+ ),
+ type=PalantirToOssieConverter._resolve_field_type(ontology, palantir_ds, column),
+ )
+ )
+
+ dataset = Dataset(
+ name=ds_name,
+ source=f"{db_name}.{schema_name}.{palantir_ds.readable_id()}",
+ fields=fields,
+ description=palantir_ds.description(),
+ )
+ semantic_model.add_dataset(dataset)
+ return dataset
+
+ @staticmethod
+ def _resolve_field_type(
+ ontology: OntologyComponent, palantir_ds: PalantirDataSet, column: DataSetColumn
+ ) -> Concept:
+ try:
+ type_str = (
+ DataType.parse_datatype(column.type()).to_type() if column.type() else "String"
+ )
+ except ValueError:
+ # A type this export spells differently, or one Palantir has added:
+ # the same fallback a column with no type at all already takes.
+ warnings.warn(
+ f"Unrecognized column type '{column.type()}' on "
+ f"'{palantir_ds.readable_id()}.{column.name()}'; falling back to String."
+ )
+ type_str = "String"
+
+ concept = ontology.ensure_builtin_concept(type_str)
+ if not concept:
+ raise ValueError(
+ f"Concept '{type_str}' is not defined in the ontology but used in the "
+ f"DatasetField '{palantir_ds.readable_id()}.{column.name()}'."
+ )
+ return concept
+
+ # ------------------------------------------------------------------
+ # Naming / typing helpers
+ # ------------------------------------------------------------------
+
+ @staticmethod
+ def _attribute_name(prop: PalantirProperty | Relation) -> str:
+ return to_verbalization_string(prop.readable_id())
+
+ @staticmethod
+ def _concept_name(ot: ObjectType) -> str:
+ return to_pascal_case(ot.name())
+
+ @staticmethod
+ def _type_to_madlib_suffix(type_, arr_depth: int = 1) -> str:
+ if isinstance(type_, ArrayDataType):
+ depth = arr_depth
+ return (
+ f"{{Integer:{PalantirToOssieConverter._depth_role_name(depth)}}} maps to "
+ f"{PalantirToOssieConverter._type_to_madlib_suffix(type_.base_type(), depth + 1)}"
+ )
+ return f"{{{type_.to_type()}}}"
+
+ def _convert_property_type_roles(
+ self, ontology: OntologyComponent, roles: list[tuple[Concept, str | None]], type_, arr_depth: int = 1
+ ) -> list[tuple[Concept, str | None]]:
+ if isinstance(type_, ArrayDataType):
+ integer = ontology.ensure_builtin_concept("Integer")
+ if integer is None:
+ raise ValueError("Builtin 'Integer' could not be resolved for array role.")
+ roles.append((integer, PalantirToOssieConverter._depth_role_name(arr_depth)))
+ self._convert_property_type_roles(ontology, roles, type_.base_type(), arr_depth + 1)
+ else:
+ target = ontology.ensure_builtin_concept(type_.to_type())
+ if target is None:
+ raise ValueError(
+ f"Type concept '{type_.to_type()}' is not defined in the ontology."
+ )
+ roles.append((target, None))
+ return roles
+
+ @staticmethod
+ def _relation_players(rel: Relation) -> tuple[ObjectType, ObjectType]:
+ """Return the (first, second) role-player object types of a binary
+ relation, regardless of its concrete relation type."""
+ if isinstance(rel, ManyToOneRelation):
+ return rel.many_object_type(), rel.one_object_type()
+ if isinstance(rel, (ManyToManyRelation, IntermediaryRelation)):
+ return rel.role_a_player(), rel.role_b_player()
+ raise ValueError(
+ f"Unsupported relation type '{type(rel).__name__}' for relation {rel.readable_id()}"
+ )
+
+ @staticmethod
+ def _depth_role_name(depth: int) -> str:
+ name = PalantirToOssieConverter.depths_role_names.get(depth)
+ if not name:
+ raise ValueError(f"Array types of depth {depth} are not supported")
+ return name
+
+ @staticmethod
+ def _get_dataset_field_by_palantir_property(
+ prop: PalantirProperty, palantir_ds: PalantirDataSet, dataset: Dataset
+ ) -> DatasetField | None:
+ column_name = prop.column_name()
+ pk_mapping = prop.pk_mapping()
+ ds_guid = palantir_ds.guid()
+ if pk_mapping:
+ if ds_guid not in pk_mapping:
+ raise ValueError(
+ f"Primary key mapping for Palantir DataSet '{palantir_ds.readable_id()}' "
+ f"is missing property '{PalantirToOssieConverter._attribute_name(prop)}'"
+ )
+ column_name = pk_mapping[ds_guid]
+ if not column_name:
+ return None
+ normalized = PalantirToOssieConverter._normalize_field_name(column_name)
+ field = dataset.field(normalized)
+ if not field:
+ # Fall back to a case-insensitive match. The two halves of an export
+ # routinely disagree on case — `primaryKeyMapping` names the physical
+ # warehouse column (`LOCNO`) while the property carries the API
+ # spelling (`locno`) — and an unquoted Snowflake identifier is
+ # case-insensitive anyway, so treating them as distinct only loses
+ # the mapping. Exact match still wins, so a source that genuinely
+ # relies on quoted, case-sensitive columns is unaffected.
+ lowered = normalized.lower()
+ field = next((f for f in dataset.fields if f.name.lower() == lowered), None)
+ if not field:
+ warnings.warn(f"Dataset '{dataset.name}' does not contain a field named '{column_name}'")
+ return field
+
+ @staticmethod
+ def _normalize_field_name(name: str) -> str:
+ """A dataset field name that is a usable identifier.
+
+ Everything a bare identifier cannot hold — spaces, dots, dashes, quotes —
+ becomes `_`, because a mapping expression naming this field is matched
+ against an identifier pattern when the spec is read back, and a field
+ name that fails it is silently taken for a formula instead of resolving
+ to the field.
+ """
+ normalized = sanitize_identifier(name)
+ if normalized and normalized[0].isdigit():
+ normalized = f"_{normalized}"
+ return normalized
+
+ @staticmethod
+ def _column_expression(column_name: str) -> str:
+ """The SQL reading this physical column.
+
+ Separate from the field name above: that one is sanitized and so may no
+ longer spell the column, while this has to go on naming it exactly —
+ quoted when the name is not a bare identifier.
+ """
+ if _BARE_IDENTIFIER_RE.match(column_name):
+ return column_name
+ escaped = column_name.replace('"', '""')
+ return f'"{escaped}"'
diff --git a/converters/ontology/src/ossie_ontology/converter/spec_to_ossie/__init__.py b/converters/ontology/src/ossie_ontology/converter/spec_to_ossie/__init__.py
new file mode 100644
index 00000000..13a83393
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/converter/spec_to_ossie/__init__.py
@@ -0,0 +1,16 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
diff --git a/converters/ontology/src/ossie_ontology/converter/spec_to_ossie/converter.py b/converters/ontology/src/ossie_ontology/converter/spec_to_ossie/converter.py
new file mode 100644
index 00000000..0b45ea8a
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/converter/spec_to_ossie/converter.py
@@ -0,0 +1,541 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Converter from OssieSpec (Pydantic DTOs) to OssieOntology (runtime semantic model)."""
+
+from __future__ import annotations
+
+import re
+
+from ossie_ontology.common.graph import topological_sort
+from ossie_ontology.model import (
+ Concept,
+ ConceptMapping,
+ ConceptType,
+ CustomExtension,
+ Dataset,
+ DatasetField,
+ DialectExpression,
+ DialectExpressionSet,
+ Dimension,
+ Formula,
+ FormulaFactory,
+ MappingFormulaFactory,
+ JoinPath,
+ LinkMapping,
+ SemanticModel,
+ Metric,
+ ObjectMapping,
+ OntologyComponent,
+ OntologyMapping,
+ ReferentMapping,
+ Relationship,
+ RelationshipMultiplicity,
+ OssieOntology,
+ BUILTIN_CONCEPTS
+)
+from ossie_ontology.spec import (
+ ConceptComponent as SpecConceptComponent,
+ ConceptMapping as SpecConceptMapping,
+ CustomExtension as SpecCustomExtension,
+ Dataset as SpecDataset,
+ DatasetField as SpecDatasetField,
+ DialectExpression as SpecDialectExpression,
+ Dimension as SpecDimension,
+ Expression as SpecExpression,
+ JoinPath as SpecJoinPath,
+ LinkMapping as SpecLinkMapping,
+ SemanticModel as SpecSemanticModel,
+ Metric as SpecMetric,
+ ObjectMapping as SpecObjectMapping,
+ OntologyMapping as SpecOntologyMapping,
+ OssieSpec,
+ ReferentMapping as SpecReferentMapping,
+ Relationship as SpecRelationship,
+)
+Container = Concept | Relationship
+
+# A mapping expression is treated as a single field reference when it matches
+# `DATASET.field` or a bare `field` identifier — no parsing, just a pattern check.
+_QUALIFIED_FIELD_RE = re.compile(r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*\.\s*([A-Za-z_][A-Za-z0-9_]*)\s*$")
+_BARE_FIELD_RE = re.compile(r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*$")
+
+
+class SpecToOssieConverter:
+ """Converts OssieSpec (Pydantic DTOs) to OssieOntology (runtime model).
+
+ Pass a *formula_factory* to control how Formula objects are created.
+ The default produces plain ``Formula`` instances; downstream packages can
+ inject a factory that returns enriched subclasses (e.g. with an AST).
+
+ model = SpecToOssieConverter().convert(spec)
+ model = SpecToOssieConverter(formula_factory=my_parser).convert(spec)
+ """
+
+ def __init__(self, formula_factory: FormulaFactory | None = None,
+ mapping_formula_factory: MappingFormulaFactory | None = None):
+ self._formula_factory = formula_factory or FormulaFactory()
+ self._mapping_formula_factory = mapping_formula_factory or MappingFormulaFactory()
+
+ def convert(self, spec: OssieSpec) -> OssieOntology:
+ ontology = OntologyComponent()
+ model = OssieOntology(
+ name=spec.name,
+ ontology=ontology,
+ description=spec.description,
+ ai_context=spec.ai_context,
+ version=spec.version,
+ )
+
+ self._populate_ontology(ontology, spec)
+
+ for om_spec in spec.ontology_mappings:
+ self._convert_ontology_mapping(model, om_spec)
+
+ return model
+
+ # ----- Ontology ------------------------------------------------------
+
+ def _populate_ontology(self, ontology: OntologyComponent, spec: OssieSpec) -> None:
+
+ concept_specs = {cc.concept: cc for cc in spec.ontology}
+ sorted_names = self._sort_spec_dependency_graph(list(concept_specs.values()))
+ for name in sorted_names:
+ concept_spec = concept_specs[name]
+ extends: list[Concept] = []
+ if concept_spec.extends:
+ for ext in concept_spec.extends:
+ parent = ontology.ensure_builtin_concept(ext)
+ if not parent:
+ raise ValueError(
+ f"Subtype '{ext}' is not declared in ontology '{spec.name}'."
+ )
+ extends.append(parent)
+ ontology.add_concept(
+ Concept(
+ name=concept_spec.concept,
+ type=ConceptType.from_value(concept_spec.type),
+ description=concept_spec.description,
+ extends=extends,
+ )
+ )
+
+ for concept_component in spec.ontology:
+ container = ontology.lookup_concept(concept_component.concept)
+ if container is None:
+ raise ValueError(f"Internal: container concept '{concept_component.concept}' not found")
+ for rel_spec in concept_component.relationships:
+ self._convert_relationship(ontology, container, rel_spec)
+
+ # Identifiers: now that all relationships exist, resolve identify_by.
+ for concept_component in spec.ontology:
+ concept = ontology.lookup_concept(concept_component.concept)
+ if concept is None:
+ continue
+ identifiers: dict[str, Relationship] = {}
+ for ref_name in concept_component.identify_by:
+ rel = ontology.lookup_concept_relationship(concept, ref_name)
+ if rel is None:
+ raise ValueError(
+ f"identify_by '{ref_name}' on concept '{concept.name}' refers to an "
+ f"unknown relationship in ontology '{spec.name}'."
+ )
+ identifiers[rel.full_name] = rel
+ concept.set_identify_by(identifiers)
+
+ # Formulas: derived_by + requires (after concepts/relationships exist).
+ for concept_component in spec.ontology:
+ concept = ontology.lookup_concept(concept_component.concept)
+ if concept is None:
+ continue
+ for raw in concept_component.requires:
+ req = self._build_rule(raw, concept, ontology)
+ if req:
+ concept.add_require(req)
+ for raw in concept_component.derived_by:
+ rule = self._build_rule(raw, concept, ontology)
+ if rule:
+ concept.add_derived_by(rule)
+ for rel_spec in concept_component.relationships:
+ rel = ontology.lookup_concept_relationship(concept, rel_spec.name)
+ if rel is None:
+ continue
+ for raw in rel_spec.requires:
+ req = self._build_rule(raw, rel, ontology)
+ if req:
+ rel.add_require(req)
+ for raw in rel_spec.derived_by:
+ rule = self._build_rule(raw, rel, ontology)
+ if rule:
+ rel.add_derived_by(rule)
+
+ # Ontology-level requires are not scoped to any concept/relationship;
+ # they attach directly to the ontology component.
+ for raw in spec.requires:
+ req = self._build_rule(raw, None, ontology)
+ if req:
+ ontology.add_require(req)
+
+ def _convert_relationship(
+ self, ontology: OntologyComponent, container: Concept, rel_spec: SpecRelationship
+ ) -> None:
+ relates: list[tuple[Concept, str | None]] = []
+ for role_spec in rel_spec.roles:
+ role_concept = ontology.ensure_builtin_concept(role_spec.concept)
+ if role_concept is None:
+ raise ValueError(
+ f"Role concept '{role_spec.concept}' in relationship '{container.name}.{rel_spec.name}' "
+ f"is not declared in the ontology."
+ )
+ relates.append((role_concept, role_spec.name))
+
+ multiplicity = RelationshipMultiplicity.from_value(rel_spec.multiplicity)
+ # OneToOne is only meaningful for binary relationships (the container
+ # concept plus exactly one additional role).
+ if multiplicity == RelationshipMultiplicity.ONE_TO_ONE and len(relates) != 1:
+ raise ValueError(
+ f"Relationship '{container.name}.{rel_spec.name}' declares OneToOne multiplicity, "
+ f"which is only valid for binary relationships (exactly one additional role), "
+ f"but it has {len(relates)}."
+ )
+ relationship = Relationship(
+ name=rel_spec.name,
+ container=container,
+ relates=relates,
+ description=rel_spec.description,
+ verbalizes=list(rel_spec.verbalizes) if rel_spec.verbalizes else None,
+ multiplicity=multiplicity,
+ )
+ ontology.add_relationship(relationship)
+
+ # ----- Logical model -------------------------------------------------
+
+ def _convert_semantic_model(self, lm_spec: SpecSemanticModel) -> SemanticModel:
+ semantic_model = SemanticModel(
+ name=lm_spec.name,
+ description=lm_spec.description,
+ ai_context=lm_spec.ai_context,
+ custom_extensions=[
+ _convert_custom_extension(ce) for ce in lm_spec.custom_extensions
+ ],
+ )
+ for ds_spec in lm_spec.datasets:
+ semantic_model.add_dataset(_convert_dataset(ds_spec))
+ for jp_spec in lm_spec.relationships:
+ semantic_model.add_join_path(_convert_join_path(jp_spec, semantic_model))
+ for m_spec in lm_spec.metrics:
+ semantic_model.add_metric(_convert_metric(m_spec))
+ return semantic_model
+
+ # ----- Ontology mapping ---------------------------------------------
+
+ def _convert_ontology_mapping(self, model: OssieOntology, om_spec: SpecOntologyMapping) -> None:
+ ontology = model.ontology
+
+ semantic_model = self._convert_semantic_model(om_spec.semantic_model)
+
+ mapping = OntologyMapping(
+ name=om_spec.name,
+ ontology=ontology,
+ semantic_model=semantic_model,
+ description=om_spec.description,
+ )
+ model.add_ontology_mapping(mapping)
+
+ for cm_spec in om_spec.concept_mappings:
+ mapping.add_concept_mapping(self._convert_concept_mapping(model, ontology, semantic_model, cm_spec))
+
+ def _convert_concept_mapping(
+ self,
+ model: OssieOntology,
+ ontology: OntologyComponent,
+ semantic_model: SemanticModel,
+ cm_spec: SpecConceptMapping,
+ ) -> ConceptMapping:
+ concept = ontology.lookup_concept(cm_spec.concept)
+ if concept is None:
+ raise ValueError(
+ f"ConceptMapping references unknown concept '{cm_spec.concept}' in ontology '{model.name}'."
+ )
+ cm = ConceptMapping(concept=concept)
+ for object_mapping_spec in cm_spec.object_mappings:
+ cm.object_mappings.append(
+ self._convert_object_mapping(model, ontology, semantic_model, concept, object_mapping_spec)
+ )
+ for link_mapping_spec in cm_spec.link_mappings:
+ cm.link_mappings.append(
+ self._convert_link_mapping(model, ontology, semantic_model, concept, link_mapping_spec)
+ )
+ return cm
+
+ def _convert_object_mapping(
+ self,
+ model: OssieOntology,
+ ontology: OntologyComponent,
+ semantic_model: SemanticModel,
+ container: Concept,
+ om_spec: SpecObjectMapping,
+ ) -> ObjectMapping:
+ concept: Concept | None = None
+ if om_spec.concept:
+ concept = ontology.ensure_builtin_concept(om_spec.concept)
+ if concept is None:
+ raise ValueError(
+ f"ObjectMapping references unknown concept '{om_spec.concept}' in ontology "
+ f"'{model.name}'."
+ )
+ expression: DatasetField | Formula | None = None
+ if om_spec.expression is not None:
+ expression = self._resolve_mapping_expression(om_spec.expression, semantic_model, concept, ontology)
+ referent_mappings = None
+ if om_spec.referent_mappings is not None:
+ rm_container = concept if concept is not None else container
+ referent_mappings = [
+ self._convert_referent_mapping(model, ontology, semantic_model, rm_container, rm)
+ for rm in om_spec.referent_mappings
+ ]
+ return ObjectMapping(concept=concept, expression=expression, referent_mappings=referent_mappings)
+
+ def _convert_referent_mapping(
+ self,
+ model: OssieOntology,
+ ontology: OntologyComponent,
+ semantic_model: SemanticModel,
+ container: Concept,
+ rm_spec: SpecReferentMapping,
+ ) -> ReferentMapping:
+ rel = ontology.lookup_concept_relationship(container, rm_spec.relationship)
+ if rel is None:
+ raise ValueError(
+ f"ReferentMapping references unknown relationship "
+ f"'{container.name}.{rm_spec.relationship}' in ontology '{model.name}'."
+ )
+ sibling_player = rel.last_role.player
+ expression: DatasetField | Formula | None = None
+ if rm_spec.expression is not None:
+ expression = self._resolve_mapping_expression(rm_spec.expression, semantic_model, sibling_player, ontology)
+ nested = None
+ if rm_spec.referent_mappings is not None:
+ nested = [
+ self._convert_referent_mapping(model, ontology, semantic_model, sibling_player, child)
+ for child in rm_spec.referent_mappings
+ ]
+ return ReferentMapping(relationship=rel, expression=expression, referent_mappings=nested)
+
+ def _convert_link_mapping(
+ self,
+ model: OssieOntology,
+ ontology: OntologyComponent,
+ semantic_model: SemanticModel,
+ container: Concept,
+ lm_spec: SpecLinkMapping,
+ ) -> LinkMapping:
+ object_mapping = self._convert_object_mapping(model, ontology, semantic_model, container, lm_spec.object_mapping)
+ relationship: Relationship | None = None
+ if lm_spec.relationship is not None:
+ relationship = ontology.lookup_concept_relationship(container, lm_spec.relationship)
+ if relationship is None:
+ raise ValueError(
+ f"LinkMapping references unknown relationship "
+ f"'{container.name}.{lm_spec.relationship}' in ontology '{model.name}'."
+ )
+ children: list[LinkMapping] | None = None
+ if lm_spec.children is not None:
+ child_container = relationship.last_role.player if relationship is not None else container
+ children = [
+ self._convert_link_mapping(model, ontology, semantic_model, child_container, child)
+ for child in lm_spec.children
+ ]
+ return LinkMapping(object_mapping=object_mapping, relationship=relationship, children=children)
+
+ # ----- Formula helpers -----------------------------------------------
+
+ def _build_rule(self, raw: str | None, parent: Container | None, ontology: OntologyComponent) -> Formula | None:
+ if not raw:
+ return None
+ return self._formula_factory(raw_expr=raw, parent=parent, ontology=ontology)
+
+ def _resolve_mapping_expression(self, expression: str, semantic_model: SemanticModel, expected_type: Concept | None,
+ ontology: OntologyComponent) -> DatasetField | Formula:
+ """Map a raw spec expression onto either a DatasetField or a Formula.
+
+ A `DATASET.field` or unambiguous bare `field` reference that resolves
+ against *semantic_model* is returned as the corresponding DatasetField.
+
+ Everything else — including a `DATASET.field`-shaped expression whose
+ dataset or field is not found here — is delegated to the
+ MappingFormulaFactory, which receives both the ontology and the semantic
+ model. Name resolution and validation of such expressions is deliberately
+ the factory's responsibility, not this method's: the default factory
+ wraps the raw text in a plain Formula, while downstream packages inject
+ enriched factories that parse, resolve, and validate references (e.g.
+ against constructs the base semantic-model lookup cannot see). An unknown
+ `DATASET.field` is therefore not treated as an error at this layer.
+ """
+ qualified = _QUALIFIED_FIELD_RE.match(expression)
+ if qualified:
+ ds_name, field_name = qualified.group(1), qualified.group(2)
+ dataset = semantic_model.lookup_dataset(ds_name)
+ if dataset is not None:
+ field = dataset.field(field_name)
+ if field is not None:
+ _pin_field_type(field, expected_type)
+ return field
+ # Deferred to the factory by design (see docstring), not an error here.
+ return self._mapping_formula_factory(raw_expr=expression, ontology=ontology, semantic_model=semantic_model)
+
+ bare = _BARE_FIELD_RE.match(expression)
+ if bare:
+ field_name = bare.group(1)
+ matches = [
+ (dataset, field)
+ for dataset in semantic_model.datasets
+ if (field := dataset.field(field_name)) is not None
+ ]
+ if len(matches) > 1:
+ owners = ", ".join(dataset.name for dataset, _ in matches)
+ raise ValueError(
+ f"Bare field reference '{field_name}' is ambiguous: it exists in multiple "
+ f"datasets ({owners}). Qualify it as 'DATASET.{field_name}'."
+ )
+ if matches:
+ _, field = matches[0]
+ _pin_field_type(field, expected_type)
+ return field
+ return self._mapping_formula_factory(raw_expr=expression, ontology=ontology, semantic_model=semantic_model)
+
+ return self._mapping_formula_factory(raw_expr=expression, ontology=ontology, semantic_model=semantic_model)
+
+ # ----- Structural helpers --------------------------
+
+ @staticmethod
+ def _sort_spec_dependency_graph(concepts: list[SpecConceptComponent]) -> list[str]:
+ nodes: list[str] = []
+ edges: list[tuple[str, str]] = []
+ for concept in concepts:
+ name = concept.concept
+ nodes.append(name)
+ if concept.extends:
+ for ext in concept.extends:
+ if ext not in BUILTIN_CONCEPTS:
+ edges.append((ext, name))
+ return topological_sort(nodes, edges)
+
+
+def _pin_field_type(field: DatasetField, expected_type: Concept | None) -> None:
+ if expected_type is None:
+ return
+ if field.type is None:
+ field.type = expected_type
+ return
+ if field.type is not expected_type:
+ raise ValueError(
+ f"Field '{field.name}' is already mapped as concept "
+ f"'{field.type.name}' but this mapping expects "
+ f"'{expected_type.name}'. A dataset field can only be "
+ f"bound to one ontology concept type."
+ )
+
+
+def _convert_custom_extension(ce: SpecCustomExtension) -> CustomExtension:
+ return CustomExtension(vendor_name=ce.vendor_name, data=ce.data)
+
+
+def _convert_expression(expr: SpecExpression) -> DialectExpressionSet:
+ return DialectExpressionSet(
+ dialects=[_convert_dialect_expression(d) for d in expr.dialects]
+ )
+
+
+def _convert_dialect_expression(dialect_expr: SpecDialectExpression) -> DialectExpression:
+ return DialectExpression(dialect=dialect_expr.dialect, expression=dialect_expr.expression)
+
+
+def _convert_dimension(dim: SpecDimension | None) -> Dimension | None:
+ if dim is None:
+ return None
+ return Dimension(is_time=dim.is_time)
+
+
+def _convert_dataset_field(fl: SpecDatasetField) -> DatasetField:
+ return DatasetField(
+ name=fl.name,
+ expression=_convert_expression(fl.expression),
+ dimension=_convert_dimension(fl.dimension),
+ label=fl.label,
+ description=fl.description,
+ ai_context=fl.ai_context,
+ custom_extensions=[_convert_custom_extension(ce) for ce in fl.custom_extensions],
+ )
+
+
+def _convert_dataset(ds: SpecDataset) -> Dataset:
+ fields = [_convert_dataset_field(fl) for fl in ds.fields]
+ return Dataset(
+ name=ds.name,
+ source=ds.source,
+ fields=fields,
+ primary_key=ds.primary_key,
+ unique_keys=ds.unique_keys,
+ description=ds.description,
+ ai_context=ds.ai_context,
+ custom_extensions=[_convert_custom_extension(ce) for ce in ds.custom_extensions],
+ )
+
+
+def _convert_join_path(jp: SpecJoinPath, lm: SemanticModel) -> JoinPath:
+ from_dataset = lm.lookup_dataset(jp.from_)
+ to_dataset = lm.lookup_dataset(jp.to)
+ if from_dataset is None:
+ raise ValueError(f"JoinPath '{jp.name}': unknown 'from' dataset '{jp.from_}'.")
+ if to_dataset is None:
+ raise ValueError(f"JoinPath '{jp.name}': unknown 'to' dataset '{jp.to}'.")
+ from_columns: list[DatasetField] = []
+ for col in jp.from_columns:
+ field = from_dataset.field(col)
+ if field is None:
+ raise ValueError(
+ f"JoinPath '{jp.name}': column '{col}' not found in dataset '{from_dataset.name}'."
+ )
+ from_columns.append(field)
+ to_columns: list[DatasetField] = []
+ for col in jp.to_columns:
+ field = to_dataset.field(col)
+ if field is None:
+ raise ValueError(
+ f"JoinPath '{jp.name}': column '{col}' not found in dataset '{to_dataset.name}'."
+ )
+ to_columns.append(field)
+ return JoinPath(
+ name=jp.name,
+ from_dataset=from_dataset,
+ to_dataset=to_dataset,
+ from_columns=from_columns,
+ to_columns=to_columns,
+ ai_context=jp.ai_context,
+ custom_extensions=[_convert_custom_extension(ce) for ce in jp.custom_extensions],
+ )
+
+
+def _convert_metric(m: SpecMetric) -> Metric:
+ return Metric(
+ name=m.name,
+ expression=_convert_expression(m.expression),
+ description=m.description,
+ ai_context=m.ai_context,
+ custom_extensions=[_convert_custom_extension(ce) for ce in m.custom_extensions],
+ )
diff --git a/converters/ontology/src/ossie_ontology/external/__init__.py b/converters/ontology/src/ossie_ontology/external/__init__.py
new file mode 100644
index 00000000..13a83393
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/external/__init__.py
@@ -0,0 +1,16 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
diff --git a/converters/ontology/src/ossie_ontology/external/palantir/__init__.py b/converters/ontology/src/ossie_ontology/external/palantir/__init__.py
new file mode 100644
index 00000000..13a83393
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/external/palantir/__init__.py
@@ -0,0 +1,16 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
diff --git a/converters/ontology/src/ossie_ontology/external/palantir/model.py b/converters/ontology/src/ossie_ontology/external/palantir/model.py
new file mode 100644
index 00000000..1415983e
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/external/palantir/model.py
@@ -0,0 +1,628 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Status(Enum):
+ ACTIVE = 1
+ DEPRECATED = 2
+ EXPERIMENTAL = 3
+ EXAMPLE = 4
+ ENDORSED = 5
+ INTERMEDIARY = 6 # This status had been introduced for testing purposes
+
+class DataType(Enum):
+ ANY = 1
+ ATTACHMENT = 2
+ BOOLEAN = 3
+ DATE = 4
+ DECIMAL = 5
+ DOUBLE = 6
+ FLOAT = 7
+ GEOHASH = 8
+ GEOPOINT = 9
+ GEOSHAPE = 10
+ INTEGER = 11
+ LONG = 12
+ SHORT = 13
+ STRING = 14
+ TIMESERIES = 15
+ TIMESTAMP = 16
+ TIME_DEPENDENT = 17
+ STRUCT = 18
+ VECTOR = 19
+ MEDIA_REFERENCE = 20
+ CIPHER_TEXT = 21
+
+ @staticmethod
+ def parse_datatype(name: str) -> DataType:
+ try:
+ return DataType[name.upper()]
+ except KeyError:
+ raise ValueError(f"Unrecognized data type: {name}") from None
+
+ def to_type(self) -> str:
+ if self in (DataType.STRING, DataType.GEOHASH, DataType.GEOSHAPE, DataType.GEOPOINT, DataType.TIMESERIES):
+ return "String"
+ elif self == DataType.INTEGER:
+ return "Integer"
+ elif self == DataType.DECIMAL:
+ return "Decimal"
+ elif self in (DataType.FLOAT, DataType.DOUBLE, DataType.TIME_DEPENDENT):
+ return "Float"
+ elif self == DataType.BOOLEAN:
+ return "Boolean"
+ elif self == DataType.TIMESTAMP:
+ return "DateTime"
+ elif self == DataType.DATE:
+ return "Date"
+ elif self in (DataType.LONG, DataType.SHORT):
+ return "Integer"
+ elif self == DataType.ANY:
+ return "Any"
+ else:
+ # ATTACHMENT, MEDIA_REFERENCE, CIPHER_TEXT, STRUCT, VECTOR: no scalar
+ # equivalent — carry them as opaque String rather than silently numeric.
+ return "String"
+
+
+class ArrayDataType:
+
+ def __init__(self, t: DataType | ArrayDataType):
+ self._base_type = t
+
+ def base_type(self):
+ return self._base_type
+
+ def __str__(self):
+ return f"array[{str(self._base_type)}]"
+
+class Resource:
+
+ def __init__(self, guid, rid):
+ self._guid = guid
+ self._readable_id = rid
+ self._status = Status.ACTIVE
+
+ def active(self):
+ return self._status == Status.ACTIVE
+
+ def experimental(self):
+ return self._status == Status.EXPERIMENTAL
+
+ def endorsed(self):
+ return self._status == Status.ENDORSED
+
+ def intermediary(self):
+ return self._status == Status.INTERMEDIARY
+
+ def guid(self):
+ return self._guid
+
+ def readable_id(self):
+ return self._readable_id
+
+ def set_status(self, stat:Status):
+ self._status = stat
+
+ def status(self):
+ return self._status
+
+class DataSetModel:
+
+ _data_sets: dict[str, DataSet]
+
+ def __init__(self):
+ self._data_sets = {}
+
+ def data_sets(self):
+ return self._data_sets.values()
+
+ def data_sets_map(self):
+ return self._data_sets
+
+ def info(self) -> str:
+ result: list[str] = []
+ for ds in self._data_sets.values():
+ result.append(str(ds))
+ return "\n".join(result)
+
+class DataSet(Resource):
+
+ def __init__(self, guid, rid):
+ super().__init__(guid, rid)
+ self._description: str | None = None
+ self._path: str | None = None
+ self._columns: list[DataSetColumn] = []
+ self._depends_on: list[DataSet] = []
+
+ def description(self):
+ return self._description
+
+ def path(self):
+ return self._path
+
+ def columns(self):
+ return self._columns
+
+ def depends_on(self):
+ return self._depends_on
+
+ def info(self, indent: int = 0, visited: set[str] | None = None) -> str:
+ """
+ Pretty-print this dataset with indentation and handle dependency graph
+ (avoids infinite recursion on cycles by tracking visited mainDatasetIds).
+ """
+ pad = " " * indent
+ if visited is None:
+ visited = set()
+ lines: list[str] = []
+ ds_id = str(self._guid) if self._guid is not None else "None"
+ name = str(self._readable_id) if self._readable_id is not None else "None"
+
+ header = f'{pad}DataSet(id="{ds_id}", name="{name}")'
+ lines.append(header)
+ if self._description:
+ lines.append(f"{pad} description: {self._description}")
+ if self._path:
+ lines.append(f"{pad} path: {self._path}")
+
+ # Columns
+ if self._columns:
+ lines.append(f"{pad} columns:")
+ for col in self._columns:
+ lines.append(col.info(indent + 4))
+
+ # Dependencies
+ if self._depends_on:
+ lines.append(f"{pad} depends_on:")
+ if ds_id in visited:
+ lines.append(f"{pad} <cycle detected, already visited {ds_id}>")
+ else:
+ visited.add(ds_id)
+ for dep in self._depends_on:
+ # Safeguard when dep is None
+ if dep is None:
+ lines.append(f"{pad} <None>")
+ continue
+ lines.append(dep.info(indent + 4, visited))
+ visited.remove(ds_id)
+
+ return "\n".join(lines)
+
+ def __str__(self) -> str:
+ return self.info()
+
+class DataSetColumn:
+ def __init__(self, name, t, ds: DataSet):
+ self._type = t
+ self._name = name
+ self._part_of = ds
+
+ def name(self):
+ return self._name
+
+ def type(self):
+ return self._type
+
+ def part_of(self) -> DataSet:
+ return self._part_of
+
+ def info(self, indent: int = 0) -> str:
+ return f'{" " * indent}Column(name="{self._name}", type="{self._type}", part_of="{self._part_of.readable_id()}")'
+
+ def __str__(self) -> str:
+ return self.info()
+
+class Ontology:
+
+ _data_sets: dict[str, DataSet]
+ _object_types: dict[str, ObjectType]
+ _object_types_by_readable_id: dict[str, ObjectType]
+ _relations: dict[str, Relation]
+ _relations_by_readable_id: dict[str, Relation]
+ _intermediary_relations: dict[str, IntermediaryRelation]
+
+ def __init__(self):
+ self._data_sets = {}
+ self._object_types = {}
+ self._object_types_by_readable_id = {}
+ self._relations = {}
+ self._relations_by_readable_id = {}
+ self._intermediary_relations = {}
+
+ def add_object_type(self, ot):
+ self._object_types[ot.guid()] = ot
+ self._object_types_by_readable_id[ot.readable_id()] = ot
+ return self
+
+ def add_relation(self, rel):
+ self._relations[rel.guid()] = rel
+ self._relations_by_readable_id[rel.readable_id()] = rel
+ return self
+
+ def object_types(self):
+ return self._object_types
+
+ def object_type_by_readable_id(self, rid):
+ return self._object_types_by_readable_id[rid]
+
+ def relations(self):
+ return self._relations
+
+ def relation_by_readable_id(self, rid):
+ return self._relations_by_readable_id[rid]
+
+ def intermediary_relations(self):
+ return self._intermediary_relations
+
+ def data_sets(self):
+ return self._data_sets
+
+ def set_data_sets(self, data_sets: dict[str, DataSet]):
+ self._data_sets = data_sets
+
+ def info(self, indentation="") -> str:
+ result: list[str] = []
+
+ for ot in sorted(self._object_types.values(), key=lambda x: x.guid()):
+ result.append(ot.info())
+ result.append("")
+
+ for ds in sorted(self._data_sets.values(), key=lambda x: x.guid()):
+ ds_name = ds.readable_id()
+ result.append(indentation + f"Data set '{ds_name}':")
+ for col in sorted(ds.columns(), key=lambda x: x.name()):
+ result.append(indentation + f" Column '{col.name()}' of type '{col.type()}'")
+ result.append("")
+
+ for rel in sorted(self._relations.values(), key=lambda x: x.guid()):
+ result.append(indentation + rel.info())
+ result.append("")
+
+ for ir in sorted(self._intermediary_relations.values(), key=lambda x: x.guid()):
+ result.append(indentation + ir.info())
+ result.append("")
+
+ return "\n".join(result)
+
+# An ObjectType is Palantir's analog of an EntityType. Its instances are
+# identified by its primary-key Properties, which appear in the JSON as
+# ReadingIds in an array, e.g.:
+#
+# {
+# "rid" : <resource-id>
+# "primaryKeys" : [
+# <reading-id>
+# ...
+# ]
+# }
+#
+class ObjectType(Resource):
+
+ def __init__(self, guid, rid, name):
+ super().__init__(guid, rid)
+ self._name = name
+ self._type_groups = []
+ self._syncs_from = []
+ self._properties = {}
+ self._pk_properties = set()
+ self._data_sources = []
+
+ def lookup_property_by_reading(self, pname):
+ for prop in self._properties.values():
+ if prop.readable_id() == pname:
+ return prop
+ return None
+
+
+ def name(self):
+ return self._name
+
+ def type_groups(self):
+ return self._type_groups
+
+ def has_syncs_from(self) -> bool:
+ return bool(self._syncs_from)
+
+ def syncs_from(self):
+ if not self._syncs_from:
+ raise RuntimeError(f"Mandatory constraint violation: ObjectType '{self.readable_id()}' must sync with some DataSet")
+ return self._syncs_from
+
+ def sync_from_data_set(self, ds):
+ self._syncs_from.append(ds)
+ return self
+
+ def properties(self):
+ return self._properties
+
+ def primary_keys(self):
+ return self._pk_properties
+
+ def data_sources(self) -> list[DataSource]:
+ if not self._data_sources:
+ raise RuntimeError(f"Mandatory constraint violation: ObjectType '{self.readable_id()}' must have some data source")
+ return self._data_sources
+
+ def set_properties(self, properties):
+ self._properties = properties
+
+ def set_primary_keys(self, pk_properties):
+ self._pk_properties = pk_properties
+
+ def info(self, indent: int = 0) -> str:
+ keys = ", ".join([prop.readable_id() for prop in self._pk_properties])
+ result: list[str] = [f'{" " * indent}Object type "{self._name}({keys})":']
+ if self._syncs_from:
+ for ds in self._syncs_from:
+ result.append(f'{" " * (indent + 4)}Syncs from "{ds.readable_id()}"')
+ if self._properties:
+ for p in self._properties.values():
+ result.append(p.info(indent + 4))
+ if self._type_groups:
+ result.append(f'{" " * (indent + 4)}Belongs to type groups:')
+ for tg in self._type_groups:
+ result.append(f'{" " * (indent + 8)} "{tg}"')
+ return "\n".join(result)
+
+ def __str__(self) -> str:
+ return self.info()
+
+class DataSource:
+ def __init__(self, backing_dataset_id, backing_datasource_id):
+ self._backing_dataset_id = backing_dataset_id
+ self._backing_datasource_id = backing_datasource_id
+
+ def backing_dataset_id(self):
+ return self._backing_dataset_id
+
+ def backing_datasource_id(self):
+ return self._backing_datasource_id
+
+class Property(Resource):
+
+ def __init__(self, guid, rid, t, ot: ObjectType, column_name, datasource_resource_id):
+ super().__init__(guid, rid)
+ self._part_of = ot
+ self._type = t
+ self._column_name = column_name
+ self._datasource_resource_id = datasource_resource_id
+ self._pk_mapping = {}
+
+ def part_of(self) -> ObjectType:
+ return self._part_of
+
+ def type(self):
+ return self._type
+
+ def column_name(self):
+ return self._column_name
+
+ def datasource_resource_id(self):
+ return self._datasource_resource_id
+
+ def pk_mapping(self):
+ return self._pk_mapping
+
+ def info(self, indent: int = 0) -> str:
+ result = f'{" " * indent}Property "{self.readable_id()}" has data type "{str(self._type)}"'
+ if self._column_name and not self._pk_mapping:
+ result += f'\n{" " * (indent + 4)}Refers to "{str(self._column_name)}" of "{self._datasource_resource_id}" dataset'
+ if self._pk_mapping:
+ for k,v in self._pk_mapping.items():
+ result += f'\n{" " * (indent + 4)}Maps to primary key column "{v}" of "{k}" dataset'
+ return result
+
+ def __str__(self) -> str:
+ return self.info()
+
+# In Palantir, a Relation is a binary relation whose roles are played
+# by ObjectTypes rather than DataTypes -- i.e., entity types rather
+# than value types. They come in two forms: ManyToOne and ManyToMany.
+#
+# Palantir does not model roles or constraints directly. Instead, Relations
+# represent roles using Properties of the ObjectTypes that play the role.
+#
+class Relation(Resource):
+
+ def __init__(self, guid, rid):
+ super().__init__(guid, rid)
+
+ def info(self) -> str:
+ return ""
+
+# A ManyToOneRelation is a binary relation with a uniqueness constraint that spans
+# the "many" role. These objects are populated from a JSON message that looks like this:
+#
+# {
+# "definition": {
+# "type" : "oneToMany",
+# "oneToMany" : {
+# "objectTypeRidOneSide" : <object-type-resource-id>,
+# "objectTypeIdOneSide" : <reading-id>,
+# ...
+# },
+# "objectTypeIdManySide" : <reading-id>,
+# "objectTypeRidManySide" : <object-type-resource-id>,
+# "oneSidePrimaryKeyToManySidePropertyMapping" : {
+# <property-resource-id> : <property-resource-id>, // one-object-property -> many-object-fk-property
+# ...
+# <property-resource-id> : <property-resource-id>, // one-object-property -> many-object-fk-property
+# },
+# "rid" : <relation-resource-id>
+# }
+# }
+#
+# Consider the conceptual relationship "Subscription is part of Account" with a UC on
+# the Subscription role. Subscription then plays the "many" role, and Account plays the
+# "one" role. The resource ids for the role players can be found using these paths:
+#
+# - <definition.objectTypeRidManySide> for Subscription, and
+# - <definition.oneToMany.objectTypeRidOneSide> for Account
+#
+# Such relations are implemented using one or more Properties of the ObjectType that
+# plays the many role. Each of these Properties is interpreted as a foreign-key
+# reference to a Property of the ObjectType that plays the one role. Because an ObjectType
+# might have a compound key, there will be as many properties in the ObjectType that
+# plays the many role as there are key properties in the ObjectType that plays the one
+# role. And while we might naturally think about representing the correspondence between
+# FK properties of the "many" object type to properties of the "one" object type, for
+# some reason Palantir represents this in the reverse direction, which is equivalent,
+# just weird. This is captured in the "oneSidePrimaryKeyToManySidePropertyMapping"
+# message.
+#
+class ManyToOneRelation(Relation):
+
+ def __init__(self, guid, rid, many_object_type: ObjectType, one_object_type: ObjectType,
+ property_map: dict[Property, Property]):
+ super().__init__(guid, rid)
+ self._one_object_type = one_object_type
+ self._many_object_type = many_object_type
+ # We map the property from the many object type to the property of the one object type
+ self._property_map = property_map
+
+ def info(self) -> str:
+ one_role = self._one_object_type
+ many_role = self._many_object_type
+ return f'Relation "{self.readable_id()}" maps "{many_role.name()}" to "{one_role.name()}"'
+
+ def many_object_type(self):
+ return self._many_object_type
+
+ def one_object_type(self):
+ return self._one_object_type
+
+ def property_map(self):
+ return self._property_map
+
+# A ManyToManyRelation is a binary relation with a uniqueness constraint that spans
+# both of its roles. These are populated from a JSON message that looks like this:
+#
+# {
+# "type": "manyToMany",
+# "objectTypeRidA" : <object-type-resource-id>,
+# "objectTypeRidB" : <object-type-resource-id>,
+# "objectTypeIdA" : <reading-id>,
+# "objectTypeIdB" : <reading-id>,
+# "objectTypeAPrimaryKeyPropertyMapping" : {
+# <property-resource-id> : <property-resource-id>, // a-object-property -> join-table-property
+# ...
+# },
+# "objectTypeBPrimaryKeyPropertyMapping" : {
+# <property-resource-id> : <property-resource-id>, // b-object-property -> join-table-property
+# ...
+# },
+# "joinTableDataSource": {
+# "backingResourceRid" : <dataset-resource-id>,
+# "datasourceRid" : <datasource-resource-id>
+# }
+# }
+#
+class ManyToManyRelation(Relation):
+ def __init__(self, guid, rid, role_a_object_type: ObjectType, role_b_object_type: ObjectType,
+ role_a_property_map: dict[Property, str], role_b_property_map: dict[Property, str]):
+ super().__init__(guid, rid)
+ self._role_a_object_type = role_a_object_type
+ self._role_b_object_type = role_b_object_type
+ #
+ # We map properties from each of the two roles' object types to the id of a property
+ # of the backing resource. Notice that we map to <resource-id> rather than Property
+ # because the JSON form we are using may not record property information about the
+ # backing resource.
+ #
+ self._role_a_property_map = role_a_property_map
+ self._role_b_property_map = role_b_property_map
+ #
+ self._backing_dataset_id = None
+ self._backing_datasource_id = None
+ #
+ self._data_set: DataSet | None = None
+
+ def role_a_player(self):
+ return self._role_a_object_type
+
+ def role_b_player(self):
+ return self._role_b_object_type
+
+ def role_a_property_map(self):
+ return self._role_a_property_map
+
+ def role_b_property_map(self):
+ return self._role_b_property_map
+
+ def backing_dataset_id(self):
+ if self._backing_dataset_id is None:
+ raise RuntimeError(f"Mandatory constraint violation: ManyToManyRelation '{self.readable_id()}' must name a backing dataset resource-id")
+ return self._backing_dataset_id
+
+ def backing_datasource_id(self):
+ if self._backing_datasource_id is None:
+ raise RuntimeError(f"Mandatory constraint violation: ManyToManyRelation '{self.readable_id()}' must name a backing datasource resource-id")
+ return self._backing_datasource_id
+
+ def data_set(self):
+ if self._data_set is None:
+ raise RuntimeError(f"Mandatory constraint violation: ManyToManyRelation '{self.readable_id()}' must have some DataSet")
+ return self._data_set
+
+ def set_backing_dataset_id(self, id):
+ self._backing_dataset_id = id
+
+ def set_backing_datasource_id(self, id):
+ self._backing_datasource_id = id
+
+ def info(self):
+ result = [f'Relation "{self.readable_id()}" associates "{self.role_a_player().name()}" with "{self.role_b_player().name()}"']
+ if self._data_set:
+ result.append(f' DataSet "{self.data_set().readable_id()}"')
+ return "\n".join(result)
+
+
+class IntermediaryRelation(Relation):
+ def __init__(self, guid, rid, role_a_object_type: ObjectType, role_b_object_type: ObjectType,
+ intermediary_object_type: ObjectType, relation_a_rid: str, relation_b_rid: str):
+ super().__init__(guid, rid)
+ self._role_a_object_type = role_a_object_type
+ self._role_b_object_type = role_b_object_type
+ self._intermediary_object_type = intermediary_object_type
+ self._relation_a = relation_a_rid
+ self._relation_b = relation_b_rid
+
+ def role_a_player(self):
+ return self._role_a_object_type
+
+ def role_b_player(self):
+ return self._role_b_object_type
+
+ def intermediary_player(self):
+ return self._intermediary_object_type
+
+ def relation_a(self):
+ return self._relation_a
+
+ def relation_b(self):
+ return self._relation_b
+
+ def info(self):
+ return (f'Relation "{self.readable_id()}" associates "{self.role_a_player().name()}" with '
+ f'"{self.role_b_player().name()}" via intermediary player "{self.intermediary_player().name()}" and '
+ f'relations "{self.relation_a()}" and "{self.relation_b()}"')
+
diff --git a/converters/ontology/src/ossie_ontology/external/palantir/parser/__init__.py b/converters/ontology/src/ossie_ontology/external/palantir/parser/__init__.py
new file mode 100644
index 00000000..c0977f14
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/external/palantir/parser/__init__.py
@@ -0,0 +1,800 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+import json
+import warnings
+import zipfile
+from io import IOBase
+from pathlib import Path
+from typing import Any, Iterable
+
+from ossie_ontology.common.utils import camel_to_snake
+from ossie_ontology.external.palantir.model import DataSet, DataSetColumn, DataSetModel, ObjectType, Ontology, DataType, \
+ ArrayDataType, Property, Status, ManyToOneRelation, Relation, ManyToManyRelation, IntermediaryRelation, DataSource
+from ossie_ontology.common.file_utils import iter_json_files_from_dir_in_zip, open_top_level_file_from_zip, \
+ iter_json_files_from_dir, get_top_level_json_file_from_dir, validate_dir
+
+
+# Helper functions to aid in parsing. Palantir's JSON exports can be inconsistent in their formatting, especially
+# across versions. For example, some fields that are expected to be strings may sometimes be empty strings or
+# missing entirely, and some fields that are expected to be lists may sometimes be singletons or missing entirely.
+# These helper functions normalize these inconsistencies to make parsing easier.
+
+def norm(v: Any) -> str | None:
+ if not isinstance(v, str):
+ return None
+ return v if v.strip() else None
+
+def set_if_value(curr: str | None, new_val: str | None) -> str | None:
+ # Only set when new_val is not None (i.e., not empty string or missing)
+ return new_val if new_val is not None else curr
+
+def get_dict(d, key):
+ v = d.get(key)
+ return v if isinstance(v, dict) else {}
+
+def get_list(d, key):
+ v = d.get(key)
+ if isinstance(v, list):
+ return v
+ # Normalize singletons: some exports emit a lone object/value where a list is
+ # expected. Treat a non-null singleton as a one-element list; missing/null -> [].
+ if v is None:
+ return []
+ return [v]
+
+# DataSets in Palantir have their own JSON format that is separate from the Ontology JSON format.
+class PalantirDataSetParser:
+
+ _model: DataSetModel
+
+ def __init__(self):
+ self._model = DataSetModel()
+
+ def model(self):
+ return self._model
+
+ def _dataset_from_dict(self, d: dict[str, Any], registry: dict[str, DataSet]) -> DataSet | None:
+ ds_id = norm(d.get("mainDatasetId"))
+
+ if not ds_id:
+ return None
+
+ # Reuse or create instance; do not return early to ensure children are populated
+ ds = registry.get(ds_id, None)
+ if ds is None:
+ ds = DataSet(ds_id, norm(d.get("datasetName")))
+ registry[ds_id] = ds
+
+ # Scalars without overriding with empty values
+ ds._path = set_if_value(ds.path(), norm(d.get("datasetPath")))
+ ds._readable_id = set_if_value(ds.readable_id(), norm(d.get("datasetName")))
+ ds._description = set_if_value(ds.description(), norm(d.get("description")))
+
+ # Columns: normalize list-vs-singleton like the other helpers. Only touch
+ # columns when the field is actually present, so a missing schema in one
+ # JSON entry doesn't clobber columns populated from another.
+ if d.get("datasetSchema") is not None:
+ cols: list[DataSetColumn] = []
+ for item in get_list(d, "datasetSchema"):
+ if isinstance(item, dict):
+ col_name = norm(item.get("name"))
+ if not col_name:
+ warnings.warn(
+ f"Skipping column with missing name in datasetSchema for dataset '{ds_id}'"
+ )
+ continue
+ cols.append(DataSetColumn(col_name, item.get("type"), ds))
+ ds._columns = cols
+
+ # Dependencies
+ raw_inputs = d.get("inputDatasetIds")
+ if isinstance(raw_inputs, list):
+ inputs: list[DataSet] = []
+ for item in raw_inputs:
+ if not isinstance(item, dict):
+ continue
+ child = self._dataset_from_dict(item, registry)
+ if child is not None:
+ inputs.append(child)
+ ds._depends_on = inputs
+
+ return ds
+
+ def parse(self, file: IOBase):
+ data = json.load(file)
+
+ if not isinstance(data, list):
+ raise ValueError("Top-level JSON must be an array of datasets")
+
+ registry: dict[str, DataSet] = {}
+ for item in data:
+ if isinstance(item, dict):
+ ds = self._dataset_from_dict(item, registry)
+ if ds:
+ self.model().data_sets_map()[ds.guid()] = ds
+
+#
+# The constructs declared within a Palantir ontology refer to one another using one
+# or both of two different reference schemes:
+# - Resource ids, which are essentially GUIDs, and
+# - Readable ids, which are human-readable strings that are not guaranteed to be unique
+# but are more stable across versions and easier to work with.
+# The parser extracts both forms of identifiers for each construct and builds lookup maps
+# keyed by both forms of identifier to make it easier to resolve references regardless of
+# which form they use. In general, resource ids correspond to the 'rid' JSON key, while
+# readable ids correspond to the 'id' or 'apiName' JSON keys.
+#
+class PalantirOntologyParser:
+ _model: Ontology
+
+ #: Keys under which a datasource carries its own identifier, most preferred
+ #: first. Exports up to the `datasourceRid` era use that name; newer ones
+ #: (those that also carry a `version` of `v1`/`v2`/`v3`) call it `rid`.
+ #: Override in a subclass to teach the parser a further spelling.
+ DATASOURCE_RID_KEYS: tuple[str, ...] = ("datasourceRid", "rid")
+
+ def __init__(self):
+ self._model = Ontology()
+
+ def model(self):
+ return self._model
+
+ def _datasource_rid(self, raw_data_source: dict) -> str:
+ """The datasource's own identifier, under whichever key this export uses.
+
+ Read through here rather than off a fixed key so a new export format is
+ a one-line addition to :attr:`DATASOURCE_RID_KEYS`, and so callers never
+ have to rewrite the incoming JSON to make it look like an older version.
+
+ Returns the empty string when no key carries a value, leaving the
+ caller's own "must be non-empty" check to report it.
+ """
+ for key in self.DATASOURCE_RID_KEYS:
+ value = norm(raw_data_source.get(key))
+ if value:
+ return value
+ return ""
+
+ def parse(self, file: IOBase):
+ data = json.load(file)
+
+ if not isinstance(data, dict):
+ raise ValueError("Top-level JSON must be a dictionary of Ontology data")
+
+ # Object Types
+ object_types, object_types_by_readable_id = self._parse_object_types(data)
+ self._model._object_types = object_types
+ self._model._object_types_by_readable_id = object_types_by_readable_id
+
+ # ManyToOneRelations
+ self._model._relations, self._model._intermediary_relations = self._parse_relations(data, object_types)
+ self.validate_intermediary_relations()
+
+ self._parse_extra(data)
+
+ # Given a Raw Palantir ObjectType, extract the string to use as its name regardless
+ # of JSON convention
+ def _parse_object_type_name(self, raw_ot):
+ # Newer JSONs contain a displayMetadata section with this information
+ display_metadata = get_dict(raw_ot, "displayMetadata")
+ if display_metadata:
+ ot_name = norm(display_metadata.get("displayName"))
+ else:
+ ot_name = norm(raw_ot.get("displayName"))
+
+ if ot_name is None:
+ raise ValueError(f'Could not extract a name from ObjectType with rid: {raw_ot.get("rid")}')
+ return ot_name
+
+ def _parse_property_backing_data(self, raw_prop, property_id, object_type_id):
+ # In the new exports this information stores in the `source` field, but in the old exports
+ # it leaves in the `column` and `datasourceRid` fields. We need to support both cases.
+ # Really old format doesn't even have column/datasource info - so use property name as column
+ source = get_dict(raw_prop, "source")
+ column_name = norm(source.get("columnName")) or norm(raw_prop.get("column")) or property_id
+ backing_datasource_id = norm(source.get("datasourceBackingResourceRid")) or norm(raw_prop.get("datasourceRid")) or object_type_id
+
+ return (column_name, backing_datasource_id)
+
+ def _parse_object_types(self, data: dict) -> tuple[dict[str, ObjectType], dict[str, ObjectType]]:
+ object_types = {}
+ object_types_by_readable_id = {}
+ for raw_ot in get_list(data, "objectTypes"):
+ guid = norm(raw_ot.get("rid"))
+ if not guid:
+ raise ValueError("Object type `rid` field must be non-empty")
+ # Support both formats: new (id) and old (apiName)
+ readable_id = norm(raw_ot.get("id")) or norm(raw_ot.get("apiName"))
+ if not readable_id:
+ raise ValueError(
+ f"Object type must have a non-empty `id` or `apiName` (rid: {guid})"
+ )
+
+ # Extract the ObjectType's name
+ ot_name = self._parse_object_type_name(raw_ot)
+
+ object_type = ObjectType(guid, readable_id, ot_name)
+
+ object_type._type_groups = get_list(raw_ot, "typeGroups")
+
+ status_message = get_dict(raw_ot, "status")
+ if status_message:
+ object_type.set_status(self._get_status(norm(status_message.get("type"))))
+
+ object_types[guid] = object_type
+ object_types_by_readable_id[readable_id] = object_type
+
+ data_sources = get_list(raw_ot, "datasources")
+ if len(data_sources) < 1:
+ # No backing datasource? This is common in old versions of the JSON.
+ # Then create one that uses the same identifier as the ObjectType it backs.
+ object_type._data_sources.append(DataSource(readable_id, readable_id))
+ else:
+ for data_source in data_sources:
+ datasource_rid = self._datasource_rid(data_source)
+ backing_resource_rid = norm(data_source.get("backingResourceRid"))
+
+ if not datasource_rid or not backing_resource_rid:
+ raise ValueError("Object type fields `datasourceRid` and `backingResourceRid` must be non-empty")
+
+ object_type._data_sources.append(DataSource(backing_resource_rid, datasource_rid))
+
+
+ properties = {}
+ properties_by_readable_id = {}
+
+ # Support both formats: list (new) and dict (old). Use `or []` so a
+ # present-but-null `properties` is treated the same as missing.
+ raw_properties = raw_ot.get("properties") or []
+ if isinstance(raw_properties, dict):
+ # Old format: properties is a dict keyed by property name
+ raw_properties = list(raw_properties.values())
+
+ for raw_prop in raw_properties:
+ # Parse type (supports nested arrays)
+ # Old format uses 'dataType', new uses 'baseType'
+ raw_base_type = get_dict(raw_prop, "baseType") or get_dict(raw_prop, "dataType")
+ prop_type = self._parse_datatype_node(raw_base_type)
+
+ # Support both formats: new (id) and old (apiName)
+ prop_id = norm(raw_prop.get("id")) or norm(raw_prop.get("apiName"))
+ prop_guid = norm(raw_prop.get("rid"))
+ if not prop_guid or not prop_id:
+ warnings.warn(f"Skipping property with missing id/rid in object type '{ot_name}'")
+ continue
+
+ (column_name, backing_datasource_id) = self._parse_property_backing_data(raw_prop, prop_id, guid)
+
+ prop_name = prop_id
+ prop = Property(prop_guid, prop_name, prop_type, object_type, column_name, backing_datasource_id)
+
+ status_message = get_dict(raw_prop, "status")
+ if status_message:
+ prop.set_status(self._get_status(norm(status_message.get("type"))))
+
+ # This information exists only in the latest exports
+ primary_key_mapping = get_dict(raw_prop, "primaryKeyMapping")
+ if primary_key_mapping:
+ pk_mapping = {}
+ for k in primary_key_mapping:
+ pk_column_name = norm(get_dict(primary_key_mapping, k).get("columnName"))
+ pk_mapping[k] = pk_column_name
+ prop._pk_mapping = pk_mapping
+
+ properties[prop_guid] = prop
+ properties_by_readable_id[prop_name] = prop
+
+ object_type._properties = properties
+
+ pk_properties = set()
+ # Support both formats: primaryKeys (list) and primaryKey (string)
+ pk_list = get_list(raw_ot, "primaryKeys")
+ if not pk_list:
+ single_pk = norm(raw_ot.get("primaryKey"))
+ if single_pk:
+ pk_list = [single_pk]
+ for raw_pk_prop in pk_list:
+ pk_property = properties_by_readable_id.get(raw_pk_prop, None)
+ if pk_property is None:
+ warnings.warn(f"Property '{raw_pk_prop}' is not defined in object type '{ot_name}' - skipping as primary key")
+ continue
+ pk_properties.add(pk_property)
+
+ object_type._pk_properties = pk_properties
+
+ return object_types, object_types_by_readable_id
+
+
+ def _parse_raw_relation_id(self, raw_relation):
+ return norm(raw_relation.get("id")) or norm(raw_relation.get("apiName"))
+
+ def _parse_raw_relation_guid(self, raw_relation):
+ return norm(raw_relation.get("rid")) or norm(raw_relation.get("linkTypeRid"))
+
+ # Assumes raw_relation is a "MANY" relation and looks to make sure that it is
+ # an alternative reading of a "ONE" relation
+ def _verify_alternative_reading_of(self, raw_relation, all_relations):
+ id = raw_relation.get("linkTypeRid")
+ for r in all_relations:
+ if r.get("cardinality") == 'ONE':
+ if r.get("linkTypeRid") == id:
+ return True
+ return False
+
+ def _parse_source_and_target(self, raw_relation, object_types):
+ # In the old format, sourceObjectType/targetObjectType name the source and target
+ # using readings rather than guids.
+ source_ot = norm(raw_relation.get("sourceObjectType"))
+ target_ot = norm(raw_relation.get("targetObjectType"))
+
+ # Look up object types by apiName (readable_id)
+ source_object_type = None
+ target_object_type = None
+ for ot in object_types.values():
+ if ot.readable_id() == source_ot:
+ source_object_type = ot
+ if ot.readable_id() == target_ot:
+ target_object_type = ot
+ return (source_object_type, target_object_type)
+
+ # The old style JSON format supports only ManyToOne relations and uses a simpler format.
+ def _parse_old_style_relation(self, raw_relation, object_types):
+ id = self._parse_raw_relation_id(raw_relation)
+ (source_object_type, target_object_type) = self._parse_source_and_target(raw_relation, object_types)
+
+ if not source_object_type or not target_object_type:
+ warnings.warn(f"Skipping relation {self._parse_raw_relation_id(raw_relation)}: source or target object type not found")
+ return None
+
+ # target_object_type must comprise exactly one primary-key property
+ if len(target_object_type.primary_keys()) == 1:
+
+ # Choose the lone property from the set of target_object_type's primary key properties
+ target_object_pk_property = next(iter(target_object_type.primary_keys()))
+
+ # Look up the name of the source property that is a foreign key reference
+ # to target_object_type's primary key property
+ source_property_name = norm(raw_relation.get("foreignKeyPropertyApiName"))
+ if source_property_name is not None:
+ fk_property = source_object_type.lookup_property_by_reading(source_property_name)
+ if fk_property is not None:
+ # Build property mapping from foreign key
+ property_map = { fk_property: target_object_pk_property }
+ guid = self._parse_raw_relation_guid(raw_relation)
+ return ManyToOneRelation(guid, id, source_object_type, target_object_type, property_map)
+
+ warnings.warn(f"Skipping relation {id}: no foreign key mapping available.")
+ return None
+
+ def _parse_relations(self, data: dict, object_types: dict[str, ObjectType]) -> tuple[dict[str, Relation], dict[str, IntermediaryRelation]]:
+ relations = {}
+ intermediary_relations = {}
+
+ all_relations = get_list(data, "relations")
+ for raw_relation in all_relations:
+ # Support both formats: new (id/rid) and old (apiName/linkTypeRid)
+ relation_id = self._parse_raw_relation_id(raw_relation)
+ relation_guid = self._parse_raw_relation_guid(raw_relation)
+
+ if not relation_guid or not relation_id:
+ # Skip relations without proper identifiers (can happen with SDK-extracted ontologies)
+ warnings.warn(f"Skipping relation with missing id/rid: {raw_relation.get('apiName', 'unknown')}")
+ continue
+
+ relation_type = None
+ definition = get_dict(raw_relation, "definition")
+ if definition:
+ relation_type = norm(definition.get("type"))
+
+ relation: Relation | None = None
+
+ if not definition:
+ cardinality = norm(raw_relation.get("cardinality"))
+ if cardinality == 'MANY':
+ if not self._verify_alternative_reading_of(raw_relation, all_relations):
+ warnings.warn(f'Encountered an unsupported ManyToMany relation {relation_id}')
+ continue
+
+ # Otherwise, assume the cardinality is "ONE"
+ relation = self._parse_old_style_relation(raw_relation, object_types)
+ if relation is None:
+ continue
+
+ elif relation_type and relation_type.lower() == "onetomany":
+ one_to_many_dict = get_dict(definition, "oneToMany")
+ relation = self._parse_many_to_one_relation(relation_guid, relation_id, one_to_many_dict, object_types)
+ elif relation_type and relation_type.lower() == "intermediary":
+ intermediary_dict = get_dict(definition, "intermediary")
+ relation = self._parse_intermediary_relation(relation_guid, relation_id, intermediary_dict, object_types)
+ else:
+ many_to_many_dict = get_dict(definition, "manyToMany")
+ relation = self._parse_many_to_many_relation(relation_guid, relation_id, many_to_many_dict, object_types)
+
+ status_message = get_dict(raw_relation, "status")
+ if status_message:
+ relation.set_status(self._get_status(norm(status_message.get("type"))))
+
+ if isinstance(relation, IntermediaryRelation):
+ intermediary_relations[relation_guid] = relation
+ else:
+ relations[relation_guid] = relation
+
+ return relations, intermediary_relations
+
+ def validate_intermediary_relations(self):
+ for r in self._model.intermediary_relations().values():
+ # Validate that the intermediary relation's link types exist
+ if r.relation_a() not in self._model.relations().keys():
+ raise ValueError(
+ f"Relation with rid {r.relation_a()} is not defined for intermediary relation {r.guid()}")
+ if r.relation_b() not in self._model.relations().keys():
+ raise ValueError(
+ f"Relation with rid {r.relation_b()} is not defined for intermediary relation {r.guid()}")
+
+
+ def _parse_many_to_one_relation(self, guid: str, id: str, raw: dict[Any, Any], object_types: dict[str, ObjectType]) -> Relation:
+
+ one_object_type_rid = norm(raw.get("objectTypeRidOneSide"))
+ many_object_type_rid = norm(raw.get("objectTypeRidManySide"))
+ if not one_object_type_rid or not many_object_type_rid:
+ raise ValueError("ManyToOne relation is missing objectTypeRid fields")
+
+ try:
+ one_object_type = object_types[one_object_type_rid]
+ many_object_type = object_types[many_object_type_rid]
+ except KeyError as e:
+ raise ValueError(f"Object type {e.args[0]} is not defined") from None
+
+ one_to_many_mapping = get_dict(raw, "oneSidePrimaryKeyToManySidePropertyMapping")
+ if not one_to_many_mapping:
+ raise ValueError("Relation definition must contain `oneSidePrimaryKeyToManySidePropertyMapping`")
+
+ property_map: dict[Property, Property] = {}
+ for k, v in one_to_many_mapping.items():
+ one_property = one_object_type.properties().get(k)
+ if one_property is None:
+ raise ValueError(f"Property {k} is not defined in object type {one_object_type.readable_id()}")
+ many_property = many_object_type.properties().get(v)
+ if many_property is None:
+ raise ValueError(f"Property {v} is not defined in object type {many_object_type.readable_id()}")
+
+ property_map[many_property] = one_property
+
+ return ManyToOneRelation(guid, id, many_object_type, one_object_type, property_map)
+
+ def _parse_many_to_many_relation(self, guid: str, id: str, raw: dict[Any, Any], object_types: dict[str, ObjectType]) -> Relation:
+
+ role_a_object_type_rid = norm(raw.get("objectTypeRidA"))
+ role_b_object_type_rid = norm(raw.get("objectTypeRidB"))
+ if not role_a_object_type_rid or not role_b_object_type_rid:
+ raise ValueError("ManyToMany relation is missing objectTypeRid fields")
+
+ try:
+ role_a_object_type = object_types[role_a_object_type_rid]
+ role_b_object_type = object_types[role_b_object_type_rid]
+ except KeyError as e:
+ raise ValueError(f"Object type {e.args[0]} is not defined") from None
+
+ def build_property_map(object_type, pk_mapping: dict[str, str]) -> dict[Property, str]:
+ prop_map: dict[Property, str] = {}
+ for src_prop_id, dst_prop_id in pk_mapping.items():
+ obj_prop = object_type.properties().get(src_prop_id)
+ if obj_prop is None:
+ raise ValueError(
+ f"Property {src_prop_id} is not defined in object type {object_type.readable_id()}"
+ )
+ prop_map[obj_prop] = dst_prop_id
+ return prop_map
+
+ role_a_pk_mapping = get_dict(raw, "objectTypeAPrimaryKeyPropertyMapping")
+ if not role_a_pk_mapping:
+ raise ValueError("Relation definition must contain `objectTypeAPrimaryKeyPropertyMapping`")
+
+ role_a_property_map: dict[Property, str] = build_property_map(role_a_object_type, role_a_pk_mapping)
+
+ role_b_pk_mapping = get_dict(raw, "objectTypeBPrimaryKeyPropertyMapping")
+ if not role_b_pk_mapping:
+ raise ValueError("Relation definition must contain `objectTypeBPrimaryKeyPropertyMapping`")
+
+ role_b_property_map: dict[Property, str] = build_property_map(role_b_object_type, role_b_pk_mapping)
+
+ relation = ManyToManyRelation(guid, id, role_a_object_type, role_b_object_type, role_a_property_map,
+ role_b_property_map)
+
+ # Accept both key spellings seen across export versions: `joinTableDatasource`
+ # and `joinTableDataSource` (capital 'S').
+ join_table_data_source = get_list(raw, "joinTableDatasource") or get_list(raw, "joinTableDataSource")
+ if len(join_table_data_source) != 1:
+ raise ValueError("Relation definition must contain exactly one `joinTableDatasource`")
+
+ datasource_rid = self._datasource_rid(join_table_data_source[0])
+ backing_resource_rid = norm(join_table_data_source[0].get("backingResourceRid"))
+
+ if not datasource_rid or not backing_resource_rid:
+ raise ValueError("Relation fields `datasourceRid` and `backingResourceRid` must be non-empty")
+
+ relation.set_backing_datasource_id(datasource_rid)
+ relation.set_backing_dataset_id(backing_resource_rid)
+
+ return relation
+
+ def _parse_intermediary_relation(self, guid: str, id: str, raw: dict[Any, Any], object_types: dict[str, ObjectType]) -> Relation:
+ role_a_object_type_rid = norm(raw.get("objectTypeRidA"))
+ role_b_object_type_rid = norm(raw.get("objectTypeRidB"))
+ intermediary_rid = norm(raw.get("intermediaryObjectTypeRid"))
+ if not role_a_object_type_rid or not role_b_object_type_rid or not intermediary_rid:
+ raise ValueError("Intermediary relation is missing objectTypeRid fields")
+
+ try:
+ role_a_object_type = object_types[role_a_object_type_rid]
+ role_b_object_type = object_types[role_b_object_type_rid]
+ intermediary_object_type = object_types[intermediary_rid]
+ except KeyError as e:
+ raise ValueError(f"Object type {e.args[0]} is not defined") from None
+
+ a_to_intermediary_link_rid = norm(raw.get("aToIntermediaryLinkTypeRid"))
+ intermediary_to_b_link_rid = norm(raw.get("intermediaryToBLinkTypeRid"))
+ if not a_to_intermediary_link_rid or not intermediary_to_b_link_rid:
+ raise ValueError("Intermediary relation is missing link type rid fields")
+
+ return IntermediaryRelation(guid, id, role_a_object_type, role_b_object_type, intermediary_object_type,
+ a_to_intermediary_link_rid, intermediary_to_b_link_rid)
+
+ def _get_status(self, status):
+ match status:
+ case "active":
+ return Status.ACTIVE
+ case "deprecated":
+ return Status.DEPRECATED
+ case "experimental":
+ return Status.EXPERIMENTAL
+ case "example":
+ return Status.EXAMPLE
+ case "endorsed":
+ return Status.ENDORSED
+ # This status had been introduced for testing purposes
+ case "intermediary":
+ return Status.INTERMEDIARY
+ case _:
+ raise ValueError(f"Unrecognized Resource status {status}")
+
+ def _parse_datatype_node(self, node) -> DataType | ArrayDataType:
+ """
+ node: {"type": "...", "subType": {...}} possibly nested arrays
+ Returns DataType or ArrayDataType wrapping.
+ """
+
+ t = norm(node.get("type"))
+ if not t:
+ # Default to STRING for missing types
+ return DataType.STRING
+
+ if t.upper() == "ARRAY":
+ # Support both camelCase (subType) and snake_case (sub_type)
+ sub = get_dict(node, "subType") or get_dict(node, "sub_type")
+ if not sub:
+ # Default to STRING array if subType is missing
+ return ArrayDataType(DataType.STRING)
+ inner = self._parse_datatype_node(sub)
+ return ArrayDataType(inner)
+
+ # Non-array primitive
+ return DataType.parse_datatype(t)
+
+
+ def _parse_extra(self, data: dict) -> None:
+ """Extension point for subclasses to parse additional data from the ontology JSON.
+
+ Called at the end of :meth:`parse` with the fully-deserialized JSON dict.
+ The base implementation is a no-op; override in a subclass to add domain-specific
+ parsing (e.g. actions, workflows, validations) without re-reading the file.
+ """
+
+class PalantirParser:
+ _model: Ontology | None
+
+ def __init__(self):
+ self._model = None
+
+ def _make_ontology_parser(self) -> PalantirOntologyParser:
+ return PalantirOntologyParser()
+
+ def parse(self, path: Path) -> Ontology:
+ # A Palantir export may arrive as a ZIP archive, an already extracted
+ # folder, or a folder that simply wraps a single ZIP archive. Detect
+ # which and process accordingly.
+ if path.is_dir():
+ wrapped_zip = self._single_zip_in_dir(path)
+ if wrapped_zip is not None:
+ with zipfile.ZipFile(wrapped_zip) as zf:
+ self._parse_from_zip(zf)
+ else:
+ self._parse_from_dir(path)
+ elif path.is_file():
+ if not zipfile.is_zipfile(path):
+ raise ValueError(f"Unsupported Palantir source '{path}'. Expected a ZIP archive or a directory")
+ with zipfile.ZipFile(path) as zf:
+ self._parse_from_zip(zf)
+ else:
+ raise FileNotFoundError(f"Palantir source '{path}' does not exist")
+
+ if self._model is None:
+ raise RuntimeError(f"Parsing '{path}' did not produce an ontology model")
+
+ return self._model
+
+ @staticmethod
+ def _single_zip_in_dir(base_dir: Path) -> Path | None:
+ """Return the lone ZIP archive inside ``base_dir`` when the folder wraps
+ exactly one ``.zip`` file (and nothing else); otherwise ``None``. This
+ mirrors the convenience of accepting a folder that just contains a
+ Palantir export archive."""
+ entries = list(base_dir.iterdir())
+ if len(entries) == 1 and entries[0].is_file() and zipfile.is_zipfile(entries[0]):
+ return entries[0]
+ return None
+
+ def _parse_from_zip(self, zf: zipfile.ZipFile):
+ self._validate_archive(zf)
+
+ def _data_set_streams() -> Iterable[IOBase]:
+ for _name, fh in iter_json_files_from_dir_in_zip(zf, "data_sets"):
+ yield fh
+
+ with open_top_level_file_from_zip(zf, self._get_ontology_json_file_path(zf)) as ontology_fh:
+ self._build_model(_data_set_streams(), ontology_fh)
+
+ def _parse_from_dir(self, base_dir: Path):
+ validate_dir(base_dir)
+ ontology_path = get_top_level_json_file_from_dir(base_dir)
+
+ def _data_set_streams() -> Iterable[IOBase]:
+ for _name, fh in iter_json_files_from_dir(base_dir, "data_sets"):
+ yield fh
+
+ with ontology_path.open("rb") as ontology_fh:
+ self._build_model(_data_set_streams(), ontology_fh)
+
+ def _build_model(self, data_set_streams: Iterable[IOBase], ontology_stream: IOBase):
+ """Build the ontology model from a stream of data set JSON files and the
+ top-level ontology JSON stream. Shared by the ZIP and directory paths."""
+ any_json = False
+ data_sets: dict[str, DataSet] = {}
+ for fh in data_set_streams:
+ any_json = True
+ try:
+ parser = PalantirDataSetParser()
+ parser.parse(fh)
+ data_sets.update(parser.model().data_sets_map())
+ finally:
+ fh.close()
+ if not any_json:
+ # No datasets is a shape some exports genuinely have, not a broken
+ # one: the ontology JSON alone carries every object type, property,
+ # key and link, so the model below is built in full. What it will
+ # not have is any weaving — nothing maps a concept to the table
+ # behind it — so it type-checks and then answers every query with
+ # nothing. Loud enough to notice, not fatal.
+ warnings.warn(
+ "'data_sets' folder contains no JSON files. The ontology will be "
+ "built from the ontology JSON alone: valid, but with no mappings "
+ "connecting its concepts to source tables, so queries against it "
+ "return nothing.",
+ stacklevel=2,
+ )
+
+ parser = self._make_ontology_parser()
+ parser.parse(ontology_stream)
+ model = parser.model()
+ model.set_data_sets(data_sets)
+
+ for ot in model.object_types().values():
+ for ds in ot.data_sources():
+ data_set = data_sets.get(ds.backing_dataset_id(), None)
+ if data_set is None:
+ # For SDK-extracted ontologies with synthetic datasources,
+ # mainDatasetId in data_sets JSON matches the object type's RID
+ data_set = data_sets.get(ot.guid(), None)
+ if data_set:
+ ot.sync_from_data_set(data_set)
+ # For SDK-extracted ontologies, property column_name defaults to
+ # the apiName (camelCase), but dataset columns use snake_case.
+ # Cross-reference to use the actual dataset column names.
+ ds_col_names = {col.name() for col in data_set.columns()}
+ for prop in ot.properties().values():
+ col_name = prop.column_name()
+ if col_name not in ds_col_names:
+ snake_name = camel_to_snake(col_name)
+ if snake_name in ds_col_names:
+ prop._column_name = snake_name
+ for rel in model.relations().values():
+ if isinstance(rel, ManyToManyRelation):
+ rel._data_set = data_sets.get(rel.backing_dataset_id(), None)
+
+ self._model = model
+
+ def _validate_archive(self, zf: zipfile.ZipFile):
+ """
+ Warn when the ZIP archive carries no 'data_sets/' directory. Accepts:
+ - Top-level 'data_sets/' folder, or
+ - A single-root folder with 'root/data_sets/' inside.
+
+ Missing datasets is a warning rather than an error — see
+ :func:`ossie_ontology.common.file_utils.validate_dir` for why, and for
+ what it costs.
+ """
+ names = zf.namelist()
+
+ # Fast path: direct presence at top-level or files under 'data_sets/'
+ has_data_sets = any(
+ n.endswith("/") and n.rstrip("/").endswith("data_sets") for n in names
+ ) or any(n.startswith("data_sets/") for n in names)
+ if has_data_sets:
+ return
+
+ # Single-root archives: if there's exactly one root folder, allow root/data_sets/
+ roots = {n.split("/", 1)[0] for n in names if "/" in n}
+ if len(roots) == 1:
+ root = next(iter(roots))
+ has_rooted_data_sets = any(
+ n.endswith("/") and n.rstrip("/").endswith(f"{root}/data_sets") for n in names
+ ) or any(n.startswith(f"{root}/data_sets/") for n in names)
+ if has_rooted_data_sets:
+ return
+
+ # Same reasoning as the directory path: buildable ontology, no weaving.
+ warnings.warn(
+ "Archive contains no 'data_sets' folder. The ontology will be built "
+ "from the ontology JSON alone: valid, but with no mappings connecting "
+ "its concepts to source tables, so queries against it return nothing.",
+ stacklevel=2,
+ )
+
+ def _get_ontology_json_file_path(self, zf: zipfile.ZipFile) -> str:
+ """
+ Find exactly one top-level JSON file and return its archive path.
+
+ Rules:
+ - "Top-level" means entries without '/' in their name.
+ - If the archive is packaged under a single root directory, then
+ "top-level" means entries directly under that root (exactly one '/').
+ - There must be exactly one JSON at this level; otherwise raise.
+ """
+ names = zf.namelist()
+
+ # Identify entries without any parent directory.
+ top_level = [n for n in names if "/" not in n]
+
+ # If nothing is at the real top-level, accept the case of a single root folder.
+ if not top_level:
+ roots = {n.split("/", 1)[0] for n in names if "/" in n}
+ if len(roots) == 1:
+ root = next(iter(roots))
+ # Entries directly under the single root (e.g., 'root/file.json')
+ top_level = [n for n in names if n.startswith(f"{root}/") and n.count("/") == 1]
+
+ # Keep only JSON files
+ json_candidates = [n for n in top_level if n.lower().endswith(".json")]
+
+ # Enforce exactly one ontology JSON at the top level
+ if len(json_candidates) == 0:
+ raise ValueError("Archive must contain exactly one top-level JSON file (none found)")
+ if len(json_candidates) > 1:
+ raise ValueError("Archive must contain exactly one top-level JSON file (multiple found)")
+
+ return json_candidates[0]
diff --git a/converters/ontology/src/ossie_ontology/model.py b/converters/ontology/src/ossie_ontology/model.py
new file mode 100644
index 00000000..2f9d1e72
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/model.py
@@ -0,0 +1,1207 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Protocol
+
+# ---------------------------------------------------------------------------
+# Builtin concept names.
+# ---------------------------------------------------------------------------
+
+BUILTIN_CONCEPTS: frozenset[str] = frozenset({
+ "Any", "AnyEntity", "Boolean", "Date", "DateTime", "Decimal", "Float", "Integer", "String"
+})
+
+# ---------------------------------------------------------------------------
+# Free-form metadata mirroring spec
+# ---------------------------------------------------------------------------
+
+AiContext = str | dict[str, Any]
+
+
+@dataclass
+class CustomExtension:
+ vendor_name: str
+ data: str
+
+
+# ---------------------------------------------------------------------------
+# Ontology (concepts + relationships grouped by container)
+# ---------------------------------------------------------------------------
+
+class ConceptType(str, Enum):
+ ENTITY_TYPE = "EntityType"
+ VALUE_TYPE = "ValueType"
+
+ @classmethod
+ def from_value(cls, value: str | None) -> ConceptType | None:
+ if value is None:
+ return None
+ if not isinstance(value, str):
+ raise TypeError("value must be a string")
+ for member in cls:
+ if member.value == value:
+ return member
+ raise ValueError(f"Unknown concept type: {value}")
+
+
+class RelationshipMultiplicity(str, Enum):
+ """Spec-level multiplicity declared on a relationship.
+
+ Allows OneToOne or ManyToOne (ManyToMany is no longer expressible
+ at the spec level — it becomes the default 'unconstrained' case).
+ """
+ ONE_TO_ONE = "OneToOne"
+ MANY_TO_ONE = "ManyToOne"
+
+ @classmethod
+ def from_value(cls, value: str | None) -> RelationshipMultiplicity | None:
+ if value is None:
+ return None
+ if not isinstance(value, str):
+ raise TypeError("value must be a string")
+ normalized = value.strip().lower()
+ for member in cls:
+ if member.value.lower() == normalized:
+ return member
+ raise ValueError(f"Unknown relationship multiplicity value: {value}")
+
+
+class Concept:
+ """Type-like ontology node. May be an EntityType (real-world object,
+ referenced via identifying relationships) or a ValueType (primitive-ish,
+ transitively extending a built-in value type)."""
+ _name: str
+ _type: ConceptType | None
+ _description: str | None
+ _builtin: bool
+ _extends: list[Concept]
+ _identify_by: dict[str, Relationship]
+ _derived_by: list[Formula]
+ _requires: list[Formula]
+ _is_component: bool
+
+ def __init__(
+ self,
+ name: str,
+ type: ConceptType | None = None,
+ description: str | None = None,
+ builtin: bool = False,
+ extends: list[Concept] | None = None,
+ identify_by: dict[str, Relationship] | None = None,
+ derived_by: list[Formula] | None = None,
+ requires: list[Formula] | None = None,
+ is_component: bool = True
+ ):
+ self._name = name
+ self._type = type
+ self._description = description
+ self._builtin = builtin
+ self._extends = extends if extends else []
+ self._identify_by = identify_by if identify_by else {}
+ self._derived_by = derived_by if derived_by else []
+ self._requires = requires if requires else []
+ self._is_component = is_component
+
+ def add_require(self, require: Formula) -> None:
+ self._requires.append(require)
+
+ def add_derived_by(self, rule: Formula) -> None:
+ self._derived_by.append(rule)
+
+ def set_identify_by(self, identifiers: dict[str, Relationship]) -> None:
+ self._identify_by = identifiers
+
+ def extend(self, parent: Concept) -> None:
+ self._extends.append(parent)
+
+ @property
+ def name(self) -> str:
+ return self._name
+
+ @property
+ def type(self) -> ConceptType | None:
+ return self._type
+
+ @property
+ def description(self) -> str | None:
+ return self._description
+
+ @property
+ def is_builtin(self) -> bool:
+ return self._builtin
+
+ # True if this concept identifies a concept component in an Ossie ontology
+ @property
+ def is_component(self) -> bool:
+ return self._is_component
+
+ @property
+ def is_value_type(self) -> bool:
+ return self._type == ConceptType.VALUE_TYPE
+
+ @property
+ def is_entity_type(self) -> bool:
+ return self._type == ConceptType.ENTITY_TYPE
+
+ @property
+ def is_primitive(self) -> bool:
+ if self.is_builtin:
+ return True
+ if self._extends and len(self._extends) == 1:
+ return self._extends[0].is_primitive
+ return False
+
+ @property
+ def is_derived(self) -> bool:
+ return bool(self._derived_by)
+
+ @property
+ def extends(self) -> list[Concept]:
+ return list(self._extends)
+
+ @property
+ def identify_by(self) -> dict[str, Relationship]:
+ return dict(self._identify_by)
+
+ @property
+ def derived_by(self) -> list[Formula]:
+ return list(self._derived_by)
+
+ @property
+ def requires(self) -> list[Formula]:
+ return list(self._requires)
+
+ def __str__(self) -> str:
+ return self._name
+
+
+class Relationship:
+ """A relationship grouped under its first-role concept (the container).
+ In this model class we choose to store all the roles explicitly, including the first implicit role from the Ossie spec.
+ """
+ _name: str
+ _container: Concept
+ _roles: tuple[Role, ...]
+ _description: str | None
+ _verbalizes_raw: list[str] | None
+ _verbalizations: list[RelationshipVerbalization]
+ _multiplicity: RelationshipMultiplicity | None
+ _derived_by: list[Formula]
+ _requires: list[Formula]
+
+ def __init__(
+ self,
+ name: str,
+ container: Concept,
+ relates: list[tuple[Concept, str | None]],
+ description: str | None = None,
+ verbalizes: list[str] | None = None,
+ multiplicity: RelationshipMultiplicity | None = None,
+ ):
+ self._name = name
+ self._container = container
+ container_role = Role(self, container, 0, None)
+ additional = [Role(self, concept, idx + 1, role_name) for idx, (concept, role_name) in enumerate(relates)]
+ self._roles = tuple([container_role] + additional)
+ self._description = description
+ self._multiplicity = multiplicity
+ self._verbalizes_raw = list(verbalizes) if verbalizes else None
+ self._verbalizations = parse_verbalizations(self, verbalizes)
+ self._derived_by = []
+ self._requires = []
+
+ @property
+ def name(self) -> str:
+ return self._name
+
+ @property
+ def full_name(self) -> str:
+ return f"{self._container.name}.{self._name}"
+
+ @property
+ def container(self) -> Concept:
+ return self._container
+
+ @property
+ def description(self) -> str | None:
+ return self._description
+
+ @property
+ def signature(self) -> list[Concept]:
+ return [role.player for role in self._roles]
+
+ @property
+ def arity(self) -> int:
+ return len(self._roles)
+
+ @property
+ def binary(self) -> bool:
+ return self.arity == 2
+
+ @property
+ def unary(self) -> bool:
+ return self.arity == 1
+
+ def role(self, pos: int | Concept | str) -> Role:
+ if isinstance(pos, int):
+ return self._roles[pos]
+ if isinstance(pos, Concept):
+ for role in self._roles:
+ if role.player == pos:
+ return role
+ elif isinstance(pos, str):
+ for role in self._roles:
+ if role.name == pos:
+ return role
+ raise ValueError(f"Role '{pos}' not found in relationship '{self.full_name}'")
+
+ @property
+ def roles(self) -> tuple[Role, ...]:
+ return self._roles
+
+ def set_multiplicity(self, mult: RelationshipMultiplicity) -> None:
+ if self._multiplicity is not None and self._multiplicity != mult:
+ raise ValueError(
+ f"Conflicting multiplicity settings for relationship {self}: "
+ f"{self._multiplicity} and {mult}"
+ )
+ self._multiplicity = mult
+
+ @property
+ def first_role(self) -> Role:
+ return self._roles[0]
+
+ @property
+ def last_role(self) -> Role:
+ return self._roles[-1]
+
+ @property
+ def verbalizations(self) -> list[RelationshipVerbalization]:
+ return self._verbalizations
+
+ @property
+ def verbalizes_raw(self) -> list[str] | None:
+ return self._verbalizes_raw
+
+ @property
+ def multiplicity(self) -> RelationshipMultiplicity | None:
+ return self._multiplicity
+
+ @property
+ def derived_by(self) -> list[Formula]:
+ return list(self._derived_by)
+
+ @property
+ def requires(self) -> list[Formula]:
+ return list(self._requires)
+
+ def add_derived_by(self, rule: Formula) -> None:
+ self._derived_by.append(rule)
+
+ def add_require(self, rule: Formula) -> None:
+ self._requires.append(rule)
+
+ def __str__(self) -> str:
+ return self._name
+
+
+class Role:
+ _part_of: Relationship
+ _player: Concept
+ _name: str | None
+ _sibling: Role | None
+ _idx: int
+
+ def __init__(self, part_of: Relationship, player: Concept, idx: int, name: str | None = None):
+ self._part_of = part_of
+ self._player = player
+ self._idx = idx
+ self._name = name
+ self._sibling = None
+
+ @property
+ def player(self) -> Concept:
+ return self._player
+
+ @property
+ def idx(self) -> int:
+ return self._idx
+
+ @property
+ def name(self) -> str:
+ return self._name or self._player.name
+
+ @property
+ def explicit_name(self) -> str | None:
+ return self._name
+
+ @property
+ def part_of(self) -> Relationship:
+ return self._part_of
+
+ @property
+ def sibling(self) -> Role | None:
+ if self._part_of.binary and not self._sibling:
+ first_role, second_role = self._part_of.roles
+ sibling = second_role if self == first_role else first_role
+ self._sibling = sibling
+ return self._sibling
+
+ @property
+ def madlib(self) -> str:
+ return f"{self._player.name}:{self._name}" if self._name else self._player.name
+
+ def __eq__(self, other: object) -> bool:
+ if not isinstance(other, Role):
+ return False
+ # Position included: the two roles of a self-relationship differ in
+ # nothing else when neither carries a name, and conflating them makes
+ # `sibling` return the role itself and collapses both into one entry of
+ # any set or dict keyed by Role.
+ return (
+ self._part_of == other._part_of
+ and self._player == other._player
+ and self._name == other._name
+ and self._idx == other._idx
+ )
+
+ def __hash__(self) -> int:
+ return hash((self._part_of, self._player, self._name, self._idx))
+
+
+# ---------------------------------------------------------------------------
+# Formula — raw expression string only.
+# ---------------------------------------------------------------------------
+
+FormulaParent = Concept | Relationship | tuple[Concept, Relationship] | None
+
+
+class Formula:
+ _raw_expr: str
+ _parent: FormulaParent
+
+ def __init__(self, raw_expr: str, parent: FormulaParent = None):
+ self._raw_expr = raw_expr
+ self._parent = parent
+
+ @property
+ def raw_expr(self) -> str:
+ return self._raw_expr
+
+ @property
+ def parent(self) -> FormulaParent:
+ return self._parent
+
+ def __str__(self) -> str:
+ return self._raw_expr
+
+
+class FormulaFactory:
+ """Base factory for ontology-level formulas (derived_by / requires on concepts and relationships).
+
+ Subclass and override __call__ to return an enriched Formula subclass,
+ e.g. one carrying an AST produced by a FormulaParser.
+ """
+
+ def __call__(self, raw_expr: str, parent: FormulaParent = None, ontology: OntologyComponent | None = None) -> Formula:
+ return Formula(raw_expr=raw_expr, parent=parent)
+
+
+class MappingFormulaFactory:
+ """Base factory for mapping-level formulas (object / referent mapping expressions).
+
+ Receives both the ontology and the semantic model so that name resolution
+ and field-level validation can be performed against the full mapping context.
+
+ Subclass and override __call__ to return an enriched Formula subclass.
+ """
+
+ def __call__(self, raw_expr: str, parent: FormulaParent = None,
+ ontology: OntologyComponent | None = None, semantic_model: SemanticModel | None = None) -> Formula:
+ return Formula(raw_expr=raw_expr, parent=parent)
+
+
+# ---------------------------------------------------------------------------
+# Semantic model (datasets, join paths, metrics)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class DialectExpression:
+ dialect: str
+ expression: str
+
+
+@dataclass
+class DialectExpressionSet:
+ """Runtime equivalent of spec.Expression — same logical expression rendered
+ in one or more dialects."""
+ dialects: list[DialectExpression] = field(default_factory=list)
+
+ def by_dialect(self, dialect: str) -> DialectExpression | None:
+ for d in self.dialects:
+ if d.dialect == dialect:
+ return d
+ return None
+
+ @property
+ def primary(self) -> DialectExpression | None:
+ return self.dialects[0] if self.dialects else None
+
+
+@dataclass
+class Dimension:
+ is_time: bool | None = None
+
+
+@dataclass
+class DatasetField:
+ name: str
+ expression: DialectExpressionSet
+ type: Concept | None = None
+ dimension: Dimension | None = None
+ label: str | None = None
+ description: str | None = None
+ ai_context: AiContext | None = None
+ custom_extensions: list[CustomExtension] = field(default_factory=list)
+ # Back-reference to the owning Dataset, wired by Dataset.__init__. Used by
+ # mapping-expression rendering to reconstruct `<dataset>.<field>` strings
+ # for round-trip output. Not in the spec — purely runtime metadata.
+ dataset: "Dataset | None" = field(default=None, repr=False, compare=False)
+
+ def __str__(self) -> str:
+ return self.name
+
+
+def sanitize_identifier(ref: str) -> str:
+ return re.sub(r"[^A-Za-z0-9_]", "_", ref)
+
+
+class Dataset:
+ _name: str
+ _source: str
+ _primary_key: list[str] | None
+ _unique_keys: list[list[str]] | None
+ _description: str | None
+ _ai_context: AiContext | None
+ _fields: list[DatasetField]
+ _custom_extensions: list[CustomExtension]
+ _field_name_map: dict[str, DatasetField]
+
+ def __init__(
+ self,
+ name: str,
+ source: str,
+ fields: list[DatasetField],
+ primary_key: list[str] | None = None,
+ unique_keys: list[list[str]] | None = None,
+ description: str | None = None,
+ ai_context: AiContext | None = None,
+ custom_extensions: list[CustomExtension] | None = None,
+ ):
+ self._name = name
+ self._source = source
+ self._fields = fields
+ self._primary_key = primary_key
+ self._unique_keys = unique_keys
+ self._description = description
+ self._ai_context = ai_context
+ self._custom_extensions = custom_extensions or []
+ self._field_name_map = {fl.name: fl for fl in fields}
+ # Wire the back-reference so each field knows its owning Dataset —
+ # the mapping-expression renderer needs it to reconstruct
+ # `<dataset>.<field>` strings on reverse conversion.
+ for fl in fields:
+ fl.dataset = self
+
+ @property
+ def name(self) -> str:
+ return self._name
+
+ @property
+ def source(self) -> str:
+ return self._source
+
+ @property
+ def primary_key(self) -> list[str] | None:
+ return self._primary_key
+
+ @property
+ def unique_keys(self) -> list[list[str]] | None:
+ return self._unique_keys
+
+ @property
+ def description(self) -> str | None:
+ return self._description
+
+ @property
+ def ai_context(self) -> AiContext | None:
+ return self._ai_context
+
+ def field(self, name: str) -> DatasetField | None:
+ return self._field_name_map.get(name)
+
+ @property
+ def fields(self) -> list[DatasetField]:
+ return list(self._fields)
+
+ @property
+ def custom_extensions(self) -> list[CustomExtension]:
+ return list(self._custom_extensions)
+
+ @property
+ def schema(self) -> dict[str, Concept | None]:
+ return {fl.name: fl.type for fl in self._fields}
+
+ def __str__(self) -> str:
+ return self._name
+
+
+class JoinPath:
+ """Runtime equivalent of spec.JoinPath — a foreign-key style join
+ between two Datasets, matching `from_columns` against `to_columns`."""
+ _name: str
+ _from_dataset: Dataset
+ _to_dataset: Dataset
+ _from_columns: list[DatasetField]
+ _to_columns: list[DatasetField]
+ _ai_context: AiContext | None
+ _custom_extensions: list[CustomExtension]
+
+ def __init__(
+ self,
+ name: str,
+ from_dataset: Dataset,
+ to_dataset: Dataset,
+ from_columns: list[DatasetField],
+ to_columns: list[DatasetField],
+ ai_context: AiContext | None = None,
+ custom_extensions: list[CustomExtension] | None = None,
+ ):
+ if len(from_columns) != len(to_columns):
+ raise ValueError(
+ f"JoinPath '{name}': from_columns/to_columns arity mismatch "
+ f"({len(from_columns)} vs {len(to_columns)})"
+ )
+ self._name = name
+ self._from_dataset = from_dataset
+ self._to_dataset = to_dataset
+ self._from_columns = from_columns
+ self._to_columns = to_columns
+ self._ai_context = ai_context
+ self._custom_extensions = custom_extensions or []
+
+ @property
+ def name(self) -> str:
+ return self._name
+
+ @property
+ def from_dataset(self) -> Dataset:
+ return self._from_dataset
+
+ @property
+ def to_dataset(self) -> Dataset:
+ return self._to_dataset
+
+ @property
+ def from_columns(self) -> list[DatasetField]:
+ return list(self._from_columns)
+
+ @property
+ def to_columns(self) -> list[DatasetField]:
+ return list(self._to_columns)
+
+ @property
+ def ai_context(self) -> AiContext | None:
+ return self._ai_context
+
+ @property
+ def custom_extensions(self) -> list[CustomExtension]:
+ return list(self._custom_extensions)
+
+ def __str__(self) -> str:
+ return self._name
+
+
+class Metric:
+ """Logical-model-level metric defined as a multi-dialect aggregate expression."""
+ _name: str
+ _expression: DialectExpressionSet
+ _description: str | None
+ _ai_context: AiContext | None
+ _custom_extensions: list[CustomExtension]
+
+ def __init__(
+ self,
+ name: str,
+ expression: DialectExpressionSet,
+ description: str | None = None,
+ ai_context: AiContext | None = None,
+ custom_extensions: list[CustomExtension] | None = None,
+ ):
+ self._name = name
+ self._expression = expression
+ self._description = description
+ self._ai_context = ai_context
+ self._custom_extensions = custom_extensions or []
+
+ @property
+ def name(self) -> str:
+ return self._name
+
+ @property
+ def expression(self) -> DialectExpressionSet:
+ return self._expression
+
+ @property
+ def description(self) -> str | None:
+ return self._description
+
+ @property
+ def ai_context(self) -> AiContext | None:
+ return self._ai_context
+
+ @property
+ def custom_extensions(self) -> list[CustomExtension]:
+ return list(self._custom_extensions)
+
+
+class SemanticModel:
+ """Bundle of datasets, join paths and metrics. One or more SemanticModels
+ can feed a single OntologyMapping (see spec)."""
+ _name: str
+ _description: str | None
+ _ai_context: AiContext | None
+ _datasets: list[Dataset]
+ _join_paths: list[JoinPath]
+ _metrics: list[Metric]
+ _custom_extensions: list[CustomExtension]
+ _dataset_name_map: dict[str, Dataset]
+ _join_path_name_map: dict[str, JoinPath]
+ _metric_name_map: dict[str, Metric]
+
+ def __init__(
+ self,
+ name: str,
+ description: str | None = None,
+ ai_context: AiContext | None = None,
+ custom_extensions: list[CustomExtension] | None = None,
+ ):
+ self._name = name
+ self._description = description
+ self._ai_context = ai_context
+ self._datasets = []
+ self._join_paths = []
+ self._metrics = []
+ self._custom_extensions = custom_extensions or []
+ self._dataset_name_map = {}
+ self._join_path_name_map = {}
+ self._metric_name_map = {}
+
+ @property
+ def name(self) -> str:
+ return self._name
+
+ @property
+ def description(self) -> str | None:
+ return self._description
+
+ @property
+ def ai_context(self) -> AiContext | None:
+ return self._ai_context
+
+ @property
+ def datasets(self) -> list[Dataset]:
+ return list(self._datasets)
+
+ @property
+ def join_paths(self) -> list[JoinPath]:
+ return list(self._join_paths)
+
+ @property
+ def metrics(self) -> list[Metric]:
+ return list(self._metrics)
+
+ @property
+ def custom_extensions(self) -> list[CustomExtension]:
+ return list(self._custom_extensions)
+
+ def add_dataset(self, dataset: Dataset) -> None:
+ if dataset.name in self._dataset_name_map:
+ raise ValueError(f"Dataset '{dataset.name}' already exists in logical model '{self._name}'")
+ self._datasets.append(dataset)
+ self._dataset_name_map[dataset.name] = dataset
+
+ def add_join_path(self, join_path: JoinPath) -> None:
+ if join_path.name in self._join_path_name_map:
+ raise ValueError(f"JoinPath '{join_path.name}' already exists in logical model '{self._name}'")
+ self._join_paths.append(join_path)
+ self._join_path_name_map[join_path.name] = join_path
+
+ def add_metric(self, metric: Metric) -> None:
+ if metric.name in self._metric_name_map:
+ raise ValueError(f"Metric '{metric.name}' already exists in logical model '{self._name}'")
+ self._metrics.append(metric)
+ self._metric_name_map[metric.name] = metric
+
+ def lookup_dataset(self, name: str) -> Dataset | None:
+ return self._dataset_name_map.get(name)
+
+ def lookup_join_path(self, name: str) -> JoinPath | None:
+ return self._join_path_name_map.get(name)
+
+ def lookup_metric(self, name: str) -> Metric | None:
+ return self._metric_name_map.get(name)
+
+
+# ---------------------------------------------------------------------------
+# Ontology mapping (tree-shaped)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ObjectMapping:
+ """Maps to objects of some concept — either a direct `expression` (value
+ types / simple-id entities) or `referent_mappings` (compound id). XOR —
+ never both.
+
+ `expression` carries the *parsed* mapping expression: a `DatasetField`
+ when it resolves to a single field reference, or a `Formula` for richer
+ expressions. The forward converter parses the spec's raw string and the
+ reverse converter reconstructs it — storing the parsed form rather than the
+ raw string lets callers introspect the mapping target."""
+ concept: Concept | None = None
+ expression: DatasetField | Formula | None = None
+ referent_mappings: list[ReferentMapping] | None = None
+
+ def __post_init__(self) -> None:
+ has_expr = self.expression is not None
+ has_refs = self.referent_mappings is not None
+ if has_expr and has_refs:
+ raise ValueError("ObjectMapping must not have both expression and referent_mappings")
+ if not has_expr and not has_refs:
+ raise ValueError("ObjectMapping must have either expression or referent_mappings")
+
+
+@dataclass
+class ReferentMapping:
+ """Locates an entity object by walking one of its identifying relationships.
+
+ `expression`, like ObjectMapping's, is the parsed result — a `DatasetField`
+ for simple references or a `Formula` for richer expressions. Nested
+ `referent_mappings` descend into compound identifiers."""
+ relationship: Relationship
+ expression: DatasetField | Formula | None = None
+ referent_mappings: list[ReferentMapping] | None = None
+
+ def __post_init__(self) -> None:
+ has_expr = self.expression is not None
+ has_refs = self.referent_mappings is not None
+ if has_expr and has_refs:
+ raise ValueError("ReferentMapping must not have both expression and referent_mappings")
+ if not has_expr and not has_refs:
+ raise ValueError("ReferentMapping must have either expression or referent_mappings")
+
+
+@dataclass
+class LinkMapping:
+ """A node in the link-mapping tree. The arity of `relationship` equals the
+ node's depth (top-level = unary, depth 2 = binary, ...). `children` extend
+ the mapped tuple by one role each, sharing this node's `object_mapping`."""
+ object_mapping: ObjectMapping
+ relationship: Relationship | None = None
+ children: list[LinkMapping] | None = None
+
+
+@dataclass
+class ConceptMapping:
+ """Mappings that populate one concept and the relationships under it."""
+ concept: Concept
+ object_mappings: list[ObjectMapping] = field(default_factory=list)
+ link_mappings: list[LinkMapping] = field(default_factory=list)
+
+
+class OntologyMapping:
+ """Binds a logical model to an ontology and declares how its fields
+ populate the ontology's concepts and relationships."""
+ _name: str
+ _description: str | None
+ _ontology: OntologyComponent
+ _semantic_model: SemanticModel
+ _concept_mappings: list[ConceptMapping]
+
+ def __init__(
+ self,
+ name: str,
+ ontology: OntologyComponent,
+ semantic_model: SemanticModel,
+ description: str | None = None,
+ ):
+ self._name = name
+ self._description = description
+ self._ontology = ontology
+ self._semantic_model = semantic_model
+ self._concept_mappings = []
+
+ @property
+ def name(self) -> str:
+ return self._name
+
+ @property
+ def description(self) -> str | None:
+ return self._description
+
+ @property
+ def ontology(self) -> OntologyComponent:
+ return self._ontology
+
+ @property
+ def semantic_model(self) -> SemanticModel:
+ return self._semantic_model
+
+ @property
+ def concept_mappings(self) -> list[ConceptMapping]:
+ return list(self._concept_mappings)
+
+ def add_concept_mapping(self, cm: ConceptMapping) -> None:
+ self._concept_mappings.append(cm)
+
+
+# ---------------------------------------------------------------------------
+# Observer protocol + Ontology component (mirrors OntologyComponent in spec)
+# ---------------------------------------------------------------------------
+
+class OntologyObserver(Protocol):
+ """Structural interface for objects that want to be notified when concepts
+ or requires are added to an OntologyComponent. Implement both methods
+ and pass an instance to OntologyComponent.register()."""
+
+ def on_concept_added(self, concept: Concept) -> None: ...
+
+ def on_require_added(self, require: Formula) -> None: ...
+
+
+class OntologyComponent:
+ """Structural container for concepts, relationships, constraints, and rules.
+ Document-level metadata (name, description, ai_context) lives on OssieOntology."""
+ _concepts: list[Concept]
+ _relationships: list[Relationship]
+ _requires: list[Formula]
+ _concept_name_map: dict[str, Concept]
+ _relationship_name_map: dict[str, Relationship]
+ _observers: list[OntologyObserver]
+
+ def __init__(self):
+ self._concepts = []
+ self._relationships = []
+ self._requires = []
+ self._concept_name_map = {}
+ self._relationship_name_map = {}
+ self._observers = []
+
+ def register(self, observer: OntologyObserver) -> None:
+ self._observers.append(observer)
+ for concept in self._concepts:
+ observer.on_concept_added(concept)
+ for require in self._requires:
+ observer.on_require_added(require)
+
+ def add_concept(self, concept: Concept) -> None:
+ if concept.name in self._concept_name_map:
+ raise ValueError(f"Concept '{concept.name}' already exists in the ontology")
+ self._concepts.append(concept)
+ self._concept_name_map[concept.name] = concept
+ for obs in self._observers:
+ obs.on_concept_added(concept)
+
+ def add_relationship(self, relationship: Relationship) -> None:
+ full_name = relationship.full_name
+ if full_name in self._relationship_name_map:
+ raise ValueError(f"Relationship '{full_name}' already exists in the ontology")
+ self._relationships.append(relationship)
+ self._relationship_name_map[full_name] = relationship
+
+ def add_require(self, require: Formula) -> None:
+ self._requires.append(require)
+ for obs in self._observers:
+ obs.on_require_added(require)
+
+ def concepts(self, exclude_builtin: bool = False) -> list[Concept]:
+ if exclude_builtin:
+ return [c for c in self._concepts if not c.is_builtin]
+ return list(self._concepts)
+
+ @property
+ def relationships(self) -> list[Relationship]:
+ return list(self._relationships)
+
+ @property
+ def requires(self) -> list[Formula]:
+ return list(self._requires)
+
+ def lookup_concept(self, name: str | None) -> Concept | None:
+ """The concept called *name*, or None. Adds nothing.
+
+ Use `ensure_builtin_concept` where a builtin should be created on
+ demand: this one answers "is that name taken?", and callers rely on it
+ for exactly that.
+ """
+ if not name:
+ return None
+ return self._concept_name_map.get(name)
+
+ def ensure_builtin_concept(self, name: str | None) -> Concept | None:
+ """The concept called *name*, creating it if *name* is a builtin.
+
+ The mutating half of what `lookup_concept` used to do. Builtins are
+ declared nowhere, so a model that first mentions `String` in a role or a
+ field type gets it added here, on demand.
+ """
+ existing = self.lookup_concept(name)
+ if existing is not None:
+ return existing
+ if name in BUILTIN_CONCEPTS:
+ concept = Concept(name=name, builtin=True, is_component=False)
+ self.add_concept(concept)
+ return concept
+ return None
+
+ def lookup_concept_relationship(self, concept: Concept, name: str) -> Relationship | None:
+ rel = self._relationship_name_map.get(f"{concept.name}.{name}")
+ if rel:
+ return rel
+ for ext in concept.extends:
+ rel = self.lookup_concept_relationship(ext, name)
+ if rel:
+ return rel
+ return None
+
+
+# ---------------------------------------------------------------------------
+# Root semantic model (per OssieSpec)
+# ---------------------------------------------------------------------------
+
+class OssieOntology:
+ _name: str
+ _description: str | None
+ _ai_context: AiContext | None
+ _version: str | None
+ _ontology: OntologyComponent
+ _ontology_mappings: list[OntologyMapping]
+ _ontology_mapping_index: dict[str, OntologyMapping]
+
+ def __init__(
+ self,
+ name: str,
+ ontology: OntologyComponent,
+ description: str | None = None,
+ ai_context: AiContext | None = None,
+ version: str | None = None,
+ ):
+ self._name = name
+ self._description = description
+ self._ai_context = ai_context
+ self._version = version
+ self._ontology = ontology
+ self._ontology_mappings = []
+ self._ontology_mapping_index = {}
+
+ @property
+ def name(self) -> str:
+ return self._name
+
+ @property
+ def description(self) -> str | None:
+ return self._description
+
+ @property
+ def ai_context(self) -> AiContext | None:
+ return self._ai_context
+
+ @property
+ def version(self) -> str | None:
+ return self._version
+
+ @property
+ def ontology(self) -> OntologyComponent:
+ return self._ontology
+
+ def add_ontology_mapping(self, mapping: OntologyMapping) -> None:
+ if mapping.name in self._ontology_mapping_index:
+ raise ValueError(f"OntologyMapping '{mapping.name}' already exists in model")
+ self._ontology_mappings.append(mapping)
+ self._ontology_mapping_index[mapping.name] = mapping
+
+ @property
+ def ontology_mappings(self) -> list[OntologyMapping]:
+ return list(self._ontology_mappings)
+
+
+# ---------------------------------------------------------------------------
+# Verbalization parser (handles a list of verbalization patterns)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Verbalization:
+ text: str
+
+
+@dataclass
+class RelationshipVerbalization(Verbalization):
+ roles: list[VerbalizationRole]
+
+
+@dataclass
+class VerbalizationRole:
+ concept: Concept
+ name: str | None = None
+ preceding_text: str | None = None
+ prefix: str | None = None
+ following_text: str | None = None
+ postfix: str | None = None
+
+ def verbalization_name(self) -> str:
+ return f"{{{self.concept.name}:{self.name}}}" if self.name else f"{{{self.concept.name}}}"
+
+
+_CONCEPT_TOKEN_RE = re.compile(r"\{([^:}]+?)(?::([^}]+))?\}")
+
+
+def parse_verbalizations(
+ relationship: Relationship, verbalizations: list[str] | None
+) -> list[RelationshipVerbalization]:
+ if not verbalizations:
+ return [_build_verbalization(relationship)]
+ return [_parse_verbalization(relationship, v) for v in verbalizations]
+
+
+def _build_verbalization(relationship: Relationship) -> RelationshipVerbalization:
+ roles: list[VerbalizationRole] = []
+ parts: list[str] = []
+ for role in relationship.roles:
+ vr = VerbalizationRole(concept=role.player, name=role.explicit_name)
+ roles.append(vr)
+ parts.append(vr.verbalization_name())
+ if relationship.unary:
+ return RelationshipVerbalization(text=f"{relationship.name} {parts[0]}", roles=roles)
+ return RelationshipVerbalization(text=" has ".join(parts), roles=roles)
+
+
+def _parse_verbalization(relationship: Relationship, verbalization: str) -> RelationshipVerbalization:
+ """
+ Parse a verbalization string into an ordered list of :class:`VerbalizationRole` objects.
+
+ Format example:
+
+ 'every chain- super {Store} reports returns of {Item} big -box for average- {Amount:amt}'
+
+ The string may contain any number of ``{Concept}`` / ``{Concept:roleName}`` tokens.
+ Text between tokens is split uniformly by :func:`_split_segment` into
+ ``(postfix, middle, prefix)`` and assigned to the adjacent roles:
+
+ +-----------+------------------------+------------------------------+----------------------+
+ | position | postfix | middle | prefix |
+ +===========+========================+==============================+======================+
+ | segment 0 | *ignored* | → roles[0].preceding_text | → roles[0].prefix |
+ +-----------+------------------------+------------------------------+----------------------+
+ | segment i | → roles[i-1].postfix | → roles[i-1].following_text | → roles[i].prefix |
+ +-----------+------------------------+------------------------------+----------------------+
+ | last seg | → roles[-1].postfix | → roles[-1].following_text | *ignored* |
+ +-----------+------------------------+------------------------------+----------------------+
+ """
+ tokens = list(_CONCEPT_TOKEN_RE.finditer(verbalization))
+ if len(tokens) != relationship.arity:
+ raise ValueError(
+ f"Number of roles in verbalization '{verbalization}' for relationship "
+ f"{relationship.full_name} doesn't match its arity ({relationship.arity})"
+ )
+ segments: list[str] = []
+ roles: list[VerbalizationRole] = []
+ prev_end = 0
+ for idx, m in enumerate(tokens):
+ role = relationship.role(idx)
+ segments.append(verbalization[prev_end:m.start()].strip())
+ verb_concept_name = m.group(1).strip()
+ rel_role_name = role.explicit_name
+ verb_role_name = m.group(2).strip() if m.group(2) else None
+ if rel_role_name != verb_role_name or role.player.name != verb_concept_name:
+ raise ValueError(
+ f"Role {idx}: '{role.player.name}:{role.name}' "
+ f"does not match verbalization role '{verb_concept_name}:{verb_role_name}'"
+ )
+ roles.append(VerbalizationRole(concept=role.player, name=verb_role_name))
+ prev_end = m.end()
+ segments.append(verbalization[prev_end:].strip())
+ for i, seg in enumerate(segments):
+ if not seg:
+ continue
+ postfix, middle, prefix = _split_segment(seg)
+ if i == 0:
+ roles[0].preceding_text = middle
+ roles[0].prefix = prefix
+ elif i == len(tokens):
+ roles[-1].postfix = postfix
+ roles[-1].following_text = middle
+ else:
+ roles[i - 1].postfix = postfix
+ roles[i - 1].following_text = middle
+ roles[i].prefix = prefix
+ return RelationshipVerbalization(text=verbalization, roles=roles)
+
+
+def _split_segment(segment: str) -> tuple[str | None, str | None, str | None]:
+ """Split a text segment into ``(postfix, middle, prefix)`` using the dash
+ conventions (dashes are stripped from the returned text):
+
+ - **postfix** — text glued to the *preceding* concept. A leading-dash word
+ (e.g. ``-box``) marks the segment's opening run as a postfix: the first
+ word plus any following dash-prefixed words (so ``"big -box"`` -> ``"big box"``).
+ - **prefix** — text glued to the *following* concept. A trailing-dash word
+ (e.g. ``chain-``) marks the start of the closing run (so ``"chain- super"``
+ -> ``"chain super"``).
+ - **middle** — the free text left between the postfix and prefix runs.
+
+ See tests/test_verbalization_parsing.py for the full set of expected splits.
+ """
+ words = segment.split()
+ if not words:
+ return None, None, None
+
+ # Postfix run: first word plus any following dash-prefixed words, but only
+ # when the segment actually contains a leading-dash marker somewhere.
+ postfix_end = 0
+ if any(w.startswith("-") for w in words):
+ postfix_end = 1
+ while postfix_end < len(words) and words[postfix_end].startswith("-"):
+ postfix_end += 1
+
+ # Prefix run: begins at the first trailing-dash word (after the postfix run)
+ # and extends to the end of the segment.
+ prefix_start = len(words)
+ for i in range(postfix_end, len(words)):
+ if words[i].endswith("-"):
+ prefix_start = i
+ break
+
+ postfix = " ".join(w.lstrip("-") for w in words[:postfix_end]) if postfix_end > 0 else None
+ prefix = " ".join(w.rstrip("-") for w in words[prefix_start:]) if prefix_start < len(words) else None
+ middle = " ".join(words[postfix_end:prefix_start]) if postfix_end < prefix_start else None
+
+ return postfix, middle, prefix
diff --git a/converters/ontology/src/ossie_ontology/parser/__init__.py b/converters/ontology/src/ossie_ontology/parser/__init__.py
new file mode 100644
index 00000000..049d7a35
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/parser/__init__.py
@@ -0,0 +1,70 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Entrypoint: read a YAML/JSON Ossie spec and produce an OssieOntology."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ossie_ontology.converter.spec_to_ossie.converter import SpecToOssieConverter
+from ossie_ontology.model import OssieOntology, FormulaFactory, MappingFormulaFactory
+from ossie_ontology.spec import OssieSpec
+
+
+class OssieParser:
+ _model: OssieOntology | None
+ _spec: OssieSpec | None
+ _debug: bool
+
+ def __init__(self, debug: bool = False,
+ formula_factory: FormulaFactory | None = None,
+ mapping_formula_factory: MappingFormulaFactory | None = None):
+ self._debug = debug
+ self._model = None
+ self._spec = None
+ self._formula_factory = formula_factory or FormulaFactory()
+ self._mapping_formula_factory = mapping_formula_factory or MappingFormulaFactory()
+
+ def parse(self, path: Path) -> OssieOntology:
+ # Ossie always expects a single spec file.
+ if not path.is_file():
+ raise ValueError(f"Expected a single Ossie spec file, but '{path}' is not a file")
+ raw = OssieParser.load_data(path)
+ self._spec = OssieSpec.model_validate(raw)
+ self._model = SpecToOssieConverter(
+ formula_factory=self._formula_factory, mapping_formula_factory=self._mapping_formula_factory
+ ).convert(self._spec)
+ return self._model
+
+ @staticmethod
+ def load_data(path: Path) -> Any:
+ # Pin UTF-8 so parsing is reproducible regardless of the process locale.
+ content = path.read_text(encoding="utf-8")
+ if path.suffix.lower() == ".json":
+ return json.loads(content)
+ return yaml.safe_load(content)
+
+ def spec(self) -> OssieSpec:
+ spec = self._spec
+ if spec is None:
+ raise RuntimeError("You must call 'parse()' before accessing 'spec()'")
+ return spec
diff --git a/converters/ontology/src/ossie_ontology/spec.py b/converters/ontology/src/ossie_ontology/spec.py
new file mode 100644
index 00000000..377c2821
--- /dev/null
+++ b/converters/ontology/src/ossie_ontology/spec.py
@@ -0,0 +1,272 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+# Default line width for YAML output: bounded so diffs stay reviewable, but wide
+# enough that typical concept/relationship lines aren't wrapped mid-token.
+DEFAULT_YAML_WIDTH = 1000
+
+
+class OssieObject(BaseModel):
+ """Base for all Ossie DTOs. Strict (`extra=forbid`) to surface spec drift early."""
+ model_config = ConfigDict(
+ populate_by_name=True,
+ arbitrary_types_allowed=True,
+ extra="forbid",
+ )
+
+
+# Free-form AI context: either a bare string or a structured object with keys
+# like `instructions`, `synonyms`, `examples` (per core.md).
+AiContext = str | dict[str, Any]
+
+
+class CustomExtension(OssieObject):
+ """Vendor-specific metadata attached to any logical-model element (core.md).
+
+ `data` is a JSON-encoded string so vendors can carry arbitrary payloads
+ without extending the core schema.
+ """
+ vendor_name: str
+ data: str
+
+
+# ---------- Ontology ----------
+
+class Role(OssieObject):
+ """An additional role in a Relationship (the first role is implicit — the
+ container concept). `name` is only required to disambiguate when the same
+ concept plays multiple roles in the same relationship."""
+ concept: str
+ name: str | None = None
+
+
+class Relationship(OssieObject):
+ """A relationship grouped under its first-role concept.
+
+ `roles` enumerates the *additional* roles (the first is the container
+ concept). `multiplicity` constrains the last role; `OneToOne` is only
+ valid for binary relationships. `verbalizes` is a list of natural-language
+ patterns with `{Concept}` or `{Concept:role_name}` placeholders.
+ `derived_by` and `requires` are raw expression strings (parsed elsewhere).
+ """
+ name: str
+ description: str | None = None
+ roles: list[Role] = Field(default_factory=list)
+ verbalizes: list[str] = Field(default_factory=list)
+ multiplicity: Literal["OneToOne", "ManyToOne"] | None = None
+ derived_by: list[str] = Field(default_factory=list)
+ requires: list[str] = Field(default_factory=list)
+
+
+class ConceptComponent(OssieObject):
+ """A concept and the relationships grouped under it.
+
+ A concept is a type-like node in the ontology — either an `EntityType`
+ (a real-world object referenced via other relationships) or a `ValueType`
+ (a data type with extra semantics, which must transitively extend a
+ built-in value type).
+
+ Mirrors the flattened YAML shape:
+
+ { concept: <name>, type: ..., description: ..., extends: [...],
+ identify_by: [...], relationships: [...] }
+
+ where `concept` names the concept and every relationship in
+ `relationships` takes it as the implicit first role. `identify_by` lists
+ the names of relationships (declared under this concept) whose values
+ uniquely reference its objects.
+ """
+ concept: str
+ type: Literal["EntityType", "ValueType"] | None = None
+ description: str | None = None
+ extends: list[str] | None = None
+ identify_by: list[str] = Field(default_factory=list)
+ derived_by: list[str] = Field(default_factory=list)
+ requires: list[str] = Field(default_factory=list)
+ relationships: list[Relationship] = Field(default_factory=list)
+
+
+# ---------- Logical model (per ossie/core.md) ----------
+
+class DialectExpression(OssieObject):
+ """A scalar (non-aggregating) SQL/expression in a specific dialect."""
+ dialect: str
+ expression: str
+
+
+class Expression(OssieObject):
+ """Multi-dialect expression carrier — same logical expression rendered in
+ one or more dialects (e.g. ANSI_SQL + SNOWFLAKE)."""
+ dialects: list[DialectExpression] = Field(default_factory=list)
+
+
+class Dimension(OssieObject):
+ """Dimensional metadata on a DatasetField."""
+ is_time: bool | None = None
+
+
+class DatasetField(OssieObject):
+ """A row-level attribute of a Dataset. `expression` is scalar (no
+ aggregations); use Metric for aggregates."""
+ name: str
+ expression: Expression
+ dimension: Dimension | None = None
+ label: str | None = None
+ description: str | None = None
+ ai_context: AiContext | None = None
+ custom_extensions: list[CustomExtension] = Field(default_factory=list)
+
+
+class Dataset(OssieObject):
+ """A logical dataset (fact or dimension table) backed by `source` — a
+ physical table/view reference or a query."""
+ name: str
+ source: str
+ primary_key: list[str] | None = None
+ unique_keys: list[list[str]] | None = None
+ description: str | None = None
+ ai_context: AiContext | None = None
+ fields: list[DatasetField] = Field(default_factory=list)
+ custom_extensions: list[CustomExtension] = Field(default_factory=list)
+
+
+class JoinPath(OssieObject):
+ """A foreign-key style join between two Datasets: rows in `from` reference
+ rows in `to` by matching `from_columns` against `to_columns` in order.
+ Same arity required on both sides."""
+ name: str
+ from_: str = Field(alias="from")
+ to: str
+ from_columns: list[str]
+ to_columns: list[str]
+ ai_context: AiContext | None = None
+ custom_extensions: list[CustomExtension] = Field(default_factory=list)
+
+
+class Metric(OssieObject):
+ """A model-level quantitative measure defined as an aggregate expression.
+ Can reference fields across multiple Datasets."""
+ name: str
+ expression: Expression
+ description: str | None = None
+ ai_context: AiContext | None = None
+ custom_extensions: list[CustomExtension] = Field(default_factory=list)
+
+
+class SemanticModel(OssieObject):
+ """A complete logical/semantic model (the body that the core spec calls
+ `semantic_model`): datasets plus the join paths and metrics defined over
+ them. One or more SemanticModels can feed a single OntologyMapping."""
+ name: str
+ description: str | None = None
+ ai_context: AiContext | None = None
+ datasets: list[Dataset] = Field(default_factory=list)
+ relationships: list[JoinPath] = Field(default_factory=list)
+ metrics: list[Metric] = Field(default_factory=list)
+ custom_extensions: list[CustomExtension] = Field(default_factory=list)
+
+
+# ---------- Ontology mapping ----------
+
+class ReferentMapping(OssieObject):
+ """Locates an entity object by walking one of its identifying
+ relationships. Carries either a leaf `expression` (SQL over dataset
+ fields) or a nested `referent_mappings` list when the referenced concept
+ is itself an entity with a compound/recursive identifier."""
+ relationship: str
+ expression: str | None = None
+ referent_mappings: list[ReferentMapping] | None = None
+
+
+class ObjectMapping(OssieObject):
+ """Maps to objects of some concept. Either a direct scalar `expression`
+ (for value types or simple-id entities) or `referent_mappings` (for
+ entities with compound identifiers). XOR — never both."""
+ concept: str | None = None
+ expression: str | None = None
+ referent_mappings: list[ReferentMapping] | None = None
+
+
+class LinkMapping(OssieObject):
+ """A node in the link-mapping tree. The arity of `relationship` equals
+ the node's depth (top-level = unary, depth 2 = binary, etc.). `children`
+ extend the mapped tuple by one role each, sharing this node's
+ `object_mapping` as their prefix to avoid duplication."""
+ object_mapping: ObjectMapping
+ relationship: str | None = None
+ children: list[LinkMapping] | None = None
+
+
+class ConceptMapping(OssieObject):
+ """Mappings that populate one concept and the relationships grouped under
+ it. `object_mappings` populate the concept's objects; `link_mappings` is
+ a forest of trees populating its relationships."""
+ concept: str
+ object_mappings: list[ObjectMapping] = Field(default_factory=list)
+ link_mappings: list[LinkMapping] = Field(default_factory=list)
+
+
+class OntologyMapping(OssieObject):
+ """Binds a semantic model to the document ontology, then declares how its
+ fields populate the ontology's concepts and relationships."""
+ name: str
+ description: str | None = None
+ semantic_model: SemanticModel
+ concept_mappings: list[ConceptMapping] = Field(default_factory=list)
+
+
+# ---------- Root ----------
+
+class OssieSpec(OssieObject):
+ """Root Ossie document: a single ontology definition and the ontology
+ mappings that wire semantic models into it."""
+ version: str | None = None
+ name: str
+ description: str | None = None
+ requires: list[str] = Field(default_factory=list)
+ ai_context: AiContext | None = None
+ ontology: list[ConceptComponent] = Field(default_factory=list)
+ ontology_mappings: list[OntologyMapping] = Field(default_factory=list)
+
+ @classmethod
+ def load_yaml(cls, text: str) -> OssieSpec:
+ return cls.model_validate(yaml.safe_load(text))
+
+ def dump_dict(self) -> dict:
+ return self.model_dump(exclude_none=True, exclude_defaults=True, by_alias=True)
+
+ def dump_yaml(self, width: int = DEFAULT_YAML_WIDTH) -> str:
+ # A bounded width keeps output reasonably wrapped (reviewable diffs) while
+ # staying deterministic. Callers can pass a large width to disable wrapping.
+ return yaml.safe_dump(self.dump_dict(), sort_keys=False, width=width)
+
+
+# `ReferentMapping` and `LinkMapping` are self-referential (each can contain a
+# list of itself). Combined with `from __future__ import annotations`, every
+# annotation is a string at class-definition time, so the self-reference is an
+# unresolved forward ref. `model_rebuild()` re-walks the schema once the class
+# is fully defined and pins the forward ref to the real type — without it,
+# validating a payload with nested children raises PydanticUndefinedAnnotation.
+ReferentMapping.model_rebuild()
+LinkMapping.model_rebuild()
diff --git a/converters/ontology/tests/__init__.py b/converters/ontology/tests/__init__.py
new file mode 100644
index 00000000..13a83393
--- /dev/null
+++ b/converters/ontology/tests/__init__.py
@@ -0,0 +1,16 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
diff --git a/converters/ontology/tests/conftest.py b/converters/ontology/tests/conftest.py
new file mode 100644
index 00000000..947c4eb0
--- /dev/null
+++ b/converters/ontology/tests/conftest.py
@@ -0,0 +1,101 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Shared fixtures for the ontology converter test suite."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from ossie_ontology.model import OssieOntology
+from ossie_ontology.parser import OssieParser
+
+# Test inputs are vendored under tests/fixtures/ so the suite runs even when the
+# repo-level examples/ directory isn't present (e.g. from an sdist/wheel or a
+# subset checkout). tests/test_examples_in_sync.py guards against drift from the
+# canonical examples/ copies.
+_FIXTURES_DIR = Path(__file__).resolve().parent / "fixtures"
+
+# The snapshot files under tests/snapshots/ carry the ASF license header inline,
+# so that a source-release audit (Apache RAT) finds a header on every file in the
+# tree without needing an exclude list. pytest-snapshot compares the whole file
+# byte-for-byte, so the header has to be part of the asserted value; the snapshot
+# fixture below applies it, which also means `pytest --snapshot-update` reproduces
+# it and it cannot drift.
+#
+# Both snapshot formats tolerate it: '#' starts a comment in YAML, and the
+# structure snapshot is free-form text.
+LICENSE_HEADER = """\
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+
+
+@pytest.fixture
+def snapshot(snapshot):
+ """pytest-snapshot's fixture, with the ASF license header applied for free.
+
+ Overrides the plugin fixture so tests assert only their own payload and the
+ header stays in one place. Applies on both paths: comparison prepends it to
+ the expected value, and --snapshot-update writes it into the file.
+
+ Note: only assert_match is wrapped, since that is all this suite uses. A test
+ reaching for assert_match_dir would need the same treatment.
+ """
+ assert_match = snapshot.assert_match
+
+ def assert_match_with_license(value: str | bytes, snapshot_name: str | Path) -> None:
+ __tracebackhide__ = True
+ if isinstance(value, bytes):
+ assert_match(LICENSE_HEADER.encode() + value, snapshot_name)
+ else:
+ assert_match(LICENSE_HEADER + value, snapshot_name)
+
+ snapshot.assert_match = assert_match_with_license
+ return snapshot
+
+
+@pytest.fixture(scope="session")
+def fixtures_dir() -> Path:
+ return _FIXTURES_DIR
+
+
+@pytest.fixture(scope="session")
+def flights_path(fixtures_dir: Path) -> Path:
+ return fixtures_dir / "flights.yaml"
+
+
+@pytest.fixture
+def flights_model(flights_path: Path) -> OssieOntology:
+ return OssieParser().parse(flights_path)
\ No newline at end of file
diff --git a/converters/ontology/tests/fixtures/flights.yaml b/converters/ontology/tests/fixtures/flights.yaml
new file mode 100644
index 00000000..803ff73d
--- /dev/null
+++ b/converters/ontology/tests/fixtures/flights.yaml
@@ -0,0 +1,1111 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+version: 0.2.0.dev0
+name: Flights
+description: Ontology of flights into and out of airports.
+requires:
+ - COUNT[Airport] > 0 # there must be at least one Airport
+ - COUNT[Carrier] > 0 # there must be at least one Carrier
+ontology:
+- concept: NrFeet
+ description: "Unit of measure for distance in feet"
+ type: ValueType
+ extends: [ Decimal ]
+- concept: NrPounds
+ description: "Unit of measure for weight in pounds"
+ type: ValueType
+ extends: [ Integer ]
+- concept: NrMiles
+ description: "Unit of measure for distance in miles"
+ type: ValueType
+ extends: [ Decimal ]
+- concept: NrMinutes
+ description: "Unit of measure for time in minutes"
+ type: ValueType
+ extends: [ Decimal ]
+- concept: CancelationCode
+ description: "The single character code that identifies the reason a flight is canceled"
+ type: ValueType
+ extends: [ String ]
+ requires: [ CancelationCode == 'A' OR CancelationCode == 'B' OR CancelationCode == 'C' OR CancelationCode == 'D' ]
+- concept: Capacity
+ description: "The capacity of an aircraft, measured in pounds."
+ type: ValueType
+ extends: [ NrPounds ]
+- concept: DegreesLatitude
+ type: ValueType
+ extends: [ Decimal ]
+ requires: [ DegreesLatitude <= 90, DegreesLatitude >= -90 ]
+- concept: DegreesLongitude
+ type: ValueType
+ extends: [ Decimal ]
+ requires: [ DegreesLongitude <= 180, DegreesLongitude >= -180 ]
+- concept: Polygon
+ description: "A polygon represented as a list of vertices, where each vertex is a pair of latitude and longitude coordinates."
+ type: ValueType
+ extends: [ String ]
+- concept: CityName
+ type: ValueType
+ extends: [ String ]
+- concept: Delay
+ type: ValueType
+ extends: [ NrMinutes ]
+- concept: Distance
+ type: ValueType
+ extends: [ NrMiles ]
+- concept: DistanceGroup
+ description: "A number used to group distances of different lengths, where 1 groups the shortest and 10 the longest."
+ type: ValueType
+ extends: [ Integer ]
+ requires: [ 1 <= DistanceGroup, DistanceGroup <= 10 ]
+- concept: RunwayGeometry
+ description: "A polygon that models the shape of a runway."
+ type: ValueType
+ extends: [ Polygon ]
+- concept: RunwayLength
+ description: "The unit for measuring the lengths of runways in American airports."
+ type: ValueType
+ extends: [ NrFeet ]
+- concept: RunwayDesignator
+ description: "Used to distinguish runways within a given airport."
+ type: ValueType
+ extends: [ String ]
+- concept: SerialNr
+ type: ValueType
+ extends: [ String ]
+- concept: StateCode
+ type: ValueType
+ extends: [ String ]
+- concept: StateName
+ type: ValueType
+ extends: [ String ]
+- concept: TailNr
+ type: ValueType
+ extends: [ String ]
+- concept: Year
+ type: ValueType
+ extends: [ String ]
+- concept: CancelationReason
+ description: "A curated set of reasons that explain why a flight is canceled"
+ type: EntityType
+ identify_by: [ code ]
+ relationships:
+ - name: code
+ roles:
+ - concept: CancelationCode
+ verbalizes: [ '{CancelationReason} is identified by {CancelationCode}']
+ multiplicity: OneToOne
+ - name: description
+ roles:
+ - concept: String
+ verbalizes: [ '{CancelationReason} has description- {String}' ] # The hyphen after "description" is significant when verbalizing constraints
+ multiplicity: ManyToOne # Each CancelationReason has at most one description String
+- concept: State
+ type: EntityType
+ identify_by: [ code ]
+ relationships:
+ - name: code
+ roles:
+ - concept: StateCode
+ verbalizes:
+ - '{State} is identified by {StateCode}'
+ multiplicity: OneToOne
+ - name: name
+ roles:
+ - concept: StateName
+ verbalizes:
+ - '{State} has {StateName}'
+ multiplicity: ManyToOne
+- concept: City
+ type: EntityType
+ identify_by: [ name, state ]
+ relationships:
+ - name: name
+ roles:
+ - concept: CityName
+ verbalizes:
+ - '{City} has {CityName}'
+ multiplicity: ManyToOne
+ - name: state
+ roles:
+ - concept: State
+ verbalizes:
+ - '{City} is located in {State}'
+ multiplicity: ManyToOne
+- concept: Runway
+ type: EntityType
+ identify_by: [ designator, airport ]
+ relationships:
+ - name: airport
+ roles:
+ - concept: Airport
+ verbalizes:
+ - '{Runway} belongs to {Airport}'
+ multiplicity: ManyToOne
+ - name: designator
+ roles:
+ - concept: RunwayDesignator
+ verbalizes:
+ - '{Runway} uses {RunwayDesignator}'
+ multiplicity: ManyToOne
+ - name: length
+ roles:
+ - concept: RunwayLength
+ verbalizes:
+ - '{Runway} has {RunwayLength}'
+ multiplicity: ManyToOne
+ - name: geometry
+ roles:
+ - concept: RunwayGeometry
+ verbalizes:
+ - '{Runway} has {RunwayGeometry}'
+ multiplicity: ManyToOne
+- concept: ManufacturerName
+ type: ValueType
+ extends: [ String ]
+- concept: Manufacturer
+ type: EntityType
+ identify_by: [ name ]
+ relationships:
+ - name: name
+ roles:
+ - concept: ManufacturerName
+ verbalizes:
+ - '{Manufacturer} is identified by {ManufacturerName}'
+ multiplicity: OneToOne
+- concept: ModelName
+ type: ValueType
+ extends: [ String ]
+- concept: Model
+ type: EntityType
+ identify_by: [ name, manufacturer ]
+ relationships:
+ - name: name
+ roles:
+ - concept: ModelName
+ verbalizes:
+ - '{Model} has {ModelName}'
+ multiplicity: ManyToOne
+ - name: manufacturer
+ roles:
+ - concept: Manufacturer
+ verbalizes:
+ - '{Model} is manufactured by {Manufacturer}'
+ multiplicity: ManyToOne
+- concept: Aircraft
+ type: EntityType
+ identify_by: [ tailnum ]
+ relationships:
+ - name: serial_number
+ roles:
+ - concept: SerialNr
+ verbalizes:
+ - '{Aircraft} has {SerialNr}'
+ multiplicity: ManyToOne
+ - name: name
+ roles:
+ - concept: String
+ verbalizes:
+ - '{Aircraft} has name {String}'
+ multiplicity: ManyToOne
+ - name: number_of_seats
+ roles:
+ - concept: Integer
+ verbalizes:
+ - '{Aircraft} has {Integer} seats'
+ multiplicity: ManyToOne
+ - name: tailnum
+ roles:
+ - concept: TailNr
+ verbalizes:
+ - '{Aircraft} is identified by {TailNr}'
+ multiplicity: OneToOne
+ - name: model
+ roles:
+ - concept: Model
+ verbalizes:
+ - '{Aircraft} has {Model}'
+ multiplicity: ManyToOne
+ - name: year_manufactured
+ roles:
+ - concept: Year
+ verbalizes:
+ - '{Aircraft} was manufactured in {Year}'
+ multiplicity: ManyToOne
+ - name: capacity
+ roles:
+ - concept: Capacity
+ verbalizes:
+ - '{Aircraft} has {Capacity}'
+ multiplicity: ManyToOne
+ - name: carrier
+ roles:
+ - concept: Carrier
+ verbalizes:
+ - '{Aircraft} is operated by {Carrier}'
+ multiplicity: ManyToOne
+- concept: AirportName
+ type: ValueType
+ extends: [ String ]
+- concept: AirportCode
+ description: "The three-letter IATA code for the airport."
+ type: ValueType
+ extends: [ String ]
+- concept: AirportId
+ description: "Five digit number used as an alternate identifier for airports."
+ type: ValueType
+ extends: [ String ]
+- concept: Airport
+ type: EntityType
+ identify_by: [ code ]
+ requires: [ Airport.latitude, Airport.longitude ]
+ relationships:
+ - name: city
+ roles:
+ - concept: City
+ verbalizes:
+ - '{Airport} is located in {City}'
+ multiplicity: ManyToOne
+ - name: serves
+ roles:
+ - concept: Market
+ verbalizes:
+ - '{Airport} serves {Market}'
+ multiplicity: ManyToOne
+ - name: average_departure_delay
+ roles:
+ - concept: Delay
+ verbalizes:
+ - '{Airport} has average- departure {Delay}' # The hyphen after "average" has significance when verbalizing constraints
+ multiplicity: ManyToOne # Each Airport has at most one average departure Delay
+ derived_by: [ 'Delay == AVG[Flight.departure_delay WHERE Airport == Flight.route.departure GROUP BY Airport]' ]
+ - name: longitude
+ roles:
+ - concept: DegreesLongitude
+ verbalizes:
+ - '{Airport} centers at {DegreesLongitude}'
+ multiplicity: ManyToOne
+ - name: average_arrival_delay
+ roles:
+ - concept: Delay
+ verbalizes:
+ - '{Airport} has average- arrival {Delay}' # The hyphen after "average" has significance when verbalizing constraints
+ multiplicity: ManyToOne # Each Airport has at most one average arrival Delay
+ derived_by: [ 'Delay == AVG[Flight.arrival_delay WHERE Airport == Flight.route.destination GROUP BY Airport]' ]
+ - name: name
+ roles:
+ - concept: AirportName
+ verbalizes:
+ - '{Airport} has {AirportName}'
+ multiplicity: ManyToOne
+ - name: code
+ roles:
+ - concept: AirportCode
+ verbalizes:
+ - '{Airport} has {AirportCode}'
+ multiplicity: OneToOne
+ - name: latitude
+ roles:
+ - concept: DegreesLatitude
+ verbalizes:
+ - '{Airport} centers at {DegreesLatitude}'
+ multiplicity: ManyToOne
+- concept: MarketName
+ type: ValueType
+ extends: [ String ]
+- concept: Market
+ type: EntityType
+ identify_by: [name]
+ relationships:
+ - name: name
+ roles: [ { concept: MarketName }]
+ verbalizes: [ '{Market} is identified by {MarketName}' ]
+ multiplicity: OneToOne
+- concept: FlightNr
+ description: "The IATA flight number, which is typically a combination of the airline's IATA code and a numeric code (e.g., 'AA1234')."
+ type: ValueType
+ extends: [ String ]
+- concept: FlightId
+ description: "A unique identifier for an instance of a flight"
+ type: ValueType
+ extends: [ String ]
+- concept: Flight
+ type: EntityType
+ identify_by: [ id ]
+ relationships:
+ - name: departure_delay
+ roles:
+ - concept: Delay
+ verbalizes:
+ - '{Flight} has departure- {Delay}' # The hyphen after "departure" has significance when verbalizing constraints
+ multiplicity: ManyToOne # Each Flight has at most one departure Delay
+ - name: number
+ roles:
+ - concept: FlightNr
+ verbalizes:
+ - '{Flight} has {FlightNr}'
+ multiplicity: ManyToOne
+ - name: scheduled_departure
+ roles: [ { concept: DateTime } ]
+ verbalizes:
+ - '{Flight} is scheduled to depart at {DateTime}'
+ multiplicity: ManyToOne
+ requires: [ Flight.scheduled_departure < Flight.scheduled_arrival ]
+ - name: arrival_delay
+ roles:
+ - concept: Delay
+ verbalizes:
+ - '{Flight} has arrival- {Delay}' # The hyphen after "arrival" has significance when verbalizing constraints
+ multiplicity: ManyToOne # Each Flight has at most one arrival Delay
+ - name: canceled
+ verbalizes:
+ - '{Flight} was canceled'
+ - name: canceled_due_to
+ roles:
+ - concept: CancelationReason
+ verbalizes:
+ - '{Flight} was canceled due to {CancelationReason}'
+ multiplicity: ManyToOne
+ - name: distance
+ roles:
+ - concept: Distance
+ verbalizes:
+ - '{Flight} spans actual- {Distance}' # The hyphen after "actual" has significance when verbalizing constraints
+ multiplicity: ManyToOne # Each Flight spans at most one actual Distance
+ - name: id
+ roles:
+ - concept: FlightId
+ verbalizes:
+ - '{Flight} is identified by {FlightId}'
+ multiplicity: OneToOne
+ - name: scheduled_arrival
+ roles:
+ - concept: DateTime
+ verbalizes:
+ - '{Flight} is scheduled to arrive at {DateTime}'
+ multiplicity: ManyToOne
+ - name: registers_longitude_series
+ roles:
+ - concept: DateTime
+ - concept: DegreesLongitude
+ verbalizes:
+ - '{Flight} at {DateTime} registers {DegreesLongitude}'
+ multiplicity: ManyToOne
+ - name: registers_latitude_series
+ roles:
+ - concept: DateTime
+ - concept: DegreesLatitude
+ verbalizes:
+ - '{Flight} at {DateTime} registers {DegreesLatitude}'
+ multiplicity: ManyToOne
+ - name: date
+ roles:
+ - concept: Date
+ verbalizes:
+ - '{Flight} is scheduled to depart on {Date}'
+ multiplicity: ManyToOne
+ - name: departs_at
+ roles:
+ - concept: DateTime
+ verbalizes:
+ - '{Flight} departs at {DateTime}'
+ multiplicity: ManyToOne
+ requires: [ Flight.departs_at < Flight.arrives_at ]
+ - name: diverted
+ verbalizes:
+ - '{Flight} was diverted'
+ - name: arrives_at
+ roles:
+ - concept: DateTime
+ verbalizes:
+ - '{Flight} arrives at {DateTime}'
+ multiplicity: ManyToOne
+ - name: route
+ roles:
+ - concept: Route
+ verbalizes:
+ - '{Flight} traverses {Route}'
+ multiplicity: ManyToOne
+ - name: aircraft
+ roles:
+ - concept: Aircraft
+ verbalizes:
+ - '{Flight} uses {Aircraft}'
+ multiplicity: ManyToOne
+ requires: [ Flight.operated_by(Aircraft.carrier) ]
+ - name: operated_by
+ roles:
+ - concept: Carrier
+ verbalizes:
+ - '{Flight} is operated by {Carrier}'
+ multiplicity: ManyToOne
+- concept: CarrierCode
+ description: "The two-letter IATA code for the airline carrier."
+ type: ValueType
+ extends: [ String ]
+- concept: CarrierName
+ type: ValueType
+ extends: [ String ]
+- concept: Carrier
+ type: EntityType
+ identify_by: [ code ]
+ relationships:
+ - name: code
+ roles:
+ - concept: CarrierCode
+ verbalizes:
+ - '{Carrier} uses {CarrierCode}'
+ multiplicity: OneToOne
+ - name: name
+ roles:
+ - concept: CarrierName
+ verbalizes:
+ - '{Carrier} has {CarrierName}'
+ multiplicity: ManyToOne
+- concept: RouteId
+ type: ValueType
+ description: "A unique identifier for a route between two airports. Constructed by concatenating the IATA codes of the departure and destination airports (e.g., 'ATL -> DCA')"
+ extends: [ String ]
+- concept: Route
+ type: EntityType
+ identify_by: [ id ]
+ relationships:
+ - name: average_departure_delay
+ roles:
+ - concept: Delay
+ verbalizes:
+ - '{Route} has average- departure {Delay}' # The hyphen after "average" has significance when verbalizing constraints
+ multiplicity: ManyToOne # Each Route has at most one average departure Delay
+ derived_by: [ 'Delay == AVG[Flight.departure_delay WHERE Flight.route(Route) GROUP BY Route]' ]
+ - name: average_arrival_delay
+ roles:
+ - concept: Delay
+ verbalizes:
+ - '{Route} has average- arrival {Delay}' # The hyphen after "average" has significance when verbalizing constraints
+ multiplicity: ManyToOne # Each Route has at most one average arrival Delay
+ derived_by: [ 'Delay == AVG[Flight.arrival_delay WHERE Flight.route(Route) GROUP BY Route]' ]
+ - name: distance
+ roles:
+ - concept: Distance
+ verbalizes:
+ - '{Route} spans {Distance}'
+ multiplicity: ManyToOne
+ - name: lies_in
+ roles:
+ - concept: DistanceGroup
+ verbalizes:
+ - '{Route} has {DistanceGroup}'
+ multiplicity: ManyToOne
+ - name: id
+ roles:
+ - concept: RouteId
+ verbalizes:
+ - '{Route} is identified by {RouteId}'
+ multiplicity: OneToOne
+ - name: route_name
+ roles:
+ - concept: String
+ verbalizes:
+ - '{Route} has name- {String}' # The hyphen after "name" has significance when verbalizing constraints
+ multiplicity: ManyToOne
+ - name: destination
+ roles:
+ - concept: Airport
+ verbalizes:
+ - '{Route} connects to destination- {Airport}' # The hyphen after "destination" has significance when verbalizing constraints
+ multiplicity: ManyToOne # Each Route connects to at most one destination Airport
+ requires: [ 'NOT Route.departure(Airport)' ]
+ - name: departure
+ roles:
+ - concept: Airport
+ verbalizes:
+ - '{Route} connects to departure- {Airport}' # The hyphen after "departure" has significance when verbalizing constraints
+ multiplicity: ManyToOne # Each Route connects to at most one departure Airport
+ requires: [ 'NOT Route.destination(Airport)' ]
+ontology_mappings:
+- name: flights_mapping
+ semantic_model:
+ name: Flights semantic model
+ datasets:
+ - name: RUNWAY
+ source: DATABASE.SCHEMA.RUNWAYS
+ fields:
+ - name: airport_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: airport_code
+ - name: length
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: length
+ - name: shape
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: shape
+ - name: designator
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: designator
+ - name: AIRCRAFT
+ source: DATABASE.SCHEMA.AIRCRAFT
+ description: "An airplane, helicopter, or other machine capable of flight"
+ fields:
+ - name: serial_nr
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: serial_nr
+ - name: name
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: name
+ - name: nr_seats
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: nr_seats
+ - name: tail_nr
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: tail_nr
+ - name: carrier_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: carrier_code
+ - name: manufacturer
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: manufacturer
+ - name: model
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: model
+ - name: year
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: year
+ - name: capacity
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: capacity
+ - name: AIRPORT
+ source: DATABASE.SCHEMA.AIRPORTS
+ description: "An airport that is identified by an IATA code."
+ fields:
+ - name: state_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: state_code
+ - name: market_nm
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: market_nm
+ - name: longitude
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: longitude
+ - name: opened
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: opened
+ - name: state_nm
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: state_nm
+ - name: city_nm
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: city_nm
+ - name: name
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: name
+ - name: code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: code
+ - name: latitude
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: latitude
+ - name: FLIGHT
+ source: DATABASE.SCHEMA.FLIGHTS
+ description: "A commercial passenger flight."
+ fields:
+ - name: dep_delay
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: dep_delay
+ - name: air_time
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: air_time
+ - name: nr
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: nr
+ - name: carrier_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: carrier_code
+ - name: duration
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: duration
+ - name: scheduled_departure
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: scheduled_departure
+ - name: arr_delay
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: arr_delay
+ - name: cancelled
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: cancelled
+ - name: cancel_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: cancel_code
+ - name: distance
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: distance
+ - name: id
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: id
+ - name: scheduled_arrival
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: scheduled_arrival
+ - name: wheels_on
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: wheels_on
+ - name: date
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: date
+ - name: wheels_off
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: wheels_off
+ - name: scheduled_duration
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: scheduled_duration
+ - name: tail_nr
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: tail_nr
+ - name: departure
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: departure
+ - name: route_id
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: route_id
+ - name: diverted
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: diverted
+ - name: arrival
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: arrival
+ - name: CARRIER
+ source: DATABASE.SCHEMA.CARRIERS
+ description: "An airline, such as Delta, United, or American."
+ fields:
+ - name: code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: code
+ - name: name
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: name
+ - name: ROUTE
+ source: DATABASE.SCHEMA.ROUTES
+ description: "Represents the existence of one or more flights between a pair of departure
+ arrival airports."
+ fields:
+ - name: orig_airport_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: orig_airport_code
+ - name: dest_airport_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: dest_airport_code
+ - name: distance
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: distance
+ - name: dist_grp
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: dist_grp
+ - name: id
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: id
+ - name: name
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: name
+ concept_mappings:
+ - concept: Runway
+ object_mappings:
+ - referent_mappings:
+ - relationship: designator
+ expression: RUNWAY.designator
+ - relationship: airport
+ referent_mappings:
+ - relationship: code
+ expression: RUNWAY.airport_code
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: designator
+ expression: RUNWAY.designator
+ - relationship: airport
+ referent_mappings:
+ - relationship: code
+ expression: RUNWAY.airport_code
+ children:
+ - object_mapping:
+ concept: RunwayLength
+ expression: RUNWAY.length
+ relationship: length
+ - object_mapping:
+ concept: RunwayGeometry
+ expression: RUNWAY.shape
+ relationship: geometry
+ - concept: Manufacturer
+ object_mappings:
+ - referent_mappings:
+ - relationship: name
+ expression: AIRCRAFT.manufacturer
+ - concept: Model
+ object_mappings:
+ - referent_mappings:
+ - relationship: name
+ expression: AIRCRAFT.model
+ - relationship: manufacturer
+ referent_mappings:
+ - relationship: name
+ expression: AIRCRAFT.manufacturer
+ - concept: Aircraft
+ object_mappings:
+ - referent_mappings:
+ - relationship: tailnum
+ expression: AIRCRAFT.tail_nr
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: tailnum
+ expression: AIRCRAFT.tail_nr
+ children:
+ - object_mapping:
+ concept: SerialNr
+ expression: AIRCRAFT.serial_nr
+ relationship: serial_number
+ - object_mapping:
+ concept: String
+ expression: AIRCRAFT.name
+ relationship: name
+ - object_mapping:
+ concept: Integer
+ expression: AIRCRAFT.nr_seats
+ relationship: number_of_seats
+ - object_mapping:
+ concept: Model
+ referent_mappings:
+ - relationship: name
+ expression: AIRCRAFT.model
+ - relationship: manufacturer
+ referent_mappings:
+ - relationship: name
+ expression: AIRCRAFT.manufacturer
+ relationship: model
+ - object_mapping:
+ concept: Year
+ expression: AIRCRAFT.year
+ relationship: year_manufactured
+ - object_mapping:
+ concept: Capacity
+ expression: AIRCRAFT.capacity
+ relationship: capacity
+ - object_mapping:
+ concept: Carrier
+ referent_mappings:
+ - relationship: code
+ expression: AIRCRAFT.carrier_code
+ relationship: carrier
+ - concept: State
+ object_mappings:
+ - referent_mappings:
+ - relationship: code
+ expression: AIRPORT.state_code
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: code
+ expression: AIRPORT.state_code
+ children:
+ - object_mapping:
+ concept: StateName
+ expression: AIRPORT.state_nm
+ relationship: name
+ - concept: City
+ object_mappings:
+ - referent_mappings:
+ - relationship: name
+ expression: AIRPORT.city_nm
+ - relationship: state
+ referent_mappings:
+ - relationship: code
+ expression: AIRPORT.state_code
+ - concept: Market
+ object_mappings:
+ - referent_mappings:
+ - relationship: name
+ expression: AIRPORT.market_nm
+ - concept: Airport
+ object_mappings:
+ - referent_mappings:
+ - relationship: code
+ expression: AIRPORT.code
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: code
+ expression: AIRPORT.code
+ children:
+ - object_mapping:
+ concept: City
+ referent_mappings:
+ - relationship: name
+ expression: AIRPORT.city_nm
+ - relationship: state
+ referent_mappings:
+ - relationship: code
+ expression: AIRPORT.state_code
+ relationship: city
+ - object_mapping:
+ concept: Market
+ referent_mappings:
+ - relationship: name
+ expression: AIRPORT.market_nm
+ relationship: serves
+ - object_mapping:
+ concept: DegreesLongitude
+ expression: AIRPORT.longitude
+ relationship: longitude
+ - object_mapping:
+ concept: AirportName
+ expression: AIRPORT.name
+ relationship: name
+ - object_mapping:
+ concept: DegreesLatitude
+ expression: AIRPORT.latitude
+ relationship: latitude
+ - concept: Flight
+ object_mappings:
+ - referent_mappings:
+ - relationship: id
+ expression: FLIGHT.id
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: id
+ expression: FLIGHT.id WHERE ( FLIGHT.diverted == TRUE )
+ relationship: diverted
+ - object_mapping:
+ referent_mappings:
+ - relationship: id
+ expression: FLIGHT.id WHERE ( FLIGHT.cancelled == TRUE )
+ relationship: canceled
+ - object_mapping:
+ referent_mappings:
+ - relationship: id
+ expression: FLIGHT.id
+ children:
+ - object_mapping:
+ concept: Delay
+ expression: FLIGHT.arr_delay
+ relationship: arrival_delay
+ - object_mapping:
+ concept: Delay
+ expression: FLIGHT.dep_delay
+ relationship: departure_delay
+ - object_mapping:
+ concept: FlightNr
+ expression: FLIGHT.nr
+ relationship: number
+ - object_mapping:
+ concept: DateTime
+ expression: FLIGHT.scheduled_departure
+ relationship: scheduled_departure
+ - object_mapping:
+ concept: CancelationReason
+ referent_mappings:
+ - relationship: code
+ expression: FLIGHT.cancel_code
+ relationship: canceled_due_to
+ - object_mapping:
+ concept: Distance
+ expression: FLIGHT.distance
+ relationship: distance
+ - object_mapping:
+ concept: DateTime
+ expression: FLIGHT.scheduled_arrival
+ relationship: scheduled_arrival
+ - object_mapping:
+ concept: Date
+ expression: FLIGHT.date
+ relationship: date
+ - object_mapping:
+ concept: DateTime
+ expression: FLIGHT.departure
+ relationship: departs_at
+ - object_mapping:
+ concept: DateTime
+ expression: FLIGHT.arrival
+ relationship: arrives_at
+ - object_mapping:
+ concept: Route
+ referent_mappings:
+ - relationship: id
+ expression: FLIGHT.route_id
+ relationship: route
+ - object_mapping:
+ concept: Aircraft
+ referent_mappings:
+ - relationship: tailnum
+ expression: FLIGHT.tail_nr
+ relationship: aircraft
+ - object_mapping:
+ concept: Carrier
+ referent_mappings:
+ - relationship: code
+ expression: FLIGHT.carrier_code
+ relationship: operated_by
+ - concept: Carrier
+ object_mappings:
+ - referent_mappings:
+ - relationship: code
+ expression: CARRIER.code
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: code
+ expression: CARRIER.code
+ children:
+ - object_mapping:
+ concept: CarrierName
+ expression: CARRIER.name
+ relationship: name
+ - concept: Route
+ object_mappings:
+ - referent_mappings:
+ - relationship: id
+ expression: ROUTE.id
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: id
+ expression: ROUTE.id
+ children:
+ - object_mapping:
+ concept: Distance
+ expression: ROUTE.distance
+ relationship: distance
+ - object_mapping:
+ concept: DistanceGroup
+ expression: ROUTE.dist_grp
+ relationship: lies_in
+ - object_mapping:
+ concept: String
+ expression: ROUTE.name
+ relationship: route_name
+ - object_mapping:
+ concept: Airport
+ referent_mappings:
+ - relationship: code
+ expression: ROUTE.dest_airport_code
+ relationship: destination
+ - object_mapping:
+ concept: Airport
+ referent_mappings:
+ - relationship: code
+ expression: ROUTE.orig_airport_code
+ relationship: departure
diff --git a/converters/ontology/tests/snapshots/test_flights_snapshot/test_flights_roundtrip_yaml_snapshot/flights_roundtrip.yaml b/converters/ontology/tests/snapshots/test_flights_snapshot/test_flights_roundtrip_yaml_snapshot/flights_roundtrip.yaml
new file mode 100644
index 00000000..805fadef
--- /dev/null
+++ b/converters/ontology/tests/snapshots/test_flights_snapshot/test_flights_roundtrip_yaml_snapshot/flights_roundtrip.yaml
@@ -0,0 +1,1180 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+version: 0.2.0.dev0
+name: Flights
+description: Ontology of flights into and out of airports.
+requires:
+- COUNT[Airport] > 0
+- COUNT[Carrier] > 0
+ontology:
+- concept: Route
+ type: EntityType
+ identify_by:
+ - id
+ relationships:
+ - name: average_departure_delay
+ roles:
+ - concept: Delay
+ verbalizes:
+ - '{Route} has average- departure {Delay}'
+ multiplicity: ManyToOne
+ derived_by:
+ - Delay == AVG[Flight.departure_delay WHERE Flight.route(Route) GROUP BY Route]
+ - name: average_arrival_delay
+ roles:
+ - concept: Delay
+ verbalizes:
+ - '{Route} has average- arrival {Delay}'
+ multiplicity: ManyToOne
+ derived_by:
+ - Delay == AVG[Flight.arrival_delay WHERE Flight.route(Route) GROUP BY Route]
+ - name: distance
+ roles:
+ - concept: Distance
+ verbalizes:
+ - '{Route} spans {Distance}'
+ multiplicity: ManyToOne
+ - name: lies_in
+ roles:
+ - concept: DistanceGroup
+ verbalizes:
+ - '{Route} has {DistanceGroup}'
+ multiplicity: ManyToOne
+ - name: id
+ roles:
+ - concept: RouteId
+ verbalizes:
+ - '{Route} is identified by {RouteId}'
+ multiplicity: OneToOne
+ - name: route_name
+ roles:
+ - concept: String
+ verbalizes:
+ - '{Route} has name- {String}'
+ multiplicity: ManyToOne
+ - name: destination
+ roles:
+ - concept: Airport
+ verbalizes:
+ - '{Route} connects to destination- {Airport}'
+ multiplicity: ManyToOne
+ requires:
+ - NOT Route.departure(Airport)
+ - name: departure
+ roles:
+ - concept: Airport
+ verbalizes:
+ - '{Route} connects to departure- {Airport}'
+ multiplicity: ManyToOne
+ requires:
+ - NOT Route.destination(Airport)
+- concept: RouteId
+ type: ValueType
+ description: A unique identifier for a route between two airports. Constructed by concatenating the IATA codes of the departure and destination airports (e.g., 'ATL -> DCA')
+ extends:
+ - String
+- concept: Carrier
+ type: EntityType
+ identify_by:
+ - code
+ relationships:
+ - name: code
+ roles:
+ - concept: CarrierCode
+ verbalizes:
+ - '{Carrier} uses {CarrierCode}'
+ multiplicity: OneToOne
+ - name: name
+ roles:
+ - concept: CarrierName
+ verbalizes:
+ - '{Carrier} has {CarrierName}'
+ multiplicity: ManyToOne
+- concept: CarrierName
+ type: ValueType
+ extends:
+ - String
+- concept: CarrierCode
+ type: ValueType
+ description: The two-letter IATA code for the airline carrier.
+ extends:
+ - String
+- concept: Flight
+ type: EntityType
+ identify_by:
+ - id
+ relationships:
+ - name: departure_delay
+ roles:
+ - concept: Delay
+ verbalizes:
+ - '{Flight} has departure- {Delay}'
+ multiplicity: ManyToOne
+ - name: number
+ roles:
+ - concept: FlightNr
+ verbalizes:
+ - '{Flight} has {FlightNr}'
+ multiplicity: ManyToOne
+ - name: scheduled_departure
+ roles:
+ - concept: DateTime
+ verbalizes:
+ - '{Flight} is scheduled to depart at {DateTime}'
+ multiplicity: ManyToOne
+ requires:
+ - Flight.scheduled_departure < Flight.scheduled_arrival
+ - name: arrival_delay
+ roles:
+ - concept: Delay
+ verbalizes:
+ - '{Flight} has arrival- {Delay}'
+ multiplicity: ManyToOne
+ - name: canceled
+ verbalizes:
+ - '{Flight} was canceled'
+ - name: canceled_due_to
+ roles:
+ - concept: CancelationReason
+ verbalizes:
+ - '{Flight} was canceled due to {CancelationReason}'
+ multiplicity: ManyToOne
+ - name: distance
+ roles:
+ - concept: Distance
+ verbalizes:
+ - '{Flight} spans actual- {Distance}'
+ multiplicity: ManyToOne
+ - name: id
+ roles:
+ - concept: FlightId
+ verbalizes:
+ - '{Flight} is identified by {FlightId}'
+ multiplicity: OneToOne
+ - name: scheduled_arrival
+ roles:
+ - concept: DateTime
+ verbalizes:
+ - '{Flight} is scheduled to arrive at {DateTime}'
+ multiplicity: ManyToOne
+ - name: registers_longitude_series
+ roles:
+ - concept: DateTime
+ - concept: DegreesLongitude
+ verbalizes:
+ - '{Flight} at {DateTime} registers {DegreesLongitude}'
+ multiplicity: ManyToOne
+ - name: registers_latitude_series
+ roles:
+ - concept: DateTime
+ - concept: DegreesLatitude
+ verbalizes:
+ - '{Flight} at {DateTime} registers {DegreesLatitude}'
+ multiplicity: ManyToOne
+ - name: date
+ roles:
+ - concept: Date
+ verbalizes:
+ - '{Flight} is scheduled to depart on {Date}'
+ multiplicity: ManyToOne
+ - name: departs_at
+ roles:
+ - concept: DateTime
+ verbalizes:
+ - '{Flight} departs at {DateTime}'
+ multiplicity: ManyToOne
+ requires:
+ - Flight.departs_at < Flight.arrives_at
+ - name: diverted
+ verbalizes:
+ - '{Flight} was diverted'
+ - name: arrives_at
+ roles:
+ - concept: DateTime
+ verbalizes:
+ - '{Flight} arrives at {DateTime}'
+ multiplicity: ManyToOne
+ - name: route
+ roles:
+ - concept: Route
+ verbalizes:
+ - '{Flight} traverses {Route}'
+ multiplicity: ManyToOne
+ - name: aircraft
+ roles:
+ - concept: Aircraft
+ verbalizes:
+ - '{Flight} uses {Aircraft}'
+ multiplicity: ManyToOne
+ requires:
+ - Flight.operated_by(Aircraft.carrier)
+ - name: operated_by
+ roles:
+ - concept: Carrier
+ verbalizes:
+ - '{Flight} is operated by {Carrier}'
+ multiplicity: ManyToOne
+- concept: FlightId
+ type: ValueType
+ description: A unique identifier for an instance of a flight
+ extends:
+ - String
+- concept: FlightNr
+ type: ValueType
+ description: The IATA flight number, which is typically a combination of the airline's IATA code and a numeric code (e.g., 'AA1234').
+ extends:
+ - String
+- concept: Market
+ type: EntityType
+ identify_by:
+ - name
+ relationships:
+ - name: name
+ roles:
+ - concept: MarketName
+ verbalizes:
+ - '{Market} is identified by {MarketName}'
+ multiplicity: OneToOne
+- concept: MarketName
+ type: ValueType
+ extends:
+ - String
+- concept: Airport
+ type: EntityType
+ identify_by:
+ - code
+ requires:
+ - Airport.latitude
+ - Airport.longitude
+ relationships:
+ - name: city
+ roles:
+ - concept: City
+ verbalizes:
+ - '{Airport} is located in {City}'
+ multiplicity: ManyToOne
+ - name: serves
+ roles:
+ - concept: Market
+ verbalizes:
+ - '{Airport} serves {Market}'
+ multiplicity: ManyToOne
+ - name: average_departure_delay
+ roles:
+ - concept: Delay
+ verbalizes:
+ - '{Airport} has average- departure {Delay}'
+ multiplicity: ManyToOne
+ derived_by:
+ - Delay == AVG[Flight.departure_delay WHERE Airport == Flight.route.departure GROUP BY Airport]
+ - name: longitude
+ roles:
+ - concept: DegreesLongitude
+ verbalizes:
+ - '{Airport} centers at {DegreesLongitude}'
+ multiplicity: ManyToOne
+ - name: average_arrival_delay
+ roles:
+ - concept: Delay
+ verbalizes:
+ - '{Airport} has average- arrival {Delay}'
+ multiplicity: ManyToOne
+ derived_by:
+ - Delay == AVG[Flight.arrival_delay WHERE Airport == Flight.route.destination GROUP BY Airport]
+ - name: name
+ roles:
+ - concept: AirportName
+ verbalizes:
+ - '{Airport} has {AirportName}'
+ multiplicity: ManyToOne
+ - name: code
+ roles:
+ - concept: AirportCode
+ verbalizes:
+ - '{Airport} has {AirportCode}'
+ multiplicity: OneToOne
+ - name: latitude
+ roles:
+ - concept: DegreesLatitude
+ verbalizes:
+ - '{Airport} centers at {DegreesLatitude}'
+ multiplicity: ManyToOne
+- concept: AirportId
+ type: ValueType
+ description: Five digit number used as an alternate identifier for airports.
+ extends:
+ - String
+- concept: AirportCode
+ type: ValueType
+ description: The three-letter IATA code for the airport.
+ extends:
+ - String
+- concept: AirportName
+ type: ValueType
+ extends:
+ - String
+- concept: Aircraft
+ type: EntityType
+ identify_by:
+ - tailnum
+ relationships:
+ - name: serial_number
+ roles:
+ - concept: SerialNr
+ verbalizes:
+ - '{Aircraft} has {SerialNr}'
+ multiplicity: ManyToOne
+ - name: name
+ roles:
+ - concept: String
+ verbalizes:
+ - '{Aircraft} has name {String}'
+ multiplicity: ManyToOne
+ - name: number_of_seats
+ roles:
+ - concept: Integer
+ verbalizes:
+ - '{Aircraft} has {Integer} seats'
+ multiplicity: ManyToOne
+ - name: tailnum
+ roles:
+ - concept: TailNr
+ verbalizes:
+ - '{Aircraft} is identified by {TailNr}'
+ multiplicity: OneToOne
+ - name: model
+ roles:
+ - concept: Model
+ verbalizes:
+ - '{Aircraft} has {Model}'
+ multiplicity: ManyToOne
+ - name: year_manufactured
+ roles:
+ - concept: Year
+ verbalizes:
+ - '{Aircraft} was manufactured in {Year}'
+ multiplicity: ManyToOne
+ - name: capacity
+ roles:
+ - concept: Capacity
+ verbalizes:
+ - '{Aircraft} has {Capacity}'
+ multiplicity: ManyToOne
+ - name: carrier
+ roles:
+ - concept: Carrier
+ verbalizes:
+ - '{Aircraft} is operated by {Carrier}'
+ multiplicity: ManyToOne
+- concept: Model
+ type: EntityType
+ identify_by:
+ - name
+ - manufacturer
+ relationships:
+ - name: name
+ roles:
+ - concept: ModelName
+ verbalizes:
+ - '{Model} has {ModelName}'
+ multiplicity: ManyToOne
+ - name: manufacturer
+ roles:
+ - concept: Manufacturer
+ verbalizes:
+ - '{Model} is manufactured by {Manufacturer}'
+ multiplicity: ManyToOne
+- concept: ModelName
+ type: ValueType
+ extends:
+ - String
+- concept: Manufacturer
+ type: EntityType
+ identify_by:
+ - name
+ relationships:
+ - name: name
+ roles:
+ - concept: ManufacturerName
+ verbalizes:
+ - '{Manufacturer} is identified by {ManufacturerName}'
+ multiplicity: OneToOne
+- concept: ManufacturerName
+ type: ValueType
+ extends:
+ - String
+- concept: Runway
+ type: EntityType
+ identify_by:
+ - designator
+ - airport
+ relationships:
+ - name: airport
+ roles:
+ - concept: Airport
+ verbalizes:
+ - '{Runway} belongs to {Airport}'
+ multiplicity: ManyToOne
+ - name: designator
+ roles:
+ - concept: RunwayDesignator
+ verbalizes:
+ - '{Runway} uses {RunwayDesignator}'
+ multiplicity: ManyToOne
+ - name: length
+ roles:
+ - concept: RunwayLength
+ verbalizes:
+ - '{Runway} has {RunwayLength}'
+ multiplicity: ManyToOne
+ - name: geometry
+ roles:
+ - concept: RunwayGeometry
+ verbalizes:
+ - '{Runway} has {RunwayGeometry}'
+ multiplicity: ManyToOne
+- concept: City
+ type: EntityType
+ identify_by:
+ - name
+ - state
+ relationships:
+ - name: name
+ roles:
+ - concept: CityName
+ verbalizes:
+ - '{City} has {CityName}'
+ multiplicity: ManyToOne
+ - name: state
+ roles:
+ - concept: State
+ verbalizes:
+ - '{City} is located in {State}'
+ multiplicity: ManyToOne
+- concept: State
+ type: EntityType
+ identify_by:
+ - code
+ relationships:
+ - name: code
+ roles:
+ - concept: StateCode
+ verbalizes:
+ - '{State} is identified by {StateCode}'
+ multiplicity: OneToOne
+ - name: name
+ roles:
+ - concept: StateName
+ verbalizes:
+ - '{State} has {StateName}'
+ multiplicity: ManyToOne
+- concept: CancelationReason
+ type: EntityType
+ description: A curated set of reasons that explain why a flight is canceled
+ identify_by:
+ - code
+ relationships:
+ - name: code
+ roles:
+ - concept: CancelationCode
+ verbalizes:
+ - '{CancelationReason} is identified by {CancelationCode}'
+ multiplicity: OneToOne
+ - name: description
+ roles:
+ - concept: String
+ verbalizes:
+ - '{CancelationReason} has description- {String}'
+ multiplicity: ManyToOne
+- concept: Year
+ type: ValueType
+ extends:
+ - String
+- concept: TailNr
+ type: ValueType
+ extends:
+ - String
+- concept: StateName
+ type: ValueType
+ extends:
+ - String
+- concept: StateCode
+ type: ValueType
+ extends:
+ - String
+- concept: SerialNr
+ type: ValueType
+ extends:
+ - String
+- concept: RunwayDesignator
+ type: ValueType
+ description: Used to distinguish runways within a given airport.
+ extends:
+ - String
+- concept: DistanceGroup
+ type: ValueType
+ description: A number used to group distances of different lengths, where 1 groups the shortest and 10 the longest.
+ extends:
+ - Integer
+ requires:
+ - 1 <= DistanceGroup
+ - DistanceGroup <= 10
+- concept: CityName
+ type: ValueType
+ extends:
+ - String
+- concept: Polygon
+ type: ValueType
+ description: A polygon represented as a list of vertices, where each vertex is a pair of latitude and longitude coordinates.
+ extends:
+ - String
+- concept: RunwayGeometry
+ type: ValueType
+ description: A polygon that models the shape of a runway.
+ extends:
+ - Polygon
+- concept: DegreesLongitude
+ type: ValueType
+ extends:
+ - Decimal
+ requires:
+ - DegreesLongitude <= 180
+ - DegreesLongitude >= -180
+- concept: DegreesLatitude
+ type: ValueType
+ extends:
+ - Decimal
+ requires:
+ - DegreesLatitude <= 90
+ - DegreesLatitude >= -90
+- concept: CancelationCode
+ type: ValueType
+ description: The single character code that identifies the reason a flight is canceled
+ extends:
+ - String
+ requires:
+ - CancelationCode == 'A' OR CancelationCode == 'B' OR CancelationCode == 'C' OR CancelationCode == 'D'
+- concept: NrMinutes
+ type: ValueType
+ description: Unit of measure for time in minutes
+ extends:
+ - Decimal
+- concept: Delay
+ type: ValueType
+ extends:
+ - NrMinutes
+- concept: NrMiles
+ type: ValueType
+ description: Unit of measure for distance in miles
+ extends:
+ - Decimal
+- concept: Distance
+ type: ValueType
+ extends:
+ - NrMiles
+- concept: NrPounds
+ type: ValueType
+ description: Unit of measure for weight in pounds
+ extends:
+ - Integer
+- concept: Capacity
+ type: ValueType
+ description: The capacity of an aircraft, measured in pounds.
+ extends:
+ - NrPounds
+- concept: NrFeet
+ type: ValueType
+ description: Unit of measure for distance in feet
+ extends:
+ - Decimal
+- concept: RunwayLength
+ type: ValueType
+ description: The unit for measuring the lengths of runways in American airports.
+ extends:
+ - NrFeet
+ontology_mappings:
+- name: flights_mapping
+ semantic_model:
+ name: Flights semantic model
+ datasets:
+ - name: RUNWAY
+ source: DATABASE.SCHEMA.RUNWAYS
+ fields:
+ - name: airport_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: airport_code
+ - name: length
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: length
+ - name: shape
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: shape
+ - name: designator
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: designator
+ - name: AIRCRAFT
+ source: DATABASE.SCHEMA.AIRCRAFT
+ description: An airplane, helicopter, or other machine capable of flight
+ fields:
+ - name: serial_nr
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: serial_nr
+ - name: name
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: name
+ - name: nr_seats
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: nr_seats
+ - name: tail_nr
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: tail_nr
+ - name: carrier_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: carrier_code
+ - name: manufacturer
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: manufacturer
+ - name: model
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: model
+ - name: year
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: year
+ - name: capacity
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: capacity
+ - name: AIRPORT
+ source: DATABASE.SCHEMA.AIRPORTS
+ description: An airport that is identified by an IATA code.
+ fields:
+ - name: state_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: state_code
+ - name: market_nm
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: market_nm
+ - name: longitude
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: longitude
+ - name: opened
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: opened
+ - name: state_nm
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: state_nm
+ - name: city_nm
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: city_nm
+ - name: name
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: name
+ - name: code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: code
+ - name: latitude
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: latitude
+ - name: FLIGHT
+ source: DATABASE.SCHEMA.FLIGHTS
+ description: A commercial passenger flight.
+ fields:
+ - name: dep_delay
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: dep_delay
+ - name: air_time
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: air_time
+ - name: nr
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: nr
+ - name: carrier_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: carrier_code
+ - name: duration
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: duration
+ - name: scheduled_departure
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: scheduled_departure
+ - name: arr_delay
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: arr_delay
+ - name: cancelled
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: cancelled
+ - name: cancel_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: cancel_code
+ - name: distance
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: distance
+ - name: id
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: id
+ - name: scheduled_arrival
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: scheduled_arrival
+ - name: wheels_on
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: wheels_on
+ - name: date
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: date
+ - name: wheels_off
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: wheels_off
+ - name: scheduled_duration
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: scheduled_duration
+ - name: tail_nr
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: tail_nr
+ - name: departure
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: departure
+ - name: route_id
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: route_id
+ - name: diverted
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: diverted
+ - name: arrival
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: arrival
+ - name: CARRIER
+ source: DATABASE.SCHEMA.CARRIERS
+ description: An airline, such as Delta, United, or American.
+ fields:
+ - name: code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: code
+ - name: name
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: name
+ - name: ROUTE
+ source: DATABASE.SCHEMA.ROUTES
+ description: Represents the existence of one or more flights between a pair of departure arrival airports.
+ fields:
+ - name: orig_airport_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: orig_airport_code
+ - name: dest_airport_code
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: dest_airport_code
+ - name: distance
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: distance
+ - name: dist_grp
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: dist_grp
+ - name: id
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: id
+ - name: name
+ expression:
+ dialects:
+ - dialect: ANSI_SQL
+ expression: name
+ concept_mappings:
+ - concept: Runway
+ object_mappings:
+ - referent_mappings:
+ - relationship: designator
+ expression: RUNWAY.designator
+ - relationship: airport
+ referent_mappings:
+ - relationship: code
+ expression: RUNWAY.airport_code
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: designator
+ expression: RUNWAY.designator
+ - relationship: airport
+ referent_mappings:
+ - relationship: code
+ expression: RUNWAY.airport_code
+ children:
+ - object_mapping:
+ concept: RunwayLength
+ expression: RUNWAY.length
+ relationship: length
+ - object_mapping:
+ concept: RunwayGeometry
+ expression: RUNWAY.shape
+ relationship: geometry
+ - concept: Manufacturer
+ object_mappings:
+ - referent_mappings:
+ - relationship: name
+ expression: AIRCRAFT.manufacturer
+ - concept: Model
+ object_mappings:
+ - referent_mappings:
+ - relationship: name
+ expression: AIRCRAFT.model
+ - relationship: manufacturer
+ referent_mappings:
+ - relationship: name
+ expression: AIRCRAFT.manufacturer
+ - concept: Aircraft
+ object_mappings:
+ - referent_mappings:
+ - relationship: tailnum
+ expression: AIRCRAFT.tail_nr
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: tailnum
+ expression: AIRCRAFT.tail_nr
+ children:
+ - object_mapping:
+ concept: SerialNr
+ expression: AIRCRAFT.serial_nr
+ relationship: serial_number
+ - object_mapping:
+ concept: String
+ expression: AIRCRAFT.name
+ relationship: name
+ - object_mapping:
+ concept: Integer
+ expression: AIRCRAFT.nr_seats
+ relationship: number_of_seats
+ - object_mapping:
+ concept: Model
+ referent_mappings:
+ - relationship: name
+ expression: AIRCRAFT.model
+ - relationship: manufacturer
+ referent_mappings:
+ - relationship: name
+ expression: AIRCRAFT.manufacturer
+ relationship: model
+ - object_mapping:
+ concept: Year
+ expression: AIRCRAFT.year
+ relationship: year_manufactured
+ - object_mapping:
+ concept: Capacity
+ expression: AIRCRAFT.capacity
+ relationship: capacity
+ - object_mapping:
+ concept: Carrier
+ referent_mappings:
+ - relationship: code
+ expression: AIRCRAFT.carrier_code
+ relationship: carrier
+ - concept: State
+ object_mappings:
+ - referent_mappings:
+ - relationship: code
+ expression: AIRPORT.state_code
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: code
+ expression: AIRPORT.state_code
+ children:
+ - object_mapping:
+ concept: StateName
+ expression: AIRPORT.state_nm
+ relationship: name
+ - concept: City
+ object_mappings:
+ - referent_mappings:
+ - relationship: name
+ expression: AIRPORT.city_nm
+ - relationship: state
+ referent_mappings:
+ - relationship: code
+ expression: AIRPORT.state_code
+ - concept: Market
+ object_mappings:
+ - referent_mappings:
+ - relationship: name
+ expression: AIRPORT.market_nm
+ - concept: Airport
+ object_mappings:
+ - referent_mappings:
+ - relationship: code
+ expression: AIRPORT.code
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: code
+ expression: AIRPORT.code
+ children:
+ - object_mapping:
+ concept: City
+ referent_mappings:
+ - relationship: name
+ expression: AIRPORT.city_nm
+ - relationship: state
+ referent_mappings:
+ - relationship: code
+ expression: AIRPORT.state_code
+ relationship: city
+ - object_mapping:
+ concept: Market
+ referent_mappings:
+ - relationship: name
+ expression: AIRPORT.market_nm
+ relationship: serves
+ - object_mapping:
+ concept: DegreesLongitude
+ expression: AIRPORT.longitude
+ relationship: longitude
+ - object_mapping:
+ concept: AirportName
+ expression: AIRPORT.name
+ relationship: name
+ - object_mapping:
+ concept: DegreesLatitude
+ expression: AIRPORT.latitude
+ relationship: latitude
+ - concept: Flight
+ object_mappings:
+ - referent_mappings:
+ - relationship: id
+ expression: FLIGHT.id
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: id
+ expression: FLIGHT.id WHERE ( FLIGHT.diverted == TRUE )
+ relationship: diverted
+ - object_mapping:
+ referent_mappings:
+ - relationship: id
+ expression: FLIGHT.id WHERE ( FLIGHT.cancelled == TRUE )
+ relationship: canceled
+ - object_mapping:
+ referent_mappings:
+ - relationship: id
+ expression: FLIGHT.id
+ children:
+ - object_mapping:
+ concept: Delay
+ expression: FLIGHT.arr_delay
+ relationship: arrival_delay
+ - object_mapping:
+ concept: Delay
+ expression: FLIGHT.dep_delay
+ relationship: departure_delay
+ - object_mapping:
+ concept: FlightNr
+ expression: FLIGHT.nr
+ relationship: number
+ - object_mapping:
+ concept: DateTime
+ expression: FLIGHT.scheduled_departure
+ relationship: scheduled_departure
+ - object_mapping:
+ concept: CancelationReason
+ referent_mappings:
+ - relationship: code
+ expression: FLIGHT.cancel_code
+ relationship: canceled_due_to
+ - object_mapping:
+ concept: Distance
+ expression: FLIGHT.distance
+ relationship: distance
+ - object_mapping:
+ concept: DateTime
+ expression: FLIGHT.scheduled_arrival
+ relationship: scheduled_arrival
+ - object_mapping:
+ concept: Date
+ expression: FLIGHT.date
+ relationship: date
+ - object_mapping:
+ concept: DateTime
+ expression: FLIGHT.departure
+ relationship: departs_at
+ - object_mapping:
+ concept: DateTime
+ expression: FLIGHT.arrival
+ relationship: arrives_at
+ - object_mapping:
+ concept: Route
+ referent_mappings:
+ - relationship: id
+ expression: FLIGHT.route_id
+ relationship: route
+ - object_mapping:
+ concept: Aircraft
+ referent_mappings:
+ - relationship: tailnum
+ expression: FLIGHT.tail_nr
+ relationship: aircraft
+ - object_mapping:
+ concept: Carrier
+ referent_mappings:
+ - relationship: code
+ expression: FLIGHT.carrier_code
+ relationship: operated_by
+ - concept: Carrier
+ object_mappings:
+ - referent_mappings:
+ - relationship: code
+ expression: CARRIER.code
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: code
+ expression: CARRIER.code
+ children:
+ - object_mapping:
+ concept: CarrierName
+ expression: CARRIER.name
+ relationship: name
+ - concept: Route
+ object_mappings:
+ - referent_mappings:
+ - relationship: id
+ expression: ROUTE.id
+ link_mappings:
+ - object_mapping:
+ referent_mappings:
+ - relationship: id
+ expression: ROUTE.id
+ children:
+ - object_mapping:
+ concept: Distance
+ expression: ROUTE.distance
+ relationship: distance
+ - object_mapping:
+ concept: DistanceGroup
+ expression: ROUTE.dist_grp
+ relationship: lies_in
+ - object_mapping:
+ concept: String
+ expression: ROUTE.name
+ relationship: route_name
+ - object_mapping:
+ concept: Airport
+ referent_mappings:
+ - relationship: code
+ expression: ROUTE.dest_airport_code
+ relationship: destination
+ - object_mapping:
+ concept: Airport
+ referent_mappings:
+ - relationship: code
+ expression: ROUTE.orig_airport_code
+ relationship: departure
diff --git a/converters/ontology/tests/snapshots/test_flights_snapshot/test_flights_structure_snapshot/flights_structure.txt b/converters/ontology/tests/snapshots/test_flights_snapshot/test_flights_structure_snapshot/flights_structure.txt
new file mode 100644
index 00000000..0c66acf4
--- /dev/null
+++ b/converters/ontology/tests/snapshots/test_flights_snapshot/test_flights_structure_snapshot/flights_structure.txt
@@ -0,0 +1,183 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+name: Flights
+version: 0.2.0.dev0
+description: Ontology of flights into and out of airports.
+
+ontology requires:
+ - COUNT[Airport] > 0
+ - COUNT[Carrier] > 0
+
+concepts:
+ Aircraft (ENTITY_TYPE)
+ identify_by: Aircraft.tailnum
+ Airport (ENTITY_TYPE)
+ identify_by: Airport.code
+ requires: Airport.latitude
+ requires: Airport.longitude
+ AirportCode (VALUE_TYPE)
+ extends: String
+ AirportId (VALUE_TYPE)
+ extends: String
+ AirportName (VALUE_TYPE)
+ extends: String
+ CancelationCode (VALUE_TYPE)
+ extends: String
+ requires: CancelationCode == 'A' OR CancelationCode == 'B' OR CancelationCode == 'C' OR CancelationCode == 'D'
+ CancelationReason (ENTITY_TYPE)
+ identify_by: CancelationReason.code
+ Capacity (VALUE_TYPE)
+ extends: NrPounds
+ Carrier (ENTITY_TYPE)
+ identify_by: Carrier.code
+ CarrierCode (VALUE_TYPE)
+ extends: String
+ CarrierName (VALUE_TYPE)
+ extends: String
+ City (ENTITY_TYPE)
+ identify_by: City.name, City.state
+ CityName (VALUE_TYPE)
+ extends: String
+ DegreesLatitude (VALUE_TYPE)
+ extends: Decimal
+ requires: DegreesLatitude <= 90
+ requires: DegreesLatitude >= -90
+ DegreesLongitude (VALUE_TYPE)
+ extends: Decimal
+ requires: DegreesLongitude <= 180
+ requires: DegreesLongitude >= -180
+ Delay (VALUE_TYPE)
+ extends: NrMinutes
+ Distance (VALUE_TYPE)
+ extends: NrMiles
+ DistanceGroup (VALUE_TYPE)
+ extends: Integer
+ requires: 1 <= DistanceGroup
+ requires: DistanceGroup <= 10
+ Flight (ENTITY_TYPE)
+ identify_by: Flight.id
+ FlightId (VALUE_TYPE)
+ extends: String
+ FlightNr (VALUE_TYPE)
+ extends: String
+ Manufacturer (ENTITY_TYPE)
+ identify_by: Manufacturer.name
+ ManufacturerName (VALUE_TYPE)
+ extends: String
+ Market (ENTITY_TYPE)
+ identify_by: Market.name
+ MarketName (VALUE_TYPE)
+ extends: String
+ Model (ENTITY_TYPE)
+ identify_by: Model.manufacturer, Model.name
+ ModelName (VALUE_TYPE)
+ extends: String
+ NrFeet (VALUE_TYPE)
+ extends: Decimal
+ NrMiles (VALUE_TYPE)
+ extends: Decimal
+ NrMinutes (VALUE_TYPE)
+ extends: Decimal
+ NrPounds (VALUE_TYPE)
+ extends: Integer
+ Polygon (VALUE_TYPE)
+ extends: String
+ Route (ENTITY_TYPE)
+ identify_by: Route.id
+ RouteId (VALUE_TYPE)
+ extends: String
+ Runway (ENTITY_TYPE)
+ identify_by: Runway.airport, Runway.designator
+ RunwayDesignator (VALUE_TYPE)
+ extends: String
+ RunwayGeometry (VALUE_TYPE)
+ extends: Polygon
+ RunwayLength (VALUE_TYPE)
+ extends: NrFeet
+ SerialNr (VALUE_TYPE)
+ extends: String
+ State (ENTITY_TYPE)
+ identify_by: State.code
+ StateCode (VALUE_TYPE)
+ extends: String
+ StateName (VALUE_TYPE)
+ extends: String
+ TailNr (VALUE_TYPE)
+ extends: String
+ Year (VALUE_TYPE)
+ extends: String
+
+relationships:
+ Aircraft.capacity [MANY_TO_ONE]: Aircraft -> Capacity
+ Aircraft.carrier [MANY_TO_ONE]: Aircraft -> Carrier
+ Aircraft.model [MANY_TO_ONE]: Aircraft -> Model
+ Aircraft.name [MANY_TO_ONE]: Aircraft -> String
+ Aircraft.number_of_seats [MANY_TO_ONE]: Aircraft -> Integer
+ Aircraft.serial_number [MANY_TO_ONE]: Aircraft -> SerialNr
+ Aircraft.tailnum [ONE_TO_ONE]: Aircraft -> TailNr
+ Aircraft.year_manufactured [MANY_TO_ONE]: Aircraft -> Year
+ Airport.average_arrival_delay [MANY_TO_ONE]: Airport -> Delay
+ Airport.average_departure_delay [MANY_TO_ONE]: Airport -> Delay
+ Airport.city [MANY_TO_ONE]: Airport -> City
+ Airport.code [ONE_TO_ONE]: Airport -> AirportCode
+ Airport.latitude [MANY_TO_ONE]: Airport -> DegreesLatitude
+ Airport.longitude [MANY_TO_ONE]: Airport -> DegreesLongitude
+ Airport.name [MANY_TO_ONE]: Airport -> AirportName
+ Airport.serves [MANY_TO_ONE]: Airport -> Market
+ CancelationReason.code [ONE_TO_ONE]: CancelationReason -> CancelationCode
+ CancelationReason.description [MANY_TO_ONE]: CancelationReason -> String
+ Carrier.code [ONE_TO_ONE]: Carrier -> CarrierCode
+ Carrier.name [MANY_TO_ONE]: Carrier -> CarrierName
+ City.name [MANY_TO_ONE]: City -> CityName
+ City.state [MANY_TO_ONE]: City -> State
+ Flight.aircraft [MANY_TO_ONE]: Flight -> Aircraft
+ Flight.arrival_delay [MANY_TO_ONE]: Flight -> Delay
+ Flight.arrives_at [MANY_TO_ONE]: Flight -> DateTime
+ Flight.canceled [None]: Flight
+ Flight.canceled_due_to [MANY_TO_ONE]: Flight -> CancelationReason
+ Flight.date [MANY_TO_ONE]: Flight -> Date
+ Flight.departs_at [MANY_TO_ONE]: Flight -> DateTime
+ Flight.departure_delay [MANY_TO_ONE]: Flight -> Delay
+ Flight.distance [MANY_TO_ONE]: Flight -> Distance
+ Flight.diverted [None]: Flight
+ Flight.id [ONE_TO_ONE]: Flight -> FlightId
+ Flight.number [MANY_TO_ONE]: Flight -> FlightNr
+ Flight.operated_by [MANY_TO_ONE]: Flight -> Carrier
+ Flight.registers_latitude_series [MANY_TO_ONE]: Flight -> DateTime -> DegreesLatitude
+ Flight.registers_longitude_series [MANY_TO_ONE]: Flight -> DateTime -> DegreesLongitude
+ Flight.route [MANY_TO_ONE]: Flight -> Route
+ Flight.scheduled_arrival [MANY_TO_ONE]: Flight -> DateTime
+ Flight.scheduled_departure [MANY_TO_ONE]: Flight -> DateTime
+ Manufacturer.name [ONE_TO_ONE]: Manufacturer -> ManufacturerName
+ Market.name [ONE_TO_ONE]: Market -> MarketName
+ Model.manufacturer [MANY_TO_ONE]: Model -> Manufacturer
+ Model.name [MANY_TO_ONE]: Model -> ModelName
+ Route.average_arrival_delay [MANY_TO_ONE]: Route -> Delay
+ Route.average_departure_delay [MANY_TO_ONE]: Route -> Delay
+ Route.departure [MANY_TO_ONE]: Route -> Airport
+ Route.destination [MANY_TO_ONE]: Route -> Airport
+ Route.distance [MANY_TO_ONE]: Route -> Distance
+ Route.id [ONE_TO_ONE]: Route -> RouteId
+ Route.lies_in [MANY_TO_ONE]: Route -> DistanceGroup
+ Route.route_name [MANY_TO_ONE]: Route -> String
+ Runway.airport [MANY_TO_ONE]: Runway -> Airport
+ Runway.designator [MANY_TO_ONE]: Runway -> RunwayDesignator
+ Runway.geometry [MANY_TO_ONE]: Runway -> RunwayGeometry
+ Runway.length [MANY_TO_ONE]: Runway -> RunwayLength
+ State.code [ONE_TO_ONE]: State -> StateCode
+ State.name [MANY_TO_ONE]: State -> StateName
diff --git a/converters/ontology/tests/test_concept_lookup.py b/converters/ontology/tests/test_concept_lookup.py
new file mode 100644
index 00000000..11e46d7d
--- /dev/null
+++ b/converters/ontology/tests/test_concept_lookup.py
@@ -0,0 +1,94 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Tests for concept lookup on OntologyComponent.
+
+Two operations, deliberately separate: `lookup_concept` answers whether a name
+is taken and adds nothing, which is what callers testing for an existing concept
+depend on; `ensure_builtin_concept` is the one that creates a builtin on demand,
+since builtins are declared nowhere.
+"""
+
+from __future__ import annotations
+
+from ossie_ontology.model import (
+ BUILTIN_CONCEPTS,
+ Concept,
+ ConceptType,
+ OntologyComponent,
+)
+
+
+def _concept_names(ontology: OntologyComponent) -> list[str]:
+ return [c.name for c in ontology.concepts()]
+
+
+def test_lookup_concept_finds_a_declared_concept():
+ ontology = OntologyComponent()
+ alpha = Concept(name="Alpha", type=ConceptType.ENTITY_TYPE)
+ ontology.add_concept(alpha)
+
+ assert ontology.lookup_concept("Alpha") is alpha
+
+
+def test_lookup_concept_does_not_create_a_builtin():
+ """The check `lookup_concept(name) is None` has to stay a question.
+
+ A caller asking whether a name is free would otherwise take that name — and
+ a concept named like a builtin would come back as the builtin it just made.
+ """
+ ontology = OntologyComponent()
+
+ assert "Date" in BUILTIN_CONCEPTS
+ assert ontology.lookup_concept("Date") is None
+ assert _concept_names(ontology) == []
+
+
+def test_lookup_concept_of_nothing_is_none():
+ ontology = OntologyComponent()
+
+ assert ontology.lookup_concept(None) is None
+ assert ontology.lookup_concept("") is None
+
+
+def test_ensure_builtin_concept_creates_it_once():
+ ontology = OntologyComponent()
+
+ first = ontology.ensure_builtin_concept("Date")
+ assert first is not None
+ assert first.is_builtin
+ # A builtin is not emitted as a concept component of its own.
+ assert not first.is_component
+
+ assert ontology.ensure_builtin_concept("Date") is first
+ assert _concept_names(ontology) == ["Date"]
+
+
+def test_ensure_builtin_concept_returns_a_declared_concept_unchanged():
+ ontology = OntologyComponent()
+ alpha = Concept(name="Alpha", type=ConceptType.ENTITY_TYPE)
+ ontology.add_concept(alpha)
+
+ assert ontology.ensure_builtin_concept("Alpha") is alpha
+ assert _concept_names(ontology) == ["Alpha"]
+
+
+def test_ensure_builtin_concept_will_not_invent_a_non_builtin():
+ ontology = OntologyComponent()
+
+ assert ontology.ensure_builtin_concept("Widget") is None
+ assert _concept_names(ontology) == []
diff --git a/converters/ontology/tests/test_examples_in_sync.py b/converters/ontology/tests/test_examples_in_sync.py
new file mode 100644
index 00000000..724092b1
--- /dev/null
+++ b/converters/ontology/tests/test_examples_in_sync.py
@@ -0,0 +1,51 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Guard against drift between the vendored test inputs under tests/fixtures/ and
+the canonical copies under the repo-level examples/ directory.
+
+The core test suite reads the vendored copies (so it runs from an sdist/wheel or
+subset checkout). This test only runs when examples/ is available — it fails if a
+vendored file falls out of sync, prompting a refresh.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+_FIXTURES_DIR = Path(__file__).resolve().parent / "fixtures"
+# tests/ -> ontology -> converters -> <repo root>
+_EXAMPLES_DIR = Path(__file__).resolve().parents[3] / "examples"
+
+# (vendored filename, canonical filename in examples/)
+_VENDORED = [("flights.yaml", "flights.yaml")]
+
+
+@pytest.mark.parametrize("vendored_name, example_name", _VENDORED)
+def test_vendored_input_matches_example(vendored_name: str, example_name: str):
+ example_path = _EXAMPLES_DIR / example_name
+ if not example_path.is_file():
+ pytest.skip(f"canonical example not present at {example_path}")
+
+ vendored_path = _FIXTURES_DIR / vendored_name
+ assert vendored_path.is_file(), f"vendored input missing: {vendored_path}"
+ assert vendored_path.read_text(encoding="utf-8") == example_path.read_text(encoding="utf-8"), (
+ f"'{vendored_path}' is out of sync with '{example_path}'. "
+ f"Refresh it with: cp {example_path} {vendored_path}"
+ )
\ No newline at end of file
diff --git a/converters/ontology/tests/test_flights_snapshot.py b/converters/ontology/tests/test_flights_snapshot.py
new file mode 100644
index 00000000..6f31430c
--- /dev/null
+++ b/converters/ontology/tests/test_flights_snapshot.py
@@ -0,0 +1,75 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Snapshot tests for the flights ontology.
+
+These lock in the converted structure and the round-tripped YAML so that any
+change in parsing/conversion output shows up as a reviewable diff.
+
+Regenerate the snapshots after an intentional change with:
+
+ pytest tests/test_flights_snapshot.py --snapshot-update
+"""
+
+from __future__ import annotations
+
+from ossie_ontology.converter.ossie_to_spec.converter import OssieToSpecConverter
+from ossie_ontology.model import OntologyComponent, OssieOntology
+
+
+def _render_structure(model: OssieOntology) -> str:
+ """Render a compact, deterministic text summary of the ontology structure."""
+ ontology: OntologyComponent = model.ontology
+ lines: list[str] = [
+ f"name: {model.name}",
+ f"version: {model.version}",
+ f"description: {model.description}",
+ "",
+ "ontology requires:",
+ ]
+ for req in ontology.requires:
+ lines.append(f" - {req}")
+
+ lines.append("")
+ lines.append("concepts:")
+ for concept in sorted(ontology.concepts(exclude_builtin=True), key=lambda c: c.name):
+ type_name = concept.type.name if concept.type else "None"
+ lines.append(f" {concept.name} ({type_name})")
+ if concept.extends:
+ lines.append(f" extends: {', '.join(p.name for p in concept.extends)}")
+ if concept.identify_by:
+ lines.append(f" identify_by: {', '.join(sorted(concept.identify_by))}")
+ for req in concept.requires:
+ lines.append(f" requires: {req}")
+
+ lines.append("")
+ lines.append("relationships:")
+ for rel in sorted(ontology.relationships, key=lambda r: r.full_name):
+ mult = rel.multiplicity.name if rel.multiplicity else "None"
+ signature = " -> ".join(c.name for c in rel.signature)
+ lines.append(f" {rel.full_name} [{mult}]: {signature}")
+
+ return "\n".join(lines) + "\n"
+
+
+def test_flights_structure_snapshot(flights_model, snapshot):
+ snapshot.assert_match(_render_structure(flights_model), "flights_structure.txt")
+
+
+def test_flights_roundtrip_yaml_snapshot(flights_model, snapshot):
+ spec = OssieToSpecConverter.convert(flights_model)
+ snapshot.assert_match(spec.dump_yaml(), "flights_roundtrip.yaml")
\ No newline at end of file
diff --git a/converters/ontology/tests/test_graph.py b/converters/ontology/tests/test_graph.py
new file mode 100644
index 00000000..a7652ab6
--- /dev/null
+++ b/converters/ontology/tests/test_graph.py
@@ -0,0 +1,91 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Tests for the topological sorts.
+
+An edge naming something outside `nodes` and a real cycle both used to stall
+Kahn's algorithm, and both came back as "the graph contains a cycle". They are
+different problems with different fixes, and only the caller knows what a
+dangling endpoint of its own means — so the sorts ignore those edges and keep
+the cycle report for cycles.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from ossie_ontology.common.graph import (
+ is_acyclic_graph,
+ topological_sort,
+ topological_sort_break_cycles,
+)
+
+
+def _precedes(order: list[str], first: str, second: str) -> bool:
+ return order.index(first) < order.index(second)
+
+
+def test_topological_sort_orders_a_chain():
+ order = topological_sort(["c", "b", "a"], [("a", "b"), ("b", "c")])
+
+ assert sorted(order) == ["a", "b", "c"]
+ assert _precedes(order, "a", "b") and _precedes(order, "b", "c")
+
+
+def test_edge_to_an_unknown_node_is_ignored():
+ """It orders nothing among the nodes given, so it constrains nothing."""
+ order = topological_sort(["a", "b"], [("missing", "a"), ("a", "b")])
+
+ assert sorted(order) == ["a", "b"]
+ assert _precedes(order, "a", "b")
+
+
+def test_edge_from_a_known_node_to_an_unknown_one_is_ignored():
+ order = topological_sort(["a", "b"], [("a", "missing"), ("a", "b")])
+
+ assert sorted(order) == ["a", "b"]
+
+
+def test_cycle_still_raises():
+ with pytest.raises(ValueError, match="contains a cycle"):
+ topological_sort(["a", "b"], [("a", "b"), ("b", "a")])
+
+
+def test_a_node_pointing_at_itself_is_a_cycle():
+ with pytest.raises(ValueError, match="contains a cycle"):
+ topological_sort(["a"], [("a", "a")])
+
+
+def test_is_acyclic_graph_distinguishes_the_two():
+ assert is_acyclic_graph(["a", "b"], [("missing", "a")])
+ assert not is_acyclic_graph(["a", "b"], [("a", "b"), ("b", "a")])
+
+
+def test_break_cycles_ignores_unknown_nodes_and_removes_nothing():
+ """The cycle-breaking sort already skipped these; it stays that way."""
+ order, removed = topological_sort_break_cycles(["a", "b"], [("missing", "a"), ("a", "b")])
+
+ assert sorted(order) == ["a", "b"]
+ assert removed == []
+
+
+def test_break_cycles_removes_a_real_cycle_edge():
+ with pytest.warns(UserWarning, match="Cycle detected"):
+ order, removed = topological_sort_break_cycles(["a", "b"], [("a", "b"), ("b", "a")])
+
+ assert sorted(order) == ["a", "b"]
+ assert len(removed) == 1
diff --git a/converters/ontology/tests/test_ossie_parser.py b/converters/ontology/tests/test_ossie_parser.py
new file mode 100644
index 00000000..f8e36e03
--- /dev/null
+++ b/converters/ontology/tests/test_ossie_parser.py
@@ -0,0 +1,301 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Unit tests for OssieParser and the spec -> OssieOntology conversion, driven by
+the `examples/flights.yaml` ontology."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+import yaml
+
+from ossie_ontology.converter.ossie_to_spec.converter import (
+ OssieToSpecConverter,
+ _convert_ontology_concepts,
+)
+from ossie_ontology.model import (
+ Concept,
+ ConceptType,
+ OntologyComponent,
+ OssieOntology,
+ Relationship,
+ RelationshipMultiplicity,
+)
+from ossie_ontology.parser import OssieParser
+
+
+# ----- Document-level metadata ------------------------------------------
+
+def test_parse_returns_model_with_metadata(flights_model):
+ assert flights_model.name == "Flights"
+ assert flights_model.version == "0.2.0.dev0"
+ assert flights_model.description == "Ontology of flights into and out of airports."
+
+
+def test_parse_returns_populated_ontology(flights_model):
+ ontology = flights_model.ontology
+ # Built-in concepts (String, Integer, Decimal, ...) are always present on top
+ # of the ones declared in the spec.
+ assert len(ontology.concepts(exclude_builtin=True)) == 44
+ assert len(ontology.concepts()) > len(ontology.concepts(exclude_builtin=True))
+ assert len(ontology.relationships) == 58
+
+
+# ----- Ontology-level requires ------------------------------------------
+
+def test_ontology_level_requires(flights_model):
+ requires = [str(r) for r in flights_model.ontology.requires]
+ assert requires == ["COUNT[Airport] > 0", "COUNT[Carrier] > 0"]
+
+
+# ----- Concept-level requires -------------------------------------------
+
+@pytest.mark.parametrize(
+ "concept_name, expected",
+ [
+ ("DegreesLatitude", ["DegreesLatitude <= 90", "DegreesLatitude >= -90"]),
+ ("DegreesLongitude", ["DegreesLongitude <= 180", "DegreesLongitude >= -180"]),
+ (
+ "CancelationCode",
+ ["CancelationCode == 'A' OR CancelationCode == 'B' OR CancelationCode == 'C' OR CancelationCode == 'D'"],
+ ),
+ ],
+)
+def test_concept_requires(flights_model, concept_name, expected):
+ concept = flights_model.ontology.lookup_concept(concept_name)
+ assert concept is not None
+ assert [str(r) for r in concept.requires] == expected
+
+
+# ----- Value-type inheritance -------------------------------------------
+
+@pytest.mark.parametrize(
+ "concept_name, parent_name",
+ [
+ ("NrFeet", "Decimal"),
+ ("NrPounds", "Integer"),
+ ("Capacity", "NrPounds"),
+ ("CancelationCode", "String"),
+ ("Delay", "NrMinutes"),
+ ],
+)
+def test_value_type_extends(flights_model, concept_name, parent_name):
+ concept = flights_model.ontology.lookup_concept(concept_name)
+ assert concept is not None
+ assert concept.type == ConceptType.VALUE_TYPE
+ assert [p.name for p in concept.extends] == [parent_name]
+
+
+# ----- Identifiers -------------------------------------------------------
+
+def test_identify_by(flights_model):
+ airport = flights_model.ontology.lookup_concept("Airport")
+ assert airport is not None
+ assert airport.type == ConceptType.ENTITY_TYPE
+ assert list(airport.identify_by.keys()) == ["Airport.code"]
+
+
+# ----- Relationship multiplicity ----------------------------------------
+
+def test_relationship_multiplicity(flights_model):
+ ontology = flights_model.ontology
+ airport = ontology.lookup_concept("Airport")
+ code_rel = ontology.lookup_concept_relationship(airport, "code")
+ assert code_rel is not None
+ assert code_rel.multiplicity == RelationshipMultiplicity.ONE_TO_ONE
+
+
+# ----- Ontology mapping / semantic model --------------------------------
+
+def test_ontology_mapping(flights_model):
+ assert len(flights_model.ontology_mappings) == 1
+ mapping = flights_model.ontology_mappings[0]
+ semantic_model = mapping.semantic_model
+ dataset_names = {d.name for d in semantic_model.datasets}
+ assert {"AIRPORT", "FLIGHT", "CARRIER", "ROUTE"} <= dataset_names
+ assert len(mapping.concept_mappings) == 11
+
+
+# ----- load_data --------------------------------------------------------
+
+def test_load_data_reads_yaml(tmp_path: Path):
+ path = tmp_path / "spec.yaml"
+ path.write_text("a: 1\nb:\n - x\n - y\n")
+ assert OssieParser.load_data(path) == {"a": 1, "b": ["x", "y"]}
+
+
+def test_load_data_reads_json(tmp_path: Path):
+ path = tmp_path / "spec.json"
+ path.write_text(json.dumps({"a": 1, "b": ["x", "y"]}))
+ assert OssieParser.load_data(path) == {"a": 1, "b": ["x", "y"]}
+
+
+def test_parse_of_flights_as_json(flights_path: Path, tmp_path: Path):
+ # The parser selects JSON vs YAML from the file suffix; a .json rendering of
+ # the same spec must produce an equivalent model.
+ json_path = tmp_path / "flights.json"
+ json_path.write_text(json.dumps(yaml.safe_load(flights_path.read_text())))
+ model = OssieParser().parse(json_path)
+ assert model.name == "Flights"
+ assert len(model.ontology.concepts(exclude_builtin=True)) == 44
+
+
+# ----- Error handling ---------------------------------------------------
+
+def test_parse_rejects_directory(tmp_path: Path):
+ with pytest.raises(ValueError, match="is not a file"):
+ OssieParser().parse(tmp_path)
+
+
+def test_parse_rejects_missing_file(tmp_path: Path):
+ with pytest.raises(ValueError, match="is not a file"):
+ OssieParser().parse(tmp_path / "does_not_exist.yaml")
+
+
+def test_spec_requires_parse_first():
+ parser = OssieParser()
+ with pytest.raises(RuntimeError):
+ parser.spec()
+
+
+def test_parsers_do_not_share_formula_factories():
+ a, b = OssieParser(), OssieParser()
+ assert a._formula_factory is not b._formula_factory
+ assert a._mapping_formula_factory is not b._mapping_formula_factory
+
+
+# ----- Round-trip invariants --------------------------------------------
+
+def _structure_sets(model: OssieOntology):
+ ontology = model.ontology
+ return (
+ {c.name for c in ontology.concepts(exclude_builtin=True)},
+ {r.full_name for r in ontology.relationships},
+ {str(req) for req in ontology.requires},
+ )
+
+
+def test_roundtrip_preserves_structure(flights_path, tmp_path: Path):
+ """Parsing -> spec -> YAML -> parsing preserves the ontology structure.
+
+ Note: concept/relationship *emission order* is not guaranteed to be stable
+ across a round-trip (it depends on the topological tie-breaking of the input
+ order), so we compare the sets of concepts, relationships, and requires
+ rather than the raw YAML.
+ """
+ model1 = OssieParser().parse(flights_path)
+ yaml1 = OssieToSpecConverter.convert(model1).dump_yaml()
+
+ roundtrip_path = tmp_path / "roundtrip.yaml"
+ roundtrip_path.write_text(yaml1)
+ model2 = OssieParser().parse(roundtrip_path)
+
+ assert _structure_sets(model1) == _structure_sets(model2)
+
+
+def test_dump_yaml_is_deterministic_for_fixed_input(flights_path):
+ """The same input file always dumps to identical YAML (so the snapshot is
+ stable across runs)."""
+ yaml_a = OssieToSpecConverter.convert(OssieParser().parse(flights_path)).dump_yaml()
+ yaml_b = OssieToSpecConverter.convert(OssieParser().parse(flights_path)).dump_yaml()
+ assert yaml_a == yaml_b
+
+
+# ----- concept dependency errors ----------------------------------------
+
+def _write_spec(tmp_path: Path, concepts: list[dict]) -> Path:
+ path = tmp_path / "spec.yaml"
+ path.write_text(yaml.safe_dump({"version": "0.1.0", "name": "Demo", "ontology": concepts}))
+ return path
+
+
+def _concept(name: str, *, extends: list[str] | None = None) -> dict:
+ concept: dict = {
+ "concept": name,
+ "type": "EntityType",
+ "relationships": [{"name": f"{name.lower()}_id", "roles": [{"concept": "String"}]}],
+ "identify_by": [f"{name.lower()}_id"],
+ }
+ if extends:
+ concept["extends"] = extends
+ return concept
+
+
+def test_extends_an_undeclared_concept_names_it(tmp_path: Path):
+ """The dependency sort runs before this check, so it must not claim a cycle.
+
+ An `extends` target missing from the document is a dangling edge, not a
+ loop, and the author needs to be told which name is missing.
+ """
+ path = _write_spec(tmp_path, [_concept("Gadget", extends=["Undeclared"])])
+
+ with pytest.raises(ValueError, match="Subtype 'Undeclared' is not declared"):
+ OssieParser().parse(path)
+
+
+def test_extends_in_a_cycle_is_still_reported_as_a_cycle(tmp_path: Path):
+ path = _write_spec(
+ tmp_path, [_concept("A", extends=["B"]), _concept("B", extends=["A"])]
+ )
+
+ with pytest.raises(ValueError, match="contains a cycle"):
+ OssieParser().parse(path)
+
+
+def test_extends_a_builtin_is_not_a_dependency(tmp_path: Path):
+ """Builtins are never declared in the document, and never sorted."""
+ path = _write_spec(tmp_path, [_concept("Code", extends=["String"])])
+
+ model = OssieParser().parse(path)
+
+ concept = model.ontology.lookup_concept("Code")
+ assert concept is not None
+ assert [p.name for p in concept.extends] == ["String"]
+
+
+# ----- grouping relationships under their concept -----------------------
+
+def test_relationships_are_grouped_under_their_own_container():
+ """Each concept emits exactly its own relationships, in declaration order.
+
+ The conversion groups the ontology's relationships by container in one pass,
+ so this pins the assignment: interleaved declarations, a concept that is not
+ a component (dropped, along with the relationship it contains), and the
+ order within each group.
+ """
+ ontology = OntologyComponent()
+ alpha = Concept(name="Alpha", type=ConceptType.ENTITY_TYPE)
+ beta = Concept(name="Beta", type=ConceptType.ENTITY_TYPE)
+ hidden = Concept(name="Hidden", type=ConceptType.ENTITY_TYPE, is_component=False)
+ for concept in (alpha, beta, hidden):
+ ontology.add_concept(concept)
+ for container, name in [
+ (alpha, "a1"), (beta, "b1"), (alpha, "a2"), (hidden, "h1"), (beta, "b2"),
+ ]:
+ ontology.add_relationship(
+ Relationship(name=name, container=container, relates=[(beta, None)])
+ )
+
+ components = _convert_ontology_concepts(ontology)
+
+ assert {c.concept: [r.name for r in c.relationships] for c in components} == {
+ "Alpha": ["a1", "a2"],
+ "Beta": ["b1", "b2"],
+ }
diff --git a/converters/ontology/tests/test_palantir_converter.py b/converters/ontology/tests/test_palantir_converter.py
new file mode 100644
index 00000000..3edd4980
--- /dev/null
+++ b/converters/ontology/tests/test_palantir_converter.py
@@ -0,0 +1,1212 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Tests for what the Palantir converter admits into the model, and why.
+
+Two things decide it. The first is *status*: an export marks each object type,
+property and relation as active, experimental, deprecated and so on, and only
+some of those belong in a converted model. The defaults here suit an ontology in
+production use — active work, plus the endorsed and intermediary entities it
+leans on. They are class attributes read through ``allowed_*_statuses()``
+methods rather than inline checks, so a caller with a different definition of
+"finished" (a draft ontology, say, where nearly everything is still
+experimental) subclasses and widens them. These tests pin both the defaults and
+the overriding.
+
+The second is *column matching*: an export's two halves routinely disagree on
+the case of a physical column name, so a primary key naming ``LOCNO`` has to
+find a dataset field called ``locno``. Exact matches still win.
+
+Each test builds the smallest export that shows the behaviour and runs it
+through the real parser, so the fixtures stay in the JSON shapes an export
+actually uses.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Iterable
+
+import pytest
+
+from ossie_ontology.converter.ossie_to_spec.converter import OssieToSpecConverter
+from ossie_ontology.converter.palantir_to_ossie.converter import PalantirToOssieConverter
+from ossie_ontology.external.palantir.model import Status
+from ossie_ontology.external.palantir.parser import PalantirParser
+from ossie_ontology.model import ConceptMapping, DatasetField, OssieOntology
+from ossie_ontology.parser import OssieParser
+
+
+# ----- export builders --------------------------------------------------
+
+def _prop(
+ rid: str,
+ id_: str,
+ *,
+ status: str | None = None,
+ column: str | None = None,
+ pk_columns: dict[str, str] | None = None,
+ type_name: str = "STRING",
+) -> dict[str, Any]:
+ prop: dict[str, Any] = {"rid": rid, "id": id_, "baseType": {"type": type_name}}
+ if status:
+ prop["status"] = {"type": status}
+ if column:
+ prop["column"] = column
+ if pk_columns:
+ # Keyed by the backing dataset's rid: a primary key can sit in a
+ # differently named column in each dataset that feeds the object type.
+ prop["primaryKeyMapping"] = {
+ ds_rid: {"columnName": name} for ds_rid, name in pk_columns.items()
+ }
+ return prop
+
+
+def _object_type(
+ key: str,
+ name: str,
+ *,
+ status: str | None = None,
+ properties: Iterable[dict[str, Any]] = (),
+ primary_keys: Iterable[str] | None = None,
+ datasources: Iterable[str] | None = None,
+) -> dict[str, Any]:
+ """An object type identified by ``<key>_id``, plus any *properties* given.
+
+ With no *datasources*, carries no ``datasources`` entry, so the parser falls
+ back to matching a dataset whose ``mainDatasetId`` is the object type's own
+ rid — which is what :func:`_dataset` builds. Pass dataset rids to back the
+ object type with several datasets instead.
+ """
+ props = [_prop(f"ri.p.{key}_id", f"{key}_id"), *properties]
+ ot: dict[str, Any] = {
+ "rid": _ot_rid(key),
+ "id": key,
+ "displayName": name,
+ "properties": props,
+ "primaryKeys": list(primary_keys) if primary_keys is not None else [f"{key}_id"],
+ }
+ if status:
+ ot["status"] = {"type": status}
+ if datasources is not None:
+ ot["datasources"] = [
+ {"datasourceRid": rid, "backingResourceRid": rid} for rid in datasources
+ ]
+ return ot
+
+
+def _many_to_one(
+ key: str,
+ *,
+ one: str,
+ many: str,
+ key_map: dict[str, str],
+ status: str | None = None,
+) -> dict[str, Any]:
+ """A M:1 relation from the *many* object type to the *one* object type.
+
+ ``key_map`` maps a primary-key property rid on the one side to the property
+ rid holding it on the many side.
+ """
+ relation: dict[str, Any] = {
+ "rid": f"ri.rel.{key}",
+ "id": key,
+ "definition": {
+ "type": "oneToMany",
+ "oneToMany": {
+ "objectTypeRidOneSide": _ot_rid(one),
+ "objectTypeRidManySide": _ot_rid(many),
+ "oneSidePrimaryKeyToManySidePropertyMapping": key_map,
+ },
+ },
+ }
+ if status:
+ relation["status"] = {"type": status}
+ return relation
+
+
+def _many_to_many(key: str, *, a: str, b: str, status: str | None = None) -> dict[str, Any]:
+ """A M:M relation between object types *a* and *b*, keyed on their own ids.
+
+ Each side's primary key maps to the like-named column of the join table,
+ which the relation carries as its backing datasource.
+ """
+ relation: dict[str, Any] = {
+ "rid": f"ri.rel.{key}",
+ "id": key,
+ "definition": {
+ "type": "manyToMany",
+ "manyToMany": {
+ "objectTypeRidA": _ot_rid(a),
+ "objectTypeRidB": _ot_rid(b),
+ "objectTypeAPrimaryKeyPropertyMapping": {f"ri.p.{a}_id": f"{a}_id"},
+ "objectTypeBPrimaryKeyPropertyMapping": {f"ri.p.{b}_id": f"{b}_id"},
+ "joinTableDatasource": [
+ {"datasourceRid": f"ri.ds.{key}", "backingResourceRid": f"ri.res.{key}"}
+ ],
+ },
+ },
+ }
+ if status:
+ relation["status"] = {"type": status}
+ return relation
+
+
+def _intermediary(
+ key: str,
+ *,
+ a: str,
+ b: str,
+ via: str,
+ link_a: str,
+ link_b: str,
+ status: str | None = None,
+) -> dict[str, Any]:
+ """An intermediary relation joining *a* to *b* through the *via* object type.
+
+ ``link_a`` and ``link_b`` name the two M:1 relations it is derived from;
+ both must be present in the export or the parser rejects it.
+ """
+ relation: dict[str, Any] = {
+ "rid": f"ri.rel.{key}",
+ "id": key,
+ "definition": {
+ "type": "intermediary",
+ "intermediary": {
+ "objectTypeRidA": _ot_rid(a),
+ "objectTypeRidB": _ot_rid(b),
+ "intermediaryObjectTypeRid": _ot_rid(via),
+ "aToIntermediaryLinkTypeRid": f"ri.rel.{link_a}",
+ "intermediaryToBLinkTypeRid": f"ri.rel.{link_b}",
+ },
+ },
+ }
+ if status:
+ relation["status"] = {"type": status}
+ return relation
+
+
+def _dataset(key: str, columns: Iterable[str]) -> dict[str, Any]:
+ """The dataset backing object type *key*, with the columns named."""
+ return {
+ "mainDatasetId": _ot_rid(key),
+ "datasetName": f"{key}_table",
+ "datasetSchema": [{"name": column, "type": "STRING"} for column in columns],
+ }
+
+
+def _ot_rid(key: str) -> str:
+ return f"ri.ot.{key}"
+
+
+def _convert(
+ tmp_path: Path,
+ object_types: Iterable[dict[str, Any]],
+ *,
+ relations: Iterable[dict[str, Any]] = (),
+ datasets: Iterable[dict[str, Any]] = (),
+ converter: type[PalantirToOssieConverter] = PalantirToOssieConverter,
+) -> OssieOntology:
+ """Write an extracted-folder export, parse it, and convert it.
+
+ Both files are rewritten on every call, so a test that converts the same
+ export under two different policies can call this twice.
+ """
+ export = tmp_path / "export"
+ (export / "data_sets").mkdir(parents=True, exist_ok=True)
+ (export / "ontology.json").write_text(
+ json.dumps({"objectTypes": list(object_types), "relations": list(relations)})
+ )
+ (export / "data_sets" / "ds.json").write_text(json.dumps(list(datasets)))
+ return converter().convert(PalantirParser().parse(export))
+
+
+# ----- assertion helpers ------------------------------------------------
+
+def _concept_names(model: OssieOntology) -> set[str]:
+ return {c.name for c in model.ontology.concepts(exclude_builtin=True)}
+
+
+def _relationship_names(model: OssieOntology) -> set[str]:
+ return {r.full_name for r in model.ontology.relationships}
+
+
+def _concept_mapping(model: OssieOntology, concept_name: str) -> ConceptMapping:
+ mappings = [
+ cm
+ for om in model.ontology_mappings
+ for cm in om.concept_mappings
+ if cm.concept.name == concept_name
+ ]
+ assert len(mappings) == 1, f"expected one mapping for '{concept_name}', got {len(mappings)}"
+ return mappings[0]
+
+
+def _mapped_relationship_names(model: OssieOntology, concept_name: str) -> set[str]:
+ """Names of the relationships a concept's mapping actually populates."""
+ names = set()
+ for lm in _concept_mapping(model, concept_name).link_mappings:
+ for child in lm.children or []:
+ assert child.relationship is not None
+ names.add(child.relationship.full_name)
+ return names
+
+
+def _identifier_columns(model: OssieOntology, concept_name: str) -> list[str]:
+ """The dataset fields a concept's mapping identifies its instances by."""
+ [object_mapping] = _concept_mapping(model, concept_name).object_mappings
+ columns = []
+ for rm in object_mapping.referent_mappings or []:
+ assert isinstance(rm.expression, DatasetField)
+ columns.append(rm.expression.name)
+ return columns
+
+
+# ----- object type statuses ---------------------------------------------
+
+def test_default_policy_admits_active_endorsed_and_intermediary(tmp_path: Path):
+ model = _convert(tmp_path, [
+ _object_type("alpha", "Alpha", status="active"),
+ _object_type("bravo", "Bravo", status="endorsed"),
+ _object_type("charlie", "Charlie", status="intermediary"),
+ _object_type("delta", "Delta", status="experimental"),
+ _object_type("echo", "Echo", status="deprecated"),
+ ])
+ assert _concept_names(model) == {"Alpha", "Bravo", "Charlie"}
+
+
+def test_object_type_named_like_a_builtin_is_reported(tmp_path: Path):
+ """`date` pascal-cases to `Date`, which is a builtin value type.
+
+ Letting it through gives the entity the builtin's name, and every DATE
+ column in the export is then typed by this object type — so it is reported
+ as the concept-name collision it is, naming the object type rather than
+ surfacing later as a complaint about a missing 'date_id' property.
+ """
+ object_types = [
+ _object_type(
+ "date",
+ "date",
+ status="active",
+ properties=[_prop("ri.p.label", "label", column="label")],
+ )
+ ]
+
+ with pytest.raises(ValueError, match="which is a builtin value type"):
+ _convert(tmp_path, object_types, datasets=[_dataset("date", ["date_id", "label"])])
+
+
+def test_object_type_statuses_can_be_widened_by_a_subclass(tmp_path: Path):
+ """The extension point a draft-ontology converter is built on."""
+
+ class DraftConverter(PalantirToOssieConverter):
+ OBJECT_TYPE_STATUSES = PalantirToOssieConverter.OBJECT_TYPE_STATUSES | {Status.EXPERIMENTAL}
+
+ object_types = [
+ _object_type("alpha", "Alpha", status="active"),
+ _object_type("delta", "Delta", status="experimental"),
+ ]
+ assert _concept_names(_convert(tmp_path, object_types)) == {"Alpha"}
+
+ widened = _convert(tmp_path, object_types, converter=DraftConverter)
+ assert _concept_names(widened) == {"Alpha", "Delta"}
+
+
+# ----- property statuses ------------------------------------------------
+
+def _widget_export() -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+ """One object type with a property per status, and its backing dataset."""
+ object_types = [
+ _object_type(
+ "widget",
+ "Widget",
+ status="active",
+ properties=[
+ _prop("ri.p.label", "label", status="active", column="label"),
+ _prop("ri.p.note", "note", status="experimental", column="note"),
+ _prop("ri.p.legacy", "legacy", status="deprecated", column="legacy"),
+ ],
+ )
+ ]
+ return object_types, [_dataset("widget", ["widget_id", "label", "note", "legacy"])]
+
+
+def test_experimental_property_is_declared_but_not_mapped(tmp_path: Path):
+ """An experimental property is part of the ontology, but nothing populates it.
+
+ The two policies differ on purpose: the relationship is worth declaring
+ while the work is in progress, but pointing a mapping at a column that is
+ still being reshaped is not.
+ """
+ object_types, datasets = _widget_export()
+ model = _convert(tmp_path, object_types, datasets=datasets)
+
+ assert "Widget.note" in _relationship_names(model)
+ assert _mapped_relationship_names(model, "Widget") == {"Widget.label"}
+
+
+def test_deprecated_property_is_not_converted_at_all(tmp_path: Path):
+ object_types, datasets = _widget_export()
+ model = _convert(tmp_path, object_types, datasets=datasets)
+
+ assert "Widget.legacy" not in _relationship_names(model)
+
+
+def test_mapping_property_statuses_can_be_widened_by_a_subclass(tmp_path: Path):
+ class DraftConverter(PalantirToOssieConverter):
+ MAPPING_PROPERTY_STATUSES = (
+ PalantirToOssieConverter.MAPPING_PROPERTY_STATUSES | {Status.EXPERIMENTAL}
+ )
+
+ object_types, datasets = _widget_export()
+ model = _convert(tmp_path, object_types, datasets=datasets, converter=DraftConverter)
+
+ assert _mapped_relationship_names(model, "Widget") == {"Widget.label", "Widget.note"}
+
+
+# ----- property types ---------------------------------------------------
+
+def _role_player_types(model: OssieOntology) -> dict[str, str]:
+ """The concept each relationship's value role is typed by."""
+ return {r.full_name: r.signature[-1].name for r in model.ontology.relationships}
+
+
+def _field_types(model: OssieOntology) -> dict[str, str]:
+ """The concept each dataset field is typed by."""
+ return {
+ field.name: field.type.name
+ for om in model.ontology_mappings
+ for dataset in om.semantic_model.datasets
+ for field in dataset.fields
+ if field.type is not None
+ }
+
+
+def test_property_types_without_a_scalar_equivalent_are_not_numeric(tmp_path: Path):
+ """A blob or a reference must not come out typed as a number.
+
+ Both the madlib role and the dataset field are typed from the same mapping,
+ so a wrong answer asserts arithmetic over an attachment column in two
+ places at once, with nothing downstream to reject it.
+ """
+ types = {
+ "attachment": "ATTACHMENT",
+ "media_ref": "MEDIA_REFERENCE",
+ "secret": "CIPHER_TEXT",
+ "shape": "STRUCT",
+ "embedding": "VECTOR",
+ "whatever": "ANY",
+ "big": "LONG",
+ "small": "SHORT",
+ }
+ object_types = [
+ _object_type(
+ "doc",
+ "Doc",
+ status="active",
+ properties=[
+ _prop(f"ri.p.{name}", name, column=name, type_name=palantir_type)
+ for name, palantir_type in types.items()
+ ],
+ )
+ ]
+ datasets = [
+ {
+ "mainDatasetId": _ot_rid("doc"),
+ "datasetName": "doc_table",
+ "datasetSchema": [{"name": "doc_id", "type": "STRING"}]
+ + [{"name": name, "type": palantir_type} for name, palantir_type in types.items()],
+ }
+ ]
+
+ model = _convert(tmp_path, object_types, datasets=datasets)
+
+ expected = {
+ "attachment": "String", # an attachment rid
+ "media_ref": "String", # a media reference
+ "secret": "String", # ciphertext
+ "shape": "String", # no builtin describes a struct
+ "embedding": "String", # nor a vector
+ "whatever": "Any", # this one has an exact builtin
+ "big": "Integer",
+ "small": "Integer",
+ }
+ role_types = _role_player_types(model)
+ assert {name: role_types[f"Doc.{name}"] for name in expected} == expected
+ field_types = _field_types(model)
+ assert {name: field_types[name] for name in expected} == expected
+
+
+def test_unrecognized_column_type_falls_back_to_string(tmp_path: Path):
+ """A warehouse type the enum has no name for must not fail the conversion.
+
+ Column types drift with the export format, the field type is not serialized
+ downstream at all, and a column with no type already falls back to String —
+ so an unknown one is reported and carried, not raised. A bare ARRAY column
+ is still dropped, as before.
+ """
+ object_types = [
+ _object_type(
+ "doc",
+ "Doc",
+ status="active",
+ properties=[_prop("ri.p.blob", "blob", column="blob")],
+ )
+ ]
+ datasets = [
+ {
+ "mainDatasetId": _ot_rid("doc"),
+ "datasetName": "doc_table",
+ "datasetSchema": [
+ {"name": "doc_id", "type": "STRING"},
+ {"name": "blob", "type": "BINARY"},
+ {"name": "props", "type": "MAP<STRING, STRING>"},
+ {"name": "tags", "type": "ARRAY"},
+ {"name": "untyped"},
+ ],
+ }
+ ]
+
+ with pytest.warns(UserWarning, match="Unrecognized column type 'BINARY'"):
+ model = _convert(tmp_path, object_types, datasets=datasets)
+
+ assert _field_types(model) == {
+ "doc_id": "String",
+ "blob": "String",
+ "props": "String",
+ "untyped": "String", # the pre-existing fallback this one now matches
+ }
+ # And the mapping is still built, rather than lost with the run.
+ assert _identifier_columns(model, "Doc") == ["doc_id"]
+
+
+def test_column_name_becomes_an_identifier_and_keeps_reading_its_column(tmp_path: Path):
+ """A column name that is not an identifier has to be handled on both sides.
+
+ The field *name* is what a mapping expression refers to, and it is matched
+ against an identifier pattern when the spec is read back — a name holding a
+ space fails that and is quietly taken for a formula rather than the field.
+ The field's *expression* is the SQL that reads the column, so it has to go
+ on naming the column exactly, quoted.
+ """
+ columns = {"net amt": "net_amt", "a-b": "a_b", "x.y": "x_y", "9lives": "_9lives"}
+ object_types = [
+ _object_type(
+ "doc",
+ "Doc",
+ status="active",
+ properties=[
+ _prop(f"ri.p.p{i}", f"p{i}", column=column)
+ for i, column in enumerate(columns)
+ ],
+ )
+ ]
+ datasets = [
+ {
+ "mainDatasetId": _ot_rid("doc"),
+ "datasetName": "doc_table",
+ "datasetSchema": [{"name": "doc_id", "type": "STRING"}]
+ + [{"name": column, "type": "STRING"} for column in columns],
+ }
+ ]
+
+ model = _convert(tmp_path, object_types, datasets=datasets)
+
+ [dataset] = [ds for om in model.ontology_mappings for ds in om.semantic_model.datasets]
+ expressions = {
+ field.name: field.expression.dialects[0].expression
+ for field in dataset.fields
+ if field.expression is not None
+ }
+ assert set(expressions) == {"doc_id", *columns.values()}
+ assert expressions == {
+ "doc_id": "doc_id", # already an identifier, so left alone
+ "net_amt": '"net amt"',
+ "a_b": '"a-b"',
+ "x_y": '"x.y"',
+ "_9lives": '"9lives"', # a leading digit is not a bare identifier either
+ }
+
+
+def test_field_name_survives_a_round_trip_as_a_field(tmp_path: Path):
+ """The reason the name matters: it has to resolve on the way back in."""
+ object_types = [
+ _object_type(
+ "doc",
+ "Doc",
+ status="active",
+ properties=[_prop("ri.p.net_amt", "net_amt", column="net amt")],
+ )
+ ]
+ datasets = [
+ {
+ "mainDatasetId": _ot_rid("doc"),
+ "datasetName": "doc_table",
+ "datasetSchema": [
+ {"name": "doc_id", "type": "STRING"},
+ {"name": "net amt", "type": "STRING"},
+ ],
+ }
+ ]
+ model = _convert(tmp_path, object_types, datasets=datasets)
+
+ roundtrip = tmp_path / "roundtrip.yaml"
+ roundtrip.write_text(OssieToSpecConverter.convert(model).dump_yaml())
+ reparsed = OssieParser().parse(roundtrip)
+
+ expressions = [
+ child.object_mapping.expression
+ for om in reparsed.ontology_mappings
+ for cm in om.concept_mappings
+ for link_mapping in cm.link_mappings
+ for child in link_mapping.children or []
+ ]
+ assert expressions, "the property mapping did not survive the round trip"
+ for expression in expressions:
+ assert isinstance(expression, DatasetField), f"demoted to {type(expression).__name__}"
+
+
+def test_column_without_a_name_does_not_reach_the_converter(tmp_path: Path):
+ """The parser drops it; conversion proceeds on the columns that remain.
+
+ This used to crash in `_normalize_field_name` on a `None` name, naming
+ neither the dataset nor the column.
+ """
+ object_types = [
+ _object_type(
+ "doc",
+ "Doc",
+ status="active",
+ properties=[_prop("ri.p.label", "label", column="label")],
+ )
+ ]
+ datasets = [
+ {
+ "mainDatasetId": _ot_rid("doc"),
+ "datasetName": "doc_table",
+ "datasetSchema": [
+ {"name": "doc_id", "type": "STRING"},
+ {"type": "STRING"},
+ {"name": "label", "type": "STRING"},
+ ],
+ }
+ ]
+
+ with pytest.warns(UserWarning, match="Skipping column with missing name"):
+ model = _convert(tmp_path, object_types, datasets=datasets)
+
+ assert set(_field_types(model)) == {"doc_id", "label"}
+ assert _mapped_relationship_names(model, "Doc") == {"Doc.label"}
+
+
+# ----- relation statuses ------------------------------------------------
+
+def _linked_export(
+ *, ot_status: str, relation_status: str
... 1375 lines suppressed ...