diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
index 1b891b58..61631f44 100644
--- a/.github/workflows/build-docs.yml
+++ b/.github/workflows/build-docs.yml
@@ -35,7 +35,16 @@ jobs:
version: "0.9.28"
- name: Install dependencies
run: |
- uv sync --extra docs
+ uv sync --extra docs --extra dev
+
+ - name: Generate ontology visualization
+ run: |
+ uv run python docs/scripts/build_ontology_viz.py
+ uv run pre-commit run --files docs/assets/graflo-ontology-viz/*.json || true
+
+ - name: Verify committed viz assets are fresh
+ run: |
+ git diff --exit-code docs/assets/graflo-ontology-viz/
- name: Build site
run: |
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b1b4e2f9..2bacfab2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.8.0]
+
+### Added
+
+- **GraFlo meta-ontology** — OWL vocabulary at `https://ontology.growgraph.dev/graflo` (`owl:versionIRI` `…/1.0.0`, `owl:versionInfo` `1.0.0`) describing `GraphManifest`, `Schema`, `IngestionModel`, `ProtoTransform`, pipeline actor steps, bindings, and related enumerations. Shipped as `graflo/rdf/ontology/graflo.ttl` plus JSON-LD context `graflo-context.jsonld`.
+- **`graflo.rdf`** — `ManifestRdfSerializer` / `ManifestRdfDeserializer` for bidirectional conversion between `GraphManifest` (YAML/Pydantic) and RDF (Turtle, JSON-LD, N-Triples, RDF/XML).
+- **CLI** — `manifest-to-rdf` and `rdf-to-manifest` console scripts (`graflo.rdf.cli`).
+
+### Documentation
+
+- **[GraFlo ontology](docs/model/graflo_ontology.md)** — meta-model vs user-domain RDF (`RdfInferenceManager`), versioning, URI layout, CLI, and round-trip semantics.
+- **Interactive ontology visualization** — custom hierarchical class graph (rectangular nodes, subClassOf and optional property edges, pan/zoom) embedded on the GraFlo ontology page; built via `docs/scripts/build_ontology_viz.py` with committed assets under `docs/assets/graflo-ontology-viz/`.
+- **README** and **docs index** — feature overview and quick links for manifest ↔ RDF workflows.
+
## [1.7.33]
### Added
diff --git a/CITATION.cff b/CITATION.cff
index afdf0aa9..22f3e7a0 100644
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -1,5 +1,8 @@
-abstract: A framework for transforming tabular data ( CSV, SQL ) and hierarchical data ( JSON, XML ) into
- property graphs and ingesting them into graph databases ( ArangoDB, Neo4j ) .
+abstract: >-
+ Manifest-driven graph schema and ingestion for labeled property graphs:
+ define schemas in GraphManifest (YAML/Python), ingest from CSV/JSON/Parquet/SQL/RDF/SPARQL/API,
+ infer from PostgreSQL 3NF or OWL/RDFS, apply schema migrations, and project to ArangoDB, Neo4j,
+ TigerGraph, FalkorDB, Memgraph, or NebulaGraph.
authors:
- affiliation: GrowGraph
family-names: Belikov
@@ -11,5 +14,5 @@ doi: 10.5281/zenodo.15446131
license: []
license-url: https://github.com/growgraph/graflo/blob/main/LICENSE
message: If you use this software, please cite it using the metadata from this file.
-title: graflo
+title: GraFlo — Graph Schema & Transformation Language (GSTL)
type: software
diff --git a/README.md b/README.md
index 897051fc..06e60099 100644
--- a/README.md
+++ b/README.md
@@ -8,13 +8,19 @@
[](https://github.com/growgraph/graflo/actions/workflows/pre-commit.yml)
[]( https://doi.org/10.5281/zenodo.15446131)
-**GraFlo** is a manifest-driven toolkit for **labeled property graphs (LPGs)**: describe vertices, edges, and ingestion (`GraphManifest` — YAML or Python), then project and load into a target graph database.
+**GraFlo** is a manifest-driven schema and ingestion layer for **labeled property graphs (LPGs)**.
+Write a `GraphManifest` (YAML or Python) once — it defines vertices, edges, typed properties,
+identities, and DB profile — then infer, validate, migrate, and load into any supported graph engine.
### What you get
- **One pipeline, several graph databases** — The same manifest targets ArangoDB, Neo4j, TigerGraph, FalkorDB, Memgraph, or NebulaGraph; `DatabaseProfile` and DB-aware types absorb naming, defaults, and indexing differences.
- **Explicit identities** — Vertex identity fields and indexes back upserts so reloads merge on keys instead of blindly duplicating nodes.
- **Reusable ingestion** — `Resource` actor pipelines (including **vertex_router** / **edge** steps) bind to files, SQL, SPARQL/RDF, APIs, or in-memory batches via `Bindings` and the `DataSourceRegistry`.
+- **Schema as the contract** — `GraphManifest` is the single source of truth: vertex/edge definitions,
+ typed properties, identity fields, and DB profile are validated at `finish_init` time, not at
+ write time. Schema migrations are first-class (`graflo migrate_schema`).
+- **Manifest as linked data** — The [GraFlo ontology](https://growgraph.github.io/graflo/model/graflo_ontology/) (`gf:` at `ontology.growgraph.dev`) lets you export manifests to RDF and round-trip them for tooling, provenance, and SPARQL-facing catalogs.
### What’s in the manifest
@@ -56,7 +62,8 @@ The graph engines listed in **What you get** are the supported **output** `DBTyp
## More capabilities
-- **SPARQL & RDF** — Endpoints and RDF files (`.ttl`, `.rdf`, `.n3`, …); optional OWL/RDFS schema inference (`rdflib`, `SPARQLWrapper` in the default install).
+- **GraFlo ontology (manifest RDF)** — Serialize any `GraphManifest` to RDF (Turtle, JSON-LD) using the published vocabulary at [`https://ontology.growgraph.dev/graflo`](https://ontology.growgraph.dev/graflo) (`owl:versionInfo` **1.0.0**). Covers schema, ingestion (resources, transforms, pipeline actors), and bindings. Round-trip via `graflo.rdf` or the `manifest-to-rdf` / `rdf-to-manifest` CLI. This is the **meta-model** of GraFlo itself — distinct from importing a **domain** OWL ontology into an LPG schema (`RdfInferenceManager`). Details: [docs — GraFlo ontology](https://growgraph.github.io/graflo/model/graflo_ontology/).
+- **SPARQL & RDF** — Endpoints and RDF files (`.ttl`, `.rdf`, `.n3`, …); optional OWL/RDFS **domain** schema inference (`rdflib`, `SPARQLWrapper` in the default install).
- **Schema inference** — From PostgreSQL-style 3NF layouts (PK/FK heuristics) or from OWL/RDFS (`owl:Class` → vertices, `owl:ObjectProperty` → edges, `owl:DatatypeProperty` → vertex fields).
- **Schema migrations** — Plan and apply guarded schema deltas (`migrate_schema` console script → `graflo.cli.migrate_schema`; library in `graflo.migrate`; see docs).
- **Typed `properties`** — Optional field types (`INT`, `FLOAT`, `STRING`, `DATETIME`, `BOOL`) on vertices and edges.
@@ -212,7 +219,35 @@ caster = Caster(schema=schema, ingestion_model=ingestion_model)
# ... continue with ingestion
```
-### RDF / SPARQL Ingestion
+### Manifest ↔ RDF (GraFlo ontology)
+
+```bash
+# Serialize manifest YAML to Turtle (embeds gf: vocabulary when --include-ontology is default)
+uv run manifest-to-rdf manifest.yaml \
+ --base-uri https://growgraph.dev/manifests/mygraph/v1 \
+ --format turtle \
+ --output mygraph.ttl
+
+# Restore YAML from RDF
+uv run rdf-to-manifest mygraph.ttl \
+ --manifest-uri https://growgraph.dev/manifests/mygraph/v1 \
+ --output manifest.restored.yaml
+```
+
+```python
+from graflo import GraphManifest
+from graflo.rdf import ManifestRdfDeserializer, ManifestRdfSerializer
+
+manifest = GraphManifest.from_yaml("manifest.yaml")
+base = "https://growgraph.dev/manifests/mygraph/v1"
+
+ttl = ManifestRdfSerializer().to_turtle(manifest, base)
+restored = ManifestRdfDeserializer().from_turtle(ttl, base.rstrip("/"))
+```
+
+Ontology source: `graflo/rdf/ontology/graflo.ttl`. See [GraFlo ontology](https://growgraph.github.io/graflo/model/graflo_ontology/).
+
+### RDF / SPARQL Ingestion (domain ontology → LPG)
```python
from pathlib import Path
diff --git a/docs/assets/graflo-ontology-viz/embed.html b/docs/assets/graflo-ontology-viz/embed.html
new file mode 100644
index 00000000..da83e1b4
--- /dev/null
+++ b/docs/assets/graflo-ontology-viz/embed.html
@@ -0,0 +1,884 @@
+
+
+
+ GraFlo Ontology (v1.0.0)
+
+
+
+
+ All
+ Taxonomy
+ has*
+
+ Fit
+ Reset
+
+ Drag · scroll zoom · click class
+
+
Select a class to inspect its IRI and description.
";
+ return;
+ }
+ const node = nodeById.get(state.selectedId);
+ if (!node) {
+ return;
+ }
+ const props = data.edges.filter(function (edge) {
+ return edge.kind !== "subClassOf" && (edge.source === node.id || edge.target === node.id);
+ });
+ const subclasses = data.edges
+ .filter(function (edge) {
+ return edge.kind === "subClassOf" && edge.target === node.id;
+ })
+ .map(function (edge) {
+ return nodeById.get(edge.source);
+ })
+ .filter(Boolean);
+ const parents = data.edges
+ .filter(function (edge) {
+ return edge.kind === "subClassOf" && edge.source === node.id;
+ })
+ .map(function (edge) {
+ return nodeById.get(edge.target);
+ })
+ .filter(Boolean);
+
+ let html = "" + node.label + " ";
+ html += "" + node.id + "
";
+ if (node.comment) {
+ html += "";
+ }
+ if (node.layoutGroup === "isolated") {
+ html += "Layout: standalone class (no subClassOf links)
";
+ }
+ if (parents.length) {
+ html += "Parents: " + parents.map(function (p) {
+ return p.local;
+ }).join(", ") + "
";
+ }
+ if (subclasses.length) {
+ html += "Subclasses: " + subclasses.map(function (p) {
+ return p.local;
+ }).join(", ") + "
";
+ }
+ if (props.length) {
+ html += "Properties:
";
+ props.slice(0, 12).forEach(function (edge) {
+ html += "" + edge.label + "… +" + (props.length - 12) + " more ";
+ }
+ html += " ";
+ }
+ panel.innerHTML = html;
+ }
+
+ function nodeFromEventTarget(target) {
+ const group = target.closest ? target.closest(".node") : null;
+ if (!group) {
+ return null;
+ }
+ const nodeId = group.dataset.nodeId;
+ return nodeById.get(nodeId) || null;
+ }
+
+ function bindControls() {
+ const search = document.getElementById("search");
+ const relationFilter = document.getElementById("relation-filter");
+ if (search) {
+ search.addEventListener("input", function (event) {
+ state.search = event.target.value.trim();
+ applyHighlight();
+ });
+ }
+ if (relationFilter) {
+ relationFilter.addEventListener("change", function (event) {
+ state.relationMode = event.target.value;
+ renderEdges();
+ applyHighlight();
+ });
+ }
+
+ document.getElementById("fit-button").addEventListener("click", fitToScreen);
+ document.getElementById("reset-button").addEventListener("click", function () {
+ state.selectedId = null;
+ state.search = "";
+ if (search) {
+ search.value = "";
+ }
+ if (relationFilter) {
+ relationFilter.value = "all";
+ }
+ state.relationMode = "all";
+ updateDetails();
+ renderEdges();
+ applyHighlight();
+ fitToScreen();
+ });
+
+ svg.addEventListener("wheel", function (event) {
+ event.preventDefault();
+ const delta = event.deltaY > 0 ? 0.92 : 1.08;
+ const rect = svg.getBoundingClientRect();
+ const px = event.clientX - rect.left;
+ const py = event.clientY - rect.top;
+ state.tx = px - (px - state.tx) * delta;
+ state.ty = py - (py - state.ty) * delta;
+ state.scale *= delta;
+ applyTransform();
+ }, { passive: false });
+
+ svg.addEventListener("mousedown", function (event) {
+ state.dragMoved = false;
+ state.pointerDownX = event.clientX;
+ state.pointerDownY = event.clientY;
+ const node = nodeFromEventTarget(event.target);
+ state.lastX = event.clientX;
+ state.lastY = event.clientY;
+ if (node) {
+ state.draggingNodeId = node.id;
+ svg.classList.add("dragging-node");
+ return;
+ }
+ state.draggingViewport = true;
+ svg.classList.add("dragging");
+ });
+
+ window.addEventListener("mouseup", function (event) {
+ const pendingNodeId = state.draggingNodeId;
+ const draggedNode = pendingNodeId ? nodeById.get(pendingNodeId) : null;
+ if (draggedNode && state.dragMoved) {
+ resolveOverlaps(data.nodes);
+ reRenderGraph();
+ } else if (pendingNodeId && !state.dragMoved) {
+ selectNode(pendingNodeId);
+ }
+ state.draggingNodeId = null;
+ state.draggingViewport = false;
+ svg.classList.remove("dragging");
+ svg.classList.remove("dragging-node");
+ });
+
+ window.addEventListener("mousemove", function (event) {
+ markDragIfNeeded(event);
+ const dx = event.clientX - state.lastX;
+ const dy = event.clientY - state.lastY;
+ state.lastX = event.clientX;
+ state.lastY = event.clientY;
+
+ if (state.draggingNodeId) {
+ if (!state.dragMoved) {
+ return;
+ }
+ const node = nodeById.get(state.draggingNodeId);
+ if (!node) {
+ return;
+ }
+ node.x += dx / state.scale;
+ node.y += dy / state.scale;
+ reRenderGraph();
+ return;
+ }
+
+ if (!state.draggingViewport) {
+ return;
+ }
+ markDragIfNeeded(event);
+ state.tx += dx;
+ state.ty += dy;
+ applyTransform();
+ });
+
+ svg.addEventListener("click", function (event) {
+ const wasDrag = state.dragMoved;
+ state.dragMoved = false;
+ if (wasDrag) {
+ return;
+ }
+ if (nodeFromEventTarget(event.target)) {
+ return;
+ }
+ if (state.selectedId) {
+ state.selectedId = null;
+ updateDetails();
+ applyHighlight();
+ }
+ });
+ }
+
+ computeLayout();
+ reRenderGraph();
+ bindControls();
+ updateDetails();
+ fitToScreen();
+ window.addEventListener("resize", fitToScreen);
+})();
diff --git a/docs/assets/graflo-ontology-viz/index.html b/docs/assets/graflo-ontology-viz/index.html
new file mode 100644
index 00000000..3b1cc55d
--- /dev/null
+++ b/docs/assets/graflo-ontology-viz/index.html
@@ -0,0 +1,907 @@
+
+
+
+ GraFlo Ontology (v1.0.0)
+
+
+
+ Drag · scroll zoom · click class
+
+
Open full screen
+
+## What the vocabulary covers
+
+**Schema block**
+
+- `gf:GraphManifest`, `gf:Schema`, `gf:CoreSchema`, `gf:GraphMetadata`, `gf:DatabaseProfile`
+- `gf:VertexConfig`, `gf:EdgeConfig`, `gf:Vertex`, `gf:Edge`, `gf:Field`, `gf:Identity`
+- `gf:FieldType` individuals (`gf:INT`, `gf:STRING`, …)
+
+**Ingestion block**
+
+- `gf:IngestionModel`, `gf:Resource`, `gf:ProtoTransform`, `gf:Transform`
+- `gf:DressConfig`, `gf:KeySelectionConfig`, `gf:EdgeInferSpec`
+- Pipeline actor steps (blank nodes): `gf:VertexActor`, `gf:EdgeActor`, `gf:TransformActor`, `gf:DescendActor`, `gf:VertexRouterActor` (Python aliases `*ActorStep` in `graflo.rdf.namespace`)
+
+**Bindings block**
+
+- `gf:Bindings`, `gf:FileConnector`, `gf:TableConnector`, `gf:SparqlConnector`
+- `gf:ResourceConnectorBinding`, `gf:ConnectorConnectionBinding`, `gf:StagingProxyBinding`
+
+**Enumerations** (named individuals): `gf:DBType` (ArangoDB, Neo4j, …), transform target/strategy, key-selection mode, edge duplicate policy, bound source kind.
+
+**PROV-O hooks**: `gf:GraphManifest` ⊑ `prov:Entity`, `gf:ProtoTransform` ⊑ `prov:Activity` (subclasses such as `gf:Transform` inherit this; for lineage tooling).
+
+## Manifest instance URIs
+
+When you serialize a manifest, you pass a **`base_uri`** that identifies *that* manifest document (not the ontology). The serializer mints stable paths under it, for example:
+
+| Path under `base_uri` | RDF type |
+|-----------------------|----------|
+| `(base_uri)` | `gf:GraphManifest` |
+| `schema/` | `gf:Schema` |
+| `schema/core/vertex-config` | `gf:VertexConfig` |
+| `schema/core/edge-config` | `gf:EdgeConfig` |
+| `schema/core/vertex/Person` | `gf:Vertex` |
+| `schema/core/edge/Person_knows_Person` | `gf:Edge` |
+| `ingestion/` | `gf:IngestionModel` |
+| `ingestion/resource/my_resource` | `gf:Resource` |
+| `ingestion/transform/my_transform` | `gf:ProtoTransform` |
+| `bindings/` | `gf:Bindings` |
+| `bindings/connector/` | `gf:FileConnector` / `TableConnector` / `SparqlConnector` |
+
+Pipeline steps are **blank nodes** typed with the appropriate `gf:*Actor` class (and `gf:Actor`); the full step dict is stored in `gf:stepPayload` as JSON so round-trip preserves shorthand YAML shapes (`vertex: person`, nested `descend`, `transform.call`, …).
+
+List order (resources, transforms, connectors, vertices, fields, pipeline steps) is preserved via `gf:artifactIndex`.
+
+## Python API
+
+```python
+from graflo import GraphManifest
+from graflo.rdf import ManifestRdfDeserializer, ManifestRdfSerializer
+
+manifest = GraphManifest.from_yaml("manifest.yaml")
+base = "https://growgraph.dev/manifests/academic/v1"
+
+serializer = ManifestRdfSerializer(include_ontology=True)
+ttl = serializer.to_turtle(manifest, base)
+
+restored = ManifestRdfDeserializer().from_turtle(
+ ttl,
+ manifest_uri=base.rstrip("/"),
+)
+```
+
+- **`include_ontology=True`** (default) embeds `graflo.ttl` triples in the output graph — useful for self-contained Turtle files.
+- **`to_json_ld`**, **`to_graph`** — same graph, other serializations.
+
+## CLI
+
+After `pip install graflo` (or `uv sync` in the repo):
+
+```bash
+# Manifest → RDF
+uv run manifest-to-rdf manifest.yaml \
+ --base-uri https://growgraph.dev/manifests/academic/v1 \
+ --format turtle \
+ --output academic.ttl
+
+# RDF → manifest YAML
+uv run rdf-to-manifest academic.ttl \
+ --manifest-uri https://growgraph.dev/manifests/academic/v1 \
+ --output manifest.restored.yaml
+```
+
+Formats: `turtle` (default), `json-ld`, `nt`, `xml`.
+
+## Round-trip fidelity
+
+| Area | Behavior |
+|------|----------|
+| Scalars, enums, transforms | Full via literals and `gf` individuals |
+| `pipeline` actor steps | Full via `gf:stepPayload` JSON |
+| `params`, connector extras | JSON literals on payload properties |
+| YAML aliases (`schema` / `graph`, `pipeline` / `apply`) | Canonical names only in restored YAML |
+| Runtime `PrivateAttr` state | Not serialized; call `finish_init()` after load |
+| Vertex `filters` | Serialized in `gf:vertexPayload` JSON; not decomposed into filter AST |
+
+The guaranteed invariant matches the rest of GraFlo config: **semantic canonical round-trip** (`parse → RDF → parse` equals minimal canonical dict), not byte-identical YAML.
+
+## JSON-LD
+
+`graflo/rdf/ontology/graflo-context.jsonld` maps common JSON keys to `gf:` IRIs for tools that consume JSON-LD directly. The serializer’s `to_json_ld()` output can be combined with this context in downstream pipelines.
+
+## Related
+
+- [Example 6 — RDF / Turtle ingestion](../examples/example-6.md) — **domain** OWL → GraFlo manifest (`RdfInferenceManager`)
+- [API — `graflo.rdf`](../reference/rdf/index.md)
+- [API — `RdfInferenceManager`](../reference/hq/rdf_inferencer.md)
diff --git a/docs/reference/index.md b/docs/reference/index.md
index a99a405c..7b70b126 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -44,6 +44,13 @@ Database connection and management components:
- [Resource Mapping](db/postgres/resource_mapping.md): Mapping PostgreSQL tables to graflo Resources
- [Type Mapping](db/postgres/types.md): PostgreSQL to graflo type conversion
+## RDF
+
+Manifest serialization and domain ontology inference:
+
+- **[Manifest ↔ RDF (`graflo.rdf`)](rdf/index.md)**: `ManifestRdfSerializer`, `ManifestRdfDeserializer`, GraFlo meta-ontology
+- **[RDF inference (`RdfInferenceManager`)](hq/rdf_inferencer.md)**: User OWL/RDFS TBox → GraFlo `Schema` + ingestion
+
## Core Components
Main graflo functionality:
@@ -79,6 +86,7 @@ Graph visualization and plotting:
CLI tools for graflo operations:
- **[Ingest](cli/ingest.md)**: Data ingestion commands
+- **Manifest ↔ RDF**: `manifest-to-rdf`, `rdf-to-manifest` (see [GraFlo ontology](../model/graflo_ontology.md#cli))
- **[Database Management](cli/manage_dbs.md)**: Database administration commands
- **[Schema Visualization](cli/plot_manifest.md)**: Schema visualization commands
- **[XML to JSON](cli/xml2json.md)**: XML data conversion utilities
diff --git a/docs/reference/rdf/index.md b/docs/reference/rdf/index.md
new file mode 100644
index 00000000..a75b67d3
--- /dev/null
+++ b/docs/reference/rdf/index.md
@@ -0,0 +1,34 @@
+# `graflo.rdf` — manifest ↔ RDF bridge
+
+Bidirectional conversion between **`GraphManifest`** and RDF using the [GraFlo meta-ontology](../../model/graflo_ontology.md).
+
+## Modules
+
+::: graflo.rdf
+
+## Serializer
+
+::: graflo.rdf.serializer.ManifestRdfSerializer
+
+## Deserializer
+
+::: graflo.rdf.deserializer.ManifestRdfDeserializer
+
+## Namespace constants
+
+::: graflo.rdf.namespace
+
+## Utilities
+
+::: graflo.rdf.utils
+
+## CLI
+
+Console entry points (see `pyproject.toml` → `[project.scripts]`):
+
+- **`manifest-to-rdf`** — `graflo.rdf.cli:manifest_to_rdf`
+- **`rdf-to-manifest`** — `graflo.rdf.cli:rdf_to_manifest`
+
+## See also
+
+- [`graflo.hq.rdf_inferencer`](../hq/rdf_inferencer.md) — import **user** OWL/RDFS ontologies into a GraFlo schema (opposite direction of concern)
diff --git a/docs/scripts/build_ontology_viz.py b/docs/scripts/build_ontology_viz.py
new file mode 100644
index 00000000..ff7bef15
--- /dev/null
+++ b/docs/scripts/build_ontology_viz.py
@@ -0,0 +1,83 @@
+#!/usr/bin/env python
+"""Generate interactive HTML visualization for the GraFlo OWL ontology."""
+
+from __future__ import annotations
+
+import importlib.util
+import shutil
+import sys
+from pathlib import Path
+
+from graflo.rdf.namespace import GF_ONTOLOGY_IRI, GF_VERSION
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+OUTPUT_DIR = REPO_ROOT / "docs" / "assets" / "graflo-ontology-viz"
+VIZ_DIR = Path(__file__).resolve().parent / "ontology_viz"
+
+ASSET_FILES = (
+ "graph-view.css",
+ "graph-view.js",
+)
+
+
+def _load_extract_module():
+ spec = importlib.util.spec_from_file_location(
+ "graflo_ontology_viz_extract",
+ VIZ_DIR / "extract.py",
+ )
+ if spec is None or spec.loader is None:
+ msg = "Could not load ontology graph extractor"
+ raise RuntimeError(msg)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def _render_template(template_name: str, *, title: str, graph_json: str) -> str:
+ extract = _load_extract_module()
+ template = (VIZ_DIR / template_name).read_text(encoding="utf-8")
+ return template.replace("{{TITLE}}", title).replace(
+ "{{GRAPH_JSON}}", extract.escape_json_for_html(graph_json)
+ )
+
+
+def build_ontology_viz(*, output_dir: Path = OUTPUT_DIR) -> str:
+ """Build ontology visualization HTML. Returns the viz kind identifier."""
+ extract = _load_extract_module()
+ graph_data = extract.extract_ontology_graph()
+ graph_json = extract.graph_to_json(graph_data)
+ title = f"GraFlo Ontology (v{GF_VERSION})"
+
+ if output_dir.exists():
+ shutil.rmtree(output_dir)
+ output_dir.mkdir(parents=True)
+
+ for name in ASSET_FILES:
+ shutil.copy2(VIZ_DIR / name, output_dir / name)
+
+ (output_dir / "graph-data.json").write_text(graph_json + "\n", encoding="utf-8")
+ (output_dir / "index.html").write_text(
+ _render_template("page.template.html", title=title, graph_json=graph_json),
+ encoding="utf-8",
+ )
+ (output_dir / "embed.html").write_text(
+ _render_template("embed.template.html", title=title, graph_json=graph_json),
+ encoding="utf-8",
+ )
+ return "hierarchical-graph"
+
+
+def main() -> int:
+ try:
+ viz_id = build_ontology_viz()
+ except Exception as exc: # noqa: BLE001 — CLI entrypoint
+ print(f"error: {exc}", file=sys.stderr)
+ return 1
+
+ print(f"Built {OUTPUT_DIR} using GraFlo viz '{viz_id}'")
+ print(f"Ontology: {GF_ONTOLOGY_IRI} (v{GF_VERSION})")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/docs/scripts/ontology_viz/embed.template.html b/docs/scripts/ontology_viz/embed.template.html
new file mode 100644
index 00000000..028a929f
--- /dev/null
+++ b/docs/scripts/ontology_viz/embed.template.html
@@ -0,0 +1,28 @@
+
+
+
+ {{TITLE}}
+
+
+
+
+ All
+ Taxonomy
+ has*
+
+ Fit
+ Reset
+
+ Drag · scroll zoom · click class
+
+
Select a class to inspect its IRI and description.
";
+ return;
+ }
+ const node = nodeById.get(state.selectedId);
+ if (!node) {
+ return;
+ }
+ const props = data.edges.filter(function (edge) {
+ return edge.kind !== "subClassOf" && (edge.source === node.id || edge.target === node.id);
+ });
+ const subclasses = data.edges
+ .filter(function (edge) {
+ return edge.kind === "subClassOf" && edge.target === node.id;
+ })
+ .map(function (edge) {
+ return nodeById.get(edge.source);
+ })
+ .filter(Boolean);
+ const parents = data.edges
+ .filter(function (edge) {
+ return edge.kind === "subClassOf" && edge.source === node.id;
+ })
+ .map(function (edge) {
+ return nodeById.get(edge.target);
+ })
+ .filter(Boolean);
+
+ let html = "" + node.label + " ";
+ html += "" + node.id + "
";
+ if (node.comment) {
+ html += "";
+ }
+ if (node.layoutGroup === "isolated") {
+ html += "Layout: standalone class (no subClassOf links)
";
+ }
+ if (parents.length) {
+ html += "Parents: " + parents.map(function (p) {
+ return p.local;
+ }).join(", ") + "
";
+ }
+ if (subclasses.length) {
+ html += "Subclasses: " + subclasses.map(function (p) {
+ return p.local;
+ }).join(", ") + "
";
+ }
+ if (props.length) {
+ html += "Properties:
";
+ props.slice(0, 12).forEach(function (edge) {
+ html += "" + edge.label + "… +" + (props.length - 12) + " more ";
+ }
+ html += " ";
+ }
+ panel.innerHTML = html;
+ }
+
+ function nodeFromEventTarget(target) {
+ const group = target.closest ? target.closest(".node") : null;
+ if (!group) {
+ return null;
+ }
+ const nodeId = group.dataset.nodeId;
+ return nodeById.get(nodeId) || null;
+ }
+
+ function bindControls() {
+ const search = document.getElementById("search");
+ const relationFilter = document.getElementById("relation-filter");
+ if (search) {
+ search.addEventListener("input", function (event) {
+ state.search = event.target.value.trim();
+ applyHighlight();
+ });
+ }
+ if (relationFilter) {
+ relationFilter.addEventListener("change", function (event) {
+ state.relationMode = event.target.value;
+ renderEdges();
+ applyHighlight();
+ });
+ }
+
+ document.getElementById("fit-button").addEventListener("click", fitToScreen);
+ document.getElementById("reset-button").addEventListener("click", function () {
+ state.selectedId = null;
+ state.search = "";
+ if (search) {
+ search.value = "";
+ }
+ if (relationFilter) {
+ relationFilter.value = "all";
+ }
+ state.relationMode = "all";
+ updateDetails();
+ renderEdges();
+ applyHighlight();
+ fitToScreen();
+ });
+
+ svg.addEventListener("wheel", function (event) {
+ event.preventDefault();
+ const delta = event.deltaY > 0 ? 0.92 : 1.08;
+ const rect = svg.getBoundingClientRect();
+ const px = event.clientX - rect.left;
+ const py = event.clientY - rect.top;
+ state.tx = px - (px - state.tx) * delta;
+ state.ty = py - (py - state.ty) * delta;
+ state.scale *= delta;
+ applyTransform();
+ }, { passive: false });
+
+ svg.addEventListener("mousedown", function (event) {
+ state.dragMoved = false;
+ state.pointerDownX = event.clientX;
+ state.pointerDownY = event.clientY;
+ const node = nodeFromEventTarget(event.target);
+ state.lastX = event.clientX;
+ state.lastY = event.clientY;
+ if (node) {
+ state.draggingNodeId = node.id;
+ svg.classList.add("dragging-node");
+ return;
+ }
+ state.draggingViewport = true;
+ svg.classList.add("dragging");
+ });
+
+ window.addEventListener("mouseup", function (event) {
+ const pendingNodeId = state.draggingNodeId;
+ const draggedNode = pendingNodeId ? nodeById.get(pendingNodeId) : null;
+ if (draggedNode && state.dragMoved) {
+ resolveOverlaps(data.nodes);
+ reRenderGraph();
+ } else if (pendingNodeId && !state.dragMoved) {
+ selectNode(pendingNodeId);
+ }
+ state.draggingNodeId = null;
+ state.draggingViewport = false;
+ svg.classList.remove("dragging");
+ svg.classList.remove("dragging-node");
+ });
+
+ window.addEventListener("mousemove", function (event) {
+ markDragIfNeeded(event);
+ const dx = event.clientX - state.lastX;
+ const dy = event.clientY - state.lastY;
+ state.lastX = event.clientX;
+ state.lastY = event.clientY;
+
+ if (state.draggingNodeId) {
+ if (!state.dragMoved) {
+ return;
+ }
+ const node = nodeById.get(state.draggingNodeId);
+ if (!node) {
+ return;
+ }
+ node.x += dx / state.scale;
+ node.y += dy / state.scale;
+ reRenderGraph();
+ return;
+ }
+
+ if (!state.draggingViewport) {
+ return;
+ }
+ markDragIfNeeded(event);
+ state.tx += dx;
+ state.ty += dy;
+ applyTransform();
+ });
+
+ svg.addEventListener("click", function (event) {
+ const wasDrag = state.dragMoved;
+ state.dragMoved = false;
+ if (wasDrag) {
+ return;
+ }
+ if (nodeFromEventTarget(event.target)) {
+ return;
+ }
+ if (state.selectedId) {
+ state.selectedId = null;
+ updateDetails();
+ applyHighlight();
+ }
+ });
+ }
+
+ computeLayout();
+ reRenderGraph();
+ bindControls();
+ updateDetails();
+ fitToScreen();
+ window.addEventListener("resize", fitToScreen);
+})();
diff --git a/docs/scripts/ontology_viz/page.template.html b/docs/scripts/ontology_viz/page.template.html
new file mode 100644
index 00000000..29769066
--- /dev/null
+++ b/docs/scripts/ontology_viz/page.template.html
@@ -0,0 +1,51 @@
+
+
+
+ {{TITLE}}
+
+
+
+ Drag · scroll zoom · click class
+
+
.
+@prefix rdf: .
+@prefix rdfs: .
+@prefix skos: .
+@prefix xsd: .
+@prefix prov: .
+
+ a owl:Ontology ;
+ owl:versionIRI ;
+ owl:versionInfo "1.0.0" ;
+ rdfs:label "GraFlo Ontology"@en ;
+ skos:prefLabel "GraFlo Ontology"@en ;
+ rdfs:comment "OWL vocabulary describing GraFlo GraphManifest contracts: schema, ingestion, bindings, transforms, and pipeline actors."@en .
+
+#################################################################
+# Classes
+#################################################################
+
+gf:GrafloArtifact a owl:Class ;
+ rdfs:label "GraFlo artifact"@en ;
+ skos:prefLabel "Artifact"@en .
+
+gf:GraphManifest a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact , prov:Entity ;
+ rdfs:label "Graph manifest"@en ;
+ skos:prefLabel "GraphManifest"@en .
+
+gf:Schema a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Graph schema document"@en ;
+ skos:prefLabel "Schema"@en .
+
+gf:CoreSchema a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Core schema"@en ;
+ skos:prefLabel "CoreSchema"@en .
+
+gf:VertexConfig a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Vertex config"@en ;
+ skos:prefLabel "VertexConfig"@en ;
+ rdfs:comment "Manifest-facing vertex_config block containing vertex declarations and identity policy."@en .
+
+gf:EdgeConfig a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Edge config"@en ;
+ skos:prefLabel "EdgeConfig"@en ;
+ rdfs:comment "Manifest-facing edge_config block containing edge declarations."@en .
+
+gf:GraphMetadata a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Graph metadata"@en ;
+ skos:prefLabel "Metadata"@en .
+
+gf:DatabaseProfile a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Database profile"@en ;
+ skos:prefLabel "DatabaseProfile"@en .
+
+gf:Vertex a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Vertex"@en ;
+ skos:prefLabel "Vertex"@en ;
+ rdfs:comment "Manifest-facing vertex item in vertex_config.vertices."@en .
+
+gf:Edge a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Edge"@en ;
+ skos:prefLabel "Edge"@en ;
+ rdfs:comment "Manifest-facing edge item in edge_config.edges."@en .
+
+gf:Field a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Field"@en ;
+ skos:prefLabel "Field"@en ;
+ rdfs:comment "Manifest-facing field item used in vertex.properties and edge.properties."@en .
+
+gf:Identity a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Identity field"@en ;
+ skos:prefLabel "Identity"@en ;
+ rdfs:comment "Manifest-facing identity element (string) promoted to a first-class ontology node for traceability."@en .
+
+gf:IngestionModel a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Ingestion model"@en ;
+ skos:prefLabel "IngestionModel"@en .
+
+gf:Resource a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Resource"@en ;
+ skos:prefLabel "Resource"@en .
+
+gf:EdgeInferSpec a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Edge inference selector"@en ;
+ skos:prefLabel "EdgeInferSpec"@en .
+
+gf:ProtoTransform a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact , prov:Activity ;
+ rdfs:label "Proto transform"@en ;
+ skos:prefLabel "ProtoTransform"@en .
+
+gf:Transform a owl:Class ;
+ rdfs:subClassOf gf:ProtoTransform ;
+ rdfs:label "Transform"@en ;
+ skos:prefLabel "Transform"@en .
+
+gf:DressConfig a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Dress configuration"@en ;
+ skos:prefLabel "DressConfig"@en .
+
+gf:KeySelectionConfig a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Key selection configuration"@en ;
+ skos:prefLabel "KeySelectionConfig"@en .
+
+gf:Actor a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Actor"@en ;
+ skos:prefLabel "Actor"@en .
+
+gf:VertexProducingActor a owl:Class ;
+ rdfs:subClassOf gf:Actor ;
+ rdfs:label "Vertex-producing actor"@en ;
+ skos:prefLabel "VertexProducingActor"@en .
+
+gf:VertexActor a owl:Class ;
+ rdfs:subClassOf gf:VertexProducingActor ;
+ rdfs:label "Vertex actor"@en ;
+ skos:prefLabel "VertexActor"@en ;
+ rdfs:comment "Manifest-facing actor name (vertex)."@en .
+
+gf:EdgeActor a owl:Class ;
+ rdfs:subClassOf gf:Actor ;
+ rdfs:label "Edge actor"@en ;
+ skos:prefLabel "EdgeActor"@en ;
+ rdfs:comment "Manifest-facing actor name (edge)."@en .
+
+gf:TransformActor a owl:Class ;
+ rdfs:subClassOf gf:Actor ;
+ rdfs:label "Transform actor"@en ;
+ skos:prefLabel "TransformActor"@en .
+
+gf:DescendActor a owl:Class ;
+ rdfs:subClassOf gf:Actor ;
+ rdfs:label "Descend actor"@en ;
+ skos:prefLabel "DescendActor"@en .
+
+gf:VertexRouterActor a owl:Class ;
+ rdfs:subClassOf gf:VertexProducingActor ;
+ rdfs:label "Vertex router actor"@en ;
+ skos:prefLabel "VertexRouterActor"@en .
+
+gf:Bindings a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Bindings"@en ;
+ skos:prefLabel "Bindings"@en .
+
+gf:BoundConnector a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Bound connector"@en ;
+ skos:prefLabel "BoundConnector"@en .
+
+gf:FileConnector a owl:Class ;
+ rdfs:subClassOf gf:BoundConnector ;
+ rdfs:label "File connector"@en ;
+ skos:prefLabel "FileConnector"@en .
+
+gf:TableConnector a owl:Class ;
+ rdfs:subClassOf gf:BoundConnector ;
+ rdfs:label "Table connector"@en ;
+ skos:prefLabel "TableConnector"@en .
+
+gf:SparqlConnector a owl:Class ;
+ rdfs:subClassOf gf:BoundConnector ;
+ rdfs:label "SPARQL connector"@en ;
+ skos:prefLabel "SparqlConnector"@en .
+
+gf:ResourceConnectorBinding a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Resource connector binding"@en ;
+ skos:prefLabel "ResourceConnectorBinding"@en .
+
+gf:ConnectorConnectionBinding a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Connector connection binding"@en ;
+ skos:prefLabel "ConnectorConnectionBinding"@en .
+
+gf:StagingProxyBinding a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Staging proxy binding"@en ;
+ skos:prefLabel "StagingProxyBinding"@en .
+
+gf:EdgePhysicalSpec a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Edge physical spec"@en ;
+ skos:prefLabel "EdgePhysicalSpec"@en .
+
+gf:Index a owl:Class ;
+ rdfs:subClassOf gf:GrafloArtifact ;
+ rdfs:label "Database index"@en ;
+ skos:prefLabel "Index"@en .
+
+gf:FieldType a owl:Class ;
+ rdfs:label "Field type enumeration"@en ;
+ skos:prefLabel "FieldType"@en .
+
+gf:DBType a owl:Class ;
+ rdfs:label "Database type enumeration"@en ;
+ skos:prefLabel "DBType"@en .
+
+gf:BoundSourceKind a owl:Class ;
+ rdfs:label "Bound source kind enumeration"@en ;
+ skos:prefLabel "BoundSourceKind"@en .
+
+gf:TransformTarget a owl:Class ;
+ rdfs:label "Transform target enumeration"@en ;
+ skos:prefLabel "TransformTarget"@en .
+
+gf:TransformStrategy a owl:Class ;
+ rdfs:label "Transform strategy enumeration"@en ;
+ skos:prefLabel "TransformStrategy"@en .
+
+gf:KeySelectionMode a owl:Class ;
+ rdfs:label "Key selection mode enumeration"@en ;
+ skos:prefLabel "KeySelectionMode"@en .
+
+gf:EdgeDuplicatePolicy a owl:Class ;
+ rdfs:label "Edge duplicate policy enumeration"@en ;
+ skos:prefLabel "EdgeDuplicatePolicy"@en .
+
+#################################################################
+# Object properties
+#################################################################
+
+gf:hasSchema a owl:ObjectProperty ;
+ rdfs:domain gf:GraphManifest ;
+ rdfs:range gf:Schema .
+
+gf:hasIngestionModel a owl:ObjectProperty ;
+ rdfs:domain gf:GraphManifest ;
+ rdfs:range gf:IngestionModel .
+
+gf:hasBindings a owl:ObjectProperty ;
+ rdfs:domain gf:GraphManifest ;
+ rdfs:range gf:Bindings .
+
+gf:hasCoreSchema a owl:ObjectProperty ;
+ rdfs:domain gf:Schema ;
+ rdfs:range gf:CoreSchema .
+
+gf:hasVertexConfig a owl:ObjectProperty ;
+ rdfs:domain gf:CoreSchema ;
+ rdfs:range gf:VertexConfig ;
+ rdfs:comment "Manifest path: core_schema.vertex_config."@en .
+
+gf:hasEdgeConfig a owl:ObjectProperty ;
+ rdfs:domain gf:CoreSchema ;
+ rdfs:range gf:EdgeConfig ;
+ rdfs:comment "Manifest path: core_schema.edge_config."@en .
+
+gf:hasMetadata a owl:ObjectProperty ;
+ rdfs:domain gf:Schema ;
+ rdfs:range gf:GraphMetadata .
+
+gf:hasDatabaseProfile a owl:ObjectProperty ;
+ rdfs:domain gf:Schema ;
+ rdfs:range gf:DatabaseProfile .
+
+gf:hasVertex a owl:ObjectProperty ;
+ rdfs:domain gf:VertexConfig ;
+ rdfs:range gf:Vertex ;
+ rdfs:comment "Manifest-facing edge from VertexConfig to Vertex items."@en .
+
+gf:hasEdge a owl:ObjectProperty ;
+ rdfs:domain gf:EdgeConfig ;
+ rdfs:range gf:Edge ;
+ rdfs:comment "Manifest-facing edge from EdgeConfig to Edge items."@en .
+
+gf:hasField a owl:ObjectProperty ;
+ rdfs:domain gf:Vertex , gf:Edge ;
+ rdfs:range gf:Field .
+
+gf:hasIdentity a owl:ObjectProperty ;
+ rdfs:domain gf:Vertex , gf:Edge ;
+ rdfs:range gf:Identity ;
+ rdfs:comment "Manifest-facing identity chain node for vertex and edge identities."@en .
+
+gf:edgeSource a owl:ObjectProperty ;
+ rdfs:domain gf:Edge ;
+ rdfs:range gf:Vertex .
+
+gf:edgeTarget a owl:ObjectProperty ;
+ rdfs:domain gf:Edge ;
+ rdfs:range gf:Vertex .
+
+gf:hasResource a owl:ObjectProperty ;
+ rdfs:domain gf:IngestionModel ;
+ rdfs:range gf:Resource .
+
+gf:hasTransform a owl:ObjectProperty ;
+ rdfs:domain gf:IngestionModel ;
+ rdfs:range gf:ProtoTransform .
+
+gf:hasActor a owl:ObjectProperty ;
+ rdfs:domain gf:Resource , gf:DescendActor ;
+ rdfs:range gf:Actor .
+
+gf:targetsVertex a owl:ObjectProperty ;
+ rdfs:domain gf:VertexProducingActor ;
+ rdfs:range gf:Vertex ;
+ rdfs:comment "Vertex type(s) this actor produces observations for."@en .
+
+gf:targetsEdge a owl:ObjectProperty ;
+ rdfs:domain gf:EdgeActor ;
+ rdfs:range gf:Edge ;
+ rdfs:comment "Edge type(s) this actor may produce."@en .
+
+gf:executesTransform a owl:ObjectProperty ;
+ rdfs:domain gf:TransformActor ;
+ rdfs:range gf:ProtoTransform ;
+ rdfs:comment "Connects a transform actor step to the declared transform definition it executes."@en .
+
+gf:hasDress a owl:ObjectProperty ;
+ rdfs:domain gf:ProtoTransform ;
+ rdfs:range gf:DressConfig .
+
+gf:hasKeySelection a owl:ObjectProperty ;
+ rdfs:domain gf:ProtoTransform ;
+ rdfs:range gf:KeySelectionConfig .
+
+gf:hasConnector a owl:ObjectProperty ;
+ rdfs:domain gf:Bindings ;
+ rdfs:range gf:BoundConnector .
+
+gf:bindsResourceToConnector a owl:ObjectProperty ;
+ rdfs:domain gf:Bindings ;
+ rdfs:range gf:ResourceConnectorBinding .
+
+gf:bindsConnectorToConnProxy a owl:ObjectProperty ;
+ rdfs:domain gf:Bindings ;
+ rdfs:range gf:ConnectorConnectionBinding .
+
+gf:hasStagingProxy a owl:ObjectProperty ;
+ rdfs:domain gf:Bindings ;
+ rdfs:range gf:StagingProxyBinding .
+
+gf:hasVertexIndex a owl:ObjectProperty ;
+ rdfs:domain gf:DatabaseProfile ;
+ rdfs:range gf:Index ;
+ rdfs:comment "Database profile secondary index attached to a logical vertex."@en .
+
+gf:hasEdgeSpec a owl:ObjectProperty ;
+ rdfs:domain gf:DatabaseProfile ;
+ rdfs:range gf:EdgePhysicalSpec ;
+ rdfs:comment "Database profile edge physical specification."@en .
+
+gf:refinesEdge a owl:ObjectProperty ;
+ rdfs:domain gf:EdgePhysicalSpec ;
+ rdfs:range gf:Edge ;
+ rdfs:comment "Logical Edge this physical spec is a DB-layer refinement of."@en .
+
+gf:hasIndex a owl:ObjectProperty ;
+ rdfs:domain gf:EdgePhysicalSpec ;
+ rdfs:range gf:Index ;
+ rdfs:comment "Secondary index attached to an edge physical specification."@en .
+
+gf:hasEdgeInferOnly a owl:ObjectProperty ;
+ rdfs:domain gf:Resource ;
+ rdfs:range gf:EdgeInferSpec .
+
+gf:hasEdgeInferExcept a owl:ObjectProperty ;
+ rdfs:domain gf:Resource ;
+ rdfs:range gf:EdgeInferSpec .
+
+#################################################################
+# Datatype properties
+#################################################################
+
+gf:name a owl:DatatypeProperty ;
+ rdfs:range xsd:string .
+
+gf:version a owl:DatatypeProperty ;
+ rdfs:range xsd:string .
+
+gf:description a owl:DatatypeProperty ;
+ rdfs:range xsd:string .
+
+gf:enumValue a owl:DatatypeProperty ;
+ rdfs:range xsd:string ;
+ rdfs:comment "Canonical string value for a named enumeration individual." .
+
+gf:fieldType a owl:ObjectProperty ;
+ rdfs:domain gf:Field ;
+ rdfs:range gf:FieldType .
+
+gf:dbFlavor a owl:ObjectProperty ;
+ rdfs:domain gf:DatabaseProfile ;
+ rdfs:range gf:DBType .
+
+gf:targetNamespace a owl:DatatypeProperty ;
+ rdfs:range xsd:string .
+
+gf:identityName a owl:DatatypeProperty ;
+ rdfs:domain gf:Identity ;
+ rdfs:range xsd:string ;
+ rdfs:comment "Identity token value as shown in manifest identity arrays."@en .
+
+gf:relation a owl:DatatypeProperty ;
+ rdfs:range xsd:string .
+
+gf:blank a owl:DatatypeProperty ;
+ rdfs:domain gf:Vertex ;
+ rdfs:range xsd:boolean .
+
+gf:edgesOnDuplicate a owl:ObjectProperty ;
+ rdfs:domain gf:IngestionModel ;
+ rdfs:range gf:EdgeDuplicatePolicy .
+
+gf:resourceName a owl:DatatypeProperty ;
+ rdfs:range xsd:string .
+
+gf:connectorName a owl:DatatypeProperty ;
+ rdfs:range xsd:string .
+
+gf:connProxy a owl:DatatypeProperty ;
+ rdfs:range xsd:string .
+
+gf:actorType a owl:DatatypeProperty ;
+ rdfs:domain gf:Actor ;
+ rdfs:range xsd:string .
+
+gf:stepIndex a owl:DatatypeProperty ;
+ rdfs:domain gf:Actor ;
+ rdfs:range xsd:integer .
+
+gf:stepPayload a owl:DatatypeProperty ;
+ rdfs:domain gf:Actor ;
+ rdfs:range xsd:string ;
+ rdfs:comment "JSON-encoded pipeline step dict for lossless round-trip." .
+
+gf:transformModule a owl:DatatypeProperty ;
+ rdfs:domain gf:ProtoTransform ;
+ rdfs:range xsd:string .
+
+gf:transformFunction a owl:DatatypeProperty ;
+ rdfs:domain gf:ProtoTransform ;
+ rdfs:range xsd:string .
+
+gf:transformInput a owl:DatatypeProperty ;
+ rdfs:domain gf:ProtoTransform ;
+ rdfs:range xsd:string .
+
+gf:transformOutput a owl:DatatypeProperty ;
+ rdfs:domain gf:ProtoTransform ;
+ rdfs:range xsd:string .
+
+gf:transformParams a owl:DatatypeProperty ;
+ rdfs:domain gf:ProtoTransform ;
+ rdfs:range xsd:string ;
+ rdfs:comment "JSON-encoded transform params dict." .
+
+gf:transformTarget a owl:ObjectProperty ;
+ rdfs:domain gf:ProtoTransform ;
+ rdfs:range gf:TransformTarget .
+
+gf:transformStrategy a owl:ObjectProperty ;
+ rdfs:domain gf:Transform ;
+ rdfs:range gf:TransformStrategy .
+
+gf:renameMap a owl:DatatypeProperty ;
+ rdfs:domain gf:Transform ;
+ rdfs:range xsd:string ;
+ rdfs:comment "JSON-encoded rename dict." .
+
+gf:dressKey a owl:DatatypeProperty ;
+ rdfs:domain gf:DressConfig ;
+ rdfs:range xsd:string .
+
+gf:dressValue a owl:DatatypeProperty ;
+ rdfs:domain gf:DressConfig ;
+ rdfs:range xsd:string .
+
+gf:keySelectionMode a owl:ObjectProperty ;
+ rdfs:domain gf:KeySelectionConfig ;
+ rdfs:range gf:KeySelectionMode .
+
+gf:keySelectionName a owl:DatatypeProperty ;
+ rdfs:domain gf:KeySelectionConfig ;
+ rdfs:range xsd:string .
+
+gf:boundSourceKind a owl:ObjectProperty ;
+ rdfs:domain gf:BoundConnector ;
+ rdfs:range gf:BoundSourceKind .
+
+gf:connectorPayload a owl:DatatypeProperty ;
+ rdfs:domain gf:BoundConnector ;
+ rdfs:range xsd:string ;
+ rdfs:comment "JSON-encoded connector configuration excluding hash." .
+
+gf:resourcePayload a owl:DatatypeProperty ;
+ rdfs:domain gf:Resource ;
+ rdfs:range xsd:string ;
+ rdfs:comment "JSON-encoded resource scalar/list fields excluding pipeline and name." .
+
+gf:profilePayload a owl:DatatypeProperty ;
+ rdfs:domain gf:DatabaseProfile ;
+ rdfs:range xsd:string ;
+ rdfs:comment "JSON-encoded database profile extension fields." .
+
+gf:edgePayload a owl:DatatypeProperty ;
+ rdfs:domain gf:Edge ;
+ rdfs:range xsd:string ;
+ rdfs:comment "JSON-encoded edge extension fields (identities, type, by, etc.)." .
+
+gf:vertexPayload a owl:DatatypeProperty ;
+ rdfs:domain gf:Vertex ;
+ rdfs:range xsd:string ;
+ rdfs:comment "JSON-encoded vertex extension fields (filters, etc.)." .
+
+gf:artifactIndex a owl:DatatypeProperty ;
+ rdfs:range xsd:integer ;
+ rdfs:comment "Stable ordering index for list-valued manifest children." .
+
+gf:edgeIdentities a owl:DatatypeProperty ;
+ rdfs:domain gf:Edge ;
+ rdfs:range xsd:string ;
+ rdfs:comment "JSON-encoded edge identity token groups from edge.identities." .
+
+gf:edgeType a owl:DatatypeProperty ;
+ rdfs:domain gf:Edge ;
+ rdfs:range xsd:string ;
+ rdfs:comment "Edge materialization mode such as direct or indirect." .
+
+gf:edgeBy a owl:DatatypeProperty ;
+ rdfs:domain gf:Edge ;
+ rdfs:range xsd:string ;
+ rdfs:comment "For indirect edges, the vertex type that defines the edge." .
+
+gf:profileVertexName a owl:DatatypeProperty ;
+ rdfs:domain gf:Index ;
+ rdfs:range xsd:string ;
+ rdfs:comment "Logical vertex name this database profile index belongs to." .
+
+gf:indexName a owl:DatatypeProperty ;
+ rdfs:domain gf:Index ;
+ rdfs:range xsd:string .
+
+gf:indexField a owl:DatatypeProperty ;
+ rdfs:domain gf:Index ;
+ rdfs:range xsd:string ;
+ rdfs:comment "Ordered field list for this index; one triple per field." .
+
+gf:indexUnique a owl:DatatypeProperty ;
+ rdfs:domain gf:Index ;
+ rdfs:range xsd:boolean .
+
+gf:indexType a owl:DatatypeProperty ;
+ rdfs:domain gf:Index ;
+ rdfs:range xsd:string .
+
+gf:indexDeduplicate a owl:DatatypeProperty ;
+ rdfs:domain gf:Index ;
+ rdfs:range xsd:boolean .
+
+gf:indexSparse a owl:DatatypeProperty ;
+ rdfs:domain gf:Index ;
+ rdfs:range xsd:boolean .
+
+gf:indexExcludeEdgeEndpoints a owl:DatatypeProperty ;
+ rdfs:domain gf:Index ;
+ rdfs:range xsd:boolean .
+
+gf:specSource a owl:DatatypeProperty ;
+ rdfs:domain gf:EdgePhysicalSpec ;
+ rdfs:range xsd:string .
+
+gf:specTarget a owl:DatatypeProperty ;
+ rdfs:domain gf:EdgePhysicalSpec ;
+ rdfs:range xsd:string .
+
+gf:specRelation a owl:DatatypeProperty ;
+ rdfs:domain gf:EdgePhysicalSpec ;
+ rdfs:range xsd:string .
+
+gf:specPurpose a owl:DatatypeProperty ;
+ rdfs:domain gf:EdgePhysicalSpec ;
+ rdfs:range xsd:string .
+
+gf:specRelationName a owl:DatatypeProperty ;
+ rdfs:domain gf:EdgePhysicalSpec ;
+ rdfs:range xsd:string .
+
+gf:specIndexesMode a owl:DatatypeProperty ;
+ rdfs:domain gf:EdgePhysicalSpec ;
+ rdfs:range xsd:string .
+
+gf:forceTypes a owl:DatatypeProperty ;
+ rdfs:domain gf:VertexConfig ;
+ rdfs:range xsd:string ;
+ rdfs:comment "JSON-encoded mapping of vertex names to forced inferred types." .
+
+gf:identityFromAllProperties a owl:DatatypeProperty ;
+ rdfs:domain gf:VertexConfig ;
+ rdfs:range xsd:boolean ;
+ rdfs:comment "Whether vertices without explicit identity default to all property names." .
+
+gf:vertexIndexes a owl:DatatypeProperty ;
+ rdfs:domain gf:DatabaseProfile ;
+ rdfs:range xsd:string ;
+ rdfs:comment "Legacy JSON-encoded database profile vertex indexes (superseded by gf:hasVertexIndex)." .
+
+gf:edgeSpecs a owl:DatatypeProperty ;
+ rdfs:domain gf:DatabaseProfile ;
+ rdfs:range xsd:string ;
+ rdfs:comment "Legacy JSON-encoded database profile edge specs (superseded by gf:hasEdgeSpec)." .
+
+#################################################################
+# FieldType individuals
+#################################################################
+
+gf:INT a gf:FieldType ; gf:enumValue "INT" ; rdfs:label "INT" ; skos:prefLabel "INT" .
+gf:UINT a gf:FieldType ; gf:enumValue "UINT" ; rdfs:label "UINT" ; skos:prefLabel "UINT" .
+gf:FLOAT a gf:FieldType ; gf:enumValue "FLOAT" ; rdfs:label "FLOAT" ; skos:prefLabel "FLOAT" .
+gf:DOUBLE a gf:FieldType ; gf:enumValue "DOUBLE" ; rdfs:label "DOUBLE" ; skos:prefLabel "DOUBLE" .
+gf:BOOL a gf:FieldType ; gf:enumValue "BOOL" ; rdfs:label "BOOL" ; skos:prefLabel "BOOL" .
+gf:STRING a gf:FieldType ; gf:enumValue "STRING" ; rdfs:label "STRING" ; skos:prefLabel "STRING" .
+gf:DATETIME a gf:FieldType ; gf:enumValue "DATETIME" ; rdfs:label "DATETIME" ; skos:prefLabel "DATETIME" .
+
+#################################################################
+# DBType individuals
+#################################################################
+
+gf:ArangoDB a gf:DBType ; gf:enumValue "arango" ; rdfs:label "ArangoDB" ; skos:prefLabel "ArangoDB" .
+gf:Neo4j a gf:DBType ; gf:enumValue "neo4j" ; rdfs:label "Neo4j" ; skos:prefLabel "Neo4j" .
+gf:TigerGraph a gf:DBType ; gf:enumValue "tigergraph" ; rdfs:label "TigerGraph" ; skos:prefLabel "TigerGraph" .
+gf:FalkorDB a gf:DBType ; gf:enumValue "falkordb" ; rdfs:label "FalkorDB" ; skos:prefLabel "FalkorDB" .
+gf:Memgraph a gf:DBType ; gf:enumValue "memgraph" ; rdfs:label "Memgraph" ; skos:prefLabel "Memgraph" .
+gf:Nebula a gf:DBType ; gf:enumValue "nebula" ; rdfs:label "Nebula" ; skos:prefLabel "Nebula" .
+gf:Postgres a gf:DBType ; gf:enumValue "postgres" ; rdfs:label "Postgres" ; skos:prefLabel "Postgres" .
+gf:MySQL a gf:DBType ; gf:enumValue "mysql" ; rdfs:label "MySQL" ; skos:prefLabel "MySQL" .
+gf:MongoDB a gf:DBType ; gf:enumValue "mongodb" ; rdfs:label "MongoDB" ; skos:prefLabel "MongoDB" .
+gf:SQLite a gf:DBType ; gf:enumValue "sqlite" ; rdfs:label "SQLite" ; skos:prefLabel "SQLite" .
+gf:SparqlEndpoint a gf:DBType ; gf:enumValue "sparql" ; rdfs:label "SPARQL endpoint" ; skos:prefLabel "SparqlEndpoint" .
+
+#################################################################
+# BoundSourceKind individuals
+#################################################################
+
+gf:FileSource a gf:BoundSourceKind ; gf:enumValue "file" ; rdfs:label "File source" ; skos:prefLabel "FileSource" .
+gf:SqlTableSource a gf:BoundSourceKind ; gf:enumValue "sql_table" ; rdfs:label "SQL table source" ; skos:prefLabel "SqlTableSource" .
+gf:SparqlSource a gf:BoundSourceKind ; gf:enumValue "sparql" ; rdfs:label "SPARQL source" ; skos:prefLabel "SparqlSource" .
+
+#################################################################
+# TransformTarget individuals
+#################################################################
+
+gf:ValuesTarget a gf:TransformTarget ; gf:enumValue "values" ; rdfs:label "Values target" ; skos:prefLabel "ValuesTarget" .
+gf:KeysTarget a gf:TransformTarget ; gf:enumValue "keys" ; rdfs:label "Keys target" ; skos:prefLabel "KeysTarget" .
+
+#################################################################
+# TransformStrategy individuals
+#################################################################
+
+gf:SingleStrategy a gf:TransformStrategy ; gf:enumValue "single" ; rdfs:label "Single strategy" ; skos:prefLabel "SingleStrategy" .
+gf:EachStrategy a gf:TransformStrategy ; gf:enumValue "each" ; rdfs:label "Each strategy" ; skos:prefLabel "EachStrategy" .
+gf:AllStrategy a gf:TransformStrategy ; gf:enumValue "all" ; rdfs:label "All strategy" ; skos:prefLabel "AllStrategy" .
+
+#################################################################
+# KeySelectionMode individuals
+#################################################################
+
+gf:AllKeysMode a gf:KeySelectionMode ; gf:enumValue "all" ; rdfs:label "All keys" ; skos:prefLabel "AllKeysMode" .
+gf:IncludeKeysMode a gf:KeySelectionMode ; gf:enumValue "include" ; rdfs:label "Include keys" ; skos:prefLabel "IncludeKeysMode" .
+gf:ExcludeKeysMode a gf:KeySelectionMode ; gf:enumValue "exclude" ; rdfs:label "Exclude keys" ; skos:prefLabel "ExcludeKeysMode" .
+
+#################################################################
+# EdgeDuplicatePolicy individuals
+#################################################################
+
+gf:IgnoreDuplicate a gf:EdgeDuplicatePolicy ; gf:enumValue "ignore" ; rdfs:label "Ignore duplicate" ; skos:prefLabel "IgnoreDuplicate" .
+gf:UpsertDuplicate a gf:EdgeDuplicatePolicy ; gf:enumValue "upsert" ; rdfs:label "Upsert duplicate" ; skos:prefLabel "UpsertDuplicate" .
diff --git a/graflo/rdf/serializer.py b/graflo/rdf/serializer.py
new file mode 100644
index 00000000..381def93
--- /dev/null
+++ b/graflo/rdf/serializer.py
@@ -0,0 +1,733 @@
+"""Serialize GraphManifest instances to RDF."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from rdflib import BNode, Graph, RDF, URIRef
+from rdflib.namespace import XSD
+
+from graflo.architecture.contract.bindings.connectors import (
+ FileConnector,
+ SparqlConnector,
+ TableConnector,
+)
+from graflo.architecture.contract.manifest import GraphManifest
+from graflo.architecture.contract.ingestion.transform import (
+ DressConfig,
+ KeySelectionConfig,
+ ProtoTransform,
+)
+from graflo.architecture.graph_types import EdgeId
+from graflo.architecture.schema.edge import Edge
+from graflo.architecture.schema.vertex import Field, Vertex
+from graflo.rdf import namespace as ns
+from graflo.rdf.utils import (
+ add_enum_individual,
+ add_literal,
+ actor_step_class,
+ actor_step_type,
+ join_uri,
+ json_literal,
+ load_ontology_graph,
+)
+
+
+class ManifestRdfSerializer:
+ """Convert a :class:`GraphManifest` into RDF using the GraFlo meta-ontology."""
+
+ def __init__(self, *, include_ontology: bool = True) -> None:
+ self._include_ontology = include_ontology
+
+ def to_graph(self, manifest: GraphManifest, base_uri: str) -> Graph:
+ """Serialize manifest to an rdflib graph."""
+ graph = Graph()
+ graph.bind("gf", ns.GF)
+ graph.bind("xsd", XSD)
+ if self._include_ontology:
+ graph += load_ontology_graph()
+
+ manifest_uri = URIRef(base_uri.rstrip("/"))
+ graph.add((manifest_uri, RDF.type, ns.GraphManifest))
+ vertex_uri_by_name: dict[str, URIRef] | None = None
+ edge_uri_by_id: dict[EdgeId, URIRef] | None = None
+
+ if manifest.graph_schema is not None:
+ schema_uri = URIRef(join_uri(base_uri, "schema"))
+ graph.add((manifest_uri, ns.hasSchema, schema_uri))
+ self._emit_schema(graph, schema_uri, manifest.graph_schema)
+ core_uri = URIRef(join_uri(str(schema_uri), "core"))
+ vertex_uri_by_name = {
+ vertex.name: URIRef(join_uri(str(core_uri), "vertex", vertex.name))
+ for vertex in manifest.graph_schema.core_schema.vertex_config.vertices
+ }
+ edge_uri_by_id = {
+ edge.edge_id: URIRef(
+ join_uri(str(core_uri), "edge", self._edge_key(edge))
+ )
+ for edge in manifest.graph_schema.core_schema.edge_config.edges
+ }
+
+ if manifest.ingestion_model is not None:
+ ingestion_uri = URIRef(join_uri(base_uri, "ingestion"))
+ graph.add((manifest_uri, ns.hasIngestionModel, ingestion_uri))
+ self._emit_ingestion_model(
+ graph,
+ base_uri,
+ ingestion_uri,
+ manifest.ingestion_model,
+ vertex_uri_by_name=vertex_uri_by_name,
+ edge_uri_by_id=edge_uri_by_id,
+ )
+
+ if manifest.bindings is not None:
+ bindings_uri = URIRef(join_uri(base_uri, "bindings"))
+ graph.add((manifest_uri, ns.hasBindings, bindings_uri))
+ self._emit_bindings(graph, base_uri, bindings_uri, manifest.bindings)
+
+ return graph
+
+ def to_turtle(self, manifest: GraphManifest, base_uri: str) -> str:
+ """Serialize manifest to Turtle."""
+ return self.to_graph(manifest, base_uri).serialize(format="turtle")
+
+ def to_json_ld(self, manifest: GraphManifest, base_uri: str) -> str:
+ """Serialize manifest to JSON-LD."""
+ return self.to_graph(manifest, base_uri).serialize(format="json-ld")
+
+ def _emit_schema(self, graph: Graph, schema_uri: URIRef, schema: Any) -> None:
+ graph.add((schema_uri, RDF.type, ns.Schema))
+
+ metadata_uri = URIRef(join_uri(str(schema_uri), "metadata"))
+ graph.add((schema_uri, ns.hasMetadata, metadata_uri))
+ graph.add((metadata_uri, RDF.type, ns.GraphMetadata))
+ add_literal(graph, metadata_uri, ns.name, schema.metadata.name)
+ add_literal(graph, metadata_uri, ns.version, schema.metadata.version)
+ add_literal(graph, metadata_uri, ns.description, schema.metadata.description)
+
+ core_uri = URIRef(join_uri(str(schema_uri), "core"))
+ graph.add((schema_uri, ns.hasCoreSchema, core_uri))
+ graph.add((core_uri, RDF.type, ns.CoreSchema))
+
+ vertex_config_uri = URIRef(join_uri(str(core_uri), "vertex-config"))
+ graph.add((core_uri, ns.hasVertexConfig, vertex_config_uri))
+ graph.add((vertex_config_uri, RDF.type, ns.VertexConfig))
+ self._emit_vertex_config(
+ graph, vertex_config_uri, schema.core_schema.vertex_config
+ )
+
+ edge_config_uri = URIRef(join_uri(str(core_uri), "edge-config"))
+ graph.add((core_uri, ns.hasEdgeConfig, edge_config_uri))
+ graph.add((edge_config_uri, RDF.type, ns.EdgeConfig))
+
+ vertex_uri_by_name: dict[str, URIRef] = {}
+ for index, vertex in enumerate(schema.core_schema.vertex_config.vertices):
+ vertex_uri = URIRef(join_uri(str(core_uri), "vertex", vertex.name))
+ vertex_uri_by_name[vertex.name] = vertex_uri
+ graph.add((vertex_config_uri, ns.hasVertex, vertex_uri))
+ add_literal(graph, vertex_uri, ns.artifactIndex, index)
+ self._emit_vertex(graph, vertex_uri, vertex)
+
+ edge_uri_by_id: dict[EdgeId, URIRef] = {}
+ for index, edge in enumerate(schema.core_schema.edge_config.edges):
+ edge_key = self._edge_key(edge)
+ edge_uri = URIRef(join_uri(str(core_uri), "edge", edge_key))
+ edge_uri_by_id[edge.edge_id] = edge_uri
+ graph.add((edge_config_uri, ns.hasEdge, edge_uri))
+ add_literal(graph, edge_uri, ns.artifactIndex, index)
+ self._emit_edge(graph, edge_uri, edge, vertex_uri_by_name)
+
+ profile_uri = URIRef(join_uri(str(schema_uri), "db-profile"))
+ graph.add((schema_uri, ns.hasDatabaseProfile, profile_uri))
+ self._emit_database_profile(
+ graph, profile_uri, schema.db_profile, edge_uri_by_id=edge_uri_by_id
+ )
+
+ def _emit_vertex_config(
+ self,
+ graph: Graph,
+ vertex_config_uri: URIRef,
+ vertex_config: Any,
+ ) -> None:
+ if vertex_config.force_types:
+ graph.add(
+ (
+ vertex_config_uri,
+ ns.forceTypes,
+ json_literal(vertex_config.force_types),
+ )
+ )
+ add_literal(
+ graph,
+ vertex_config_uri,
+ ns.identityFromAllProperties,
+ vertex_config.identity_from_all_properties,
+ )
+
+ def _emit_vertex(self, graph: Graph, vertex_uri: URIRef, vertex: Vertex) -> None:
+ graph.add((vertex_uri, RDF.type, ns.Vertex))
+ add_literal(graph, vertex_uri, ns.name, vertex.name)
+ add_literal(graph, vertex_uri, ns.description, vertex.description)
+ add_literal(graph, vertex_uri, ns.blank, vertex.blank)
+
+ for identity in vertex.identity:
+ identity_node = BNode()
+ graph.add((vertex_uri, ns.hasIdentity, identity_node))
+ graph.add((identity_node, RDF.type, ns.Identity))
+ add_literal(graph, identity_node, ns.identityName, identity)
+
+ payload = {}
+ if vertex.filters:
+ payload["filters"] = [
+ f.model_dump(mode="json", by_alias=True)
+ if hasattr(f, "model_dump")
+ else f
+ for f in vertex.filters
+ ]
+ if payload:
+ graph.add((vertex_uri, ns.vertexPayload, json_literal(payload)))
+
+ for index, field in enumerate(vertex.properties):
+ self._emit_field(graph, vertex_uri, field, index)
+
+ def _emit_field(
+ self,
+ graph: Graph,
+ owner_uri: URIRef,
+ field: Field | str,
+ index: int,
+ ) -> None:
+ if isinstance(field, str):
+ field_obj = Field(name=field)
+ else:
+ field_obj = field
+ field_uri = URIRef(join_uri(str(owner_uri), "field", field_obj.name))
+ graph.add((owner_uri, ns.hasField, field_uri))
+ graph.add((field_uri, RDF.type, ns.Field))
+ add_literal(graph, field_uri, ns.artifactIndex, index)
+ add_literal(graph, field_uri, ns.name, field_obj.name)
+ add_literal(graph, field_uri, ns.description, field_obj.description)
+ if field_obj.type is not None:
+ add_enum_individual(
+ graph,
+ field_uri,
+ ns.fieldType,
+ str(field_obj.type),
+ ns.ENUM_REGISTRIES["field_type"],
+ )
+
+ def _emit_edge(
+ self,
+ graph: Graph,
+ edge_uri: URIRef,
+ edge: Edge,
+ vertex_uri_by_name: dict[str, URIRef],
+ ) -> None:
+ graph.add((edge_uri, RDF.type, ns.Edge))
+ add_literal(graph, edge_uri, ns.relation, edge.relation)
+ add_literal(graph, edge_uri, ns.description, edge.description)
+
+ source_uri = vertex_uri_by_name.get(edge.source)
+ target_uri = vertex_uri_by_name.get(edge.target)
+ if source_uri is not None:
+ graph.add((edge_uri, ns.edgeSource, source_uri))
+ if target_uri is not None:
+ graph.add((edge_uri, ns.edgeTarget, target_uri))
+
+ payload: dict[str, Any] = {}
+ if edge.identities:
+ graph.add((edge_uri, ns.edgeIdentities, json_literal(edge.identities)))
+ if edge.type is not None:
+ add_literal(graph, edge_uri, ns.edgeType, str(edge.type))
+ if edge.by is not None:
+ add_literal(graph, edge_uri, ns.edgeBy, edge.by)
+ if payload:
+ graph.add((edge_uri, ns.edgePayload, json_literal(payload)))
+
+ for index, field in enumerate(edge.properties):
+ self._emit_field(graph, edge_uri, field, index)
+
+ def _emit_database_profile(
+ self,
+ graph: Graph,
+ profile_uri: URIRef,
+ profile: Any,
+ *,
+ edge_uri_by_id: dict[EdgeId, URIRef] | None = None,
+ ) -> None:
+ graph.add((profile_uri, RDF.type, ns.DatabaseProfile))
+ add_enum_individual(
+ graph,
+ profile_uri,
+ ns.dbFlavor,
+ str(profile.db_flavor),
+ ns.ENUM_REGISTRIES["db_type"],
+ )
+ add_literal(graph, profile_uri, ns.targetNamespace, profile.target_namespace)
+ self._emit_profile_indexes(
+ graph, profile_uri, profile, edge_uri_by_id=edge_uri_by_id
+ )
+
+ payload = self._model_payload(
+ profile, ns.MODEL_PAYLOAD_EXCLUDES["database_profile"]
+ )
+ if payload:
+ graph.add((profile_uri, ns.profilePayload, json_literal(payload)))
+
+ def _emit_profile_indexes(
+ self,
+ graph: Graph,
+ profile_uri: URIRef,
+ profile: Any,
+ *,
+ edge_uri_by_id: dict[EdgeId, URIRef] | None = None,
+ ) -> None:
+ for vertex_name, indexes in profile.vertex_indexes.items():
+ for index_position, index in enumerate(indexes):
+ index_uri = URIRef(
+ join_uri(
+ str(profile_uri),
+ "vertex-index",
+ vertex_name,
+ str(index_position),
+ )
+ )
+ graph.add((profile_uri, ns.hasVertexIndex, index_uri))
+ self._emit_index(
+ graph,
+ index_uri,
+ index,
+ vertex_name=vertex_name,
+ )
+
+ for spec_position, edge_spec in enumerate(profile.edge_specs):
+ spec_uri = URIRef(
+ join_uri(str(profile_uri), "edge-spec", str(spec_position))
+ )
+ graph.add((profile_uri, ns.hasEdgeSpec, spec_uri))
+ graph.add((spec_uri, RDF.type, ns.EdgePhysicalSpec))
+ add_literal(graph, spec_uri, ns.specSource, edge_spec.source)
+ add_literal(graph, spec_uri, ns.specTarget, edge_spec.target)
+ add_literal(graph, spec_uri, ns.specRelation, edge_spec.relation)
+ add_literal(graph, spec_uri, ns.specPurpose, edge_spec.purpose)
+ add_literal(graph, spec_uri, ns.specRelationName, edge_spec.relation_name)
+ add_literal(graph, spec_uri, ns.specIndexesMode, edge_spec.indexes_mode)
+ if edge_uri_by_id is not None:
+ edge_uri = edge_uri_by_id.get(
+ (edge_spec.source, edge_spec.target, edge_spec.relation)
+ )
+ if edge_uri is not None:
+ graph.add((spec_uri, ns.refinesEdge, edge_uri))
+
+ for index_position, index in enumerate(edge_spec.indexes):
+ index_uri = URIRef(
+ join_uri(str(spec_uri), "index", str(index_position))
+ )
+ graph.add((spec_uri, ns.hasIndex, index_uri))
+ self._emit_index(graph, index_uri, index)
+
+ def _emit_index(
+ self,
+ graph: Graph,
+ index_uri: URIRef,
+ index: Any,
+ *,
+ vertex_name: str | None = None,
+ ) -> None:
+ graph.add((index_uri, RDF.type, ns.Index))
+ add_literal(graph, index_uri, ns.profileVertexName, vertex_name)
+ add_literal(graph, index_uri, ns.indexName, index.name)
+ add_literal(graph, index_uri, ns.indexUnique, index.unique)
+ index_type = getattr(index.type, "value", str(index.type))
+ add_literal(graph, index_uri, ns.indexType, index_type)
+ add_literal(graph, index_uri, ns.indexDeduplicate, index.deduplicate)
+ add_literal(graph, index_uri, ns.indexSparse, index.sparse)
+ add_literal(
+ graph,
+ index_uri,
+ ns.indexExcludeEdgeEndpoints,
+ index.exclude_edge_endpoints,
+ )
+ for field in index.fields:
+ add_literal(graph, index_uri, ns.indexField, field)
+
+ def _emit_ingestion_model(
+ self,
+ graph: Graph,
+ base_uri: str,
+ ingestion_uri: URIRef,
+ ingestion_model: Any,
+ *,
+ vertex_uri_by_name: dict[str, URIRef] | None = None,
+ edge_uri_by_id: dict[EdgeId, URIRef] | None = None,
+ ) -> None:
+ graph.add((ingestion_uri, RDF.type, ns.IngestionModel))
+ add_enum_individual(
+ graph,
+ ingestion_uri,
+ ns.edgesOnDuplicate,
+ ingestion_model.edges_on_duplicate,
+ ns.ENUM_REGISTRIES["edge_duplicate_policy"],
+ )
+
+ transform_uri_by_name: dict[str, URIRef] = {}
+ for index, transform in enumerate(ingestion_model.transforms):
+ transform_uri = URIRef(
+ join_uri(
+ base_uri, "ingestion", "transform", transform.name or "unnamed"
+ )
+ )
+ if transform.name:
+ transform_uri_by_name[transform.name] = transform_uri
+ graph.add((ingestion_uri, ns.hasTransform, transform_uri))
+ add_literal(graph, transform_uri, ns.artifactIndex, index)
+ self._emit_proto_transform(graph, transform_uri, transform)
+
+ for index, resource in enumerate(ingestion_model.resources):
+ resource_uri = URIRef(
+ join_uri(base_uri, "ingestion", "resource", resource.name)
+ )
+ graph.add((ingestion_uri, ns.hasResource, resource_uri))
+ add_literal(graph, resource_uri, ns.artifactIndex, index)
+ self._emit_resource(
+ graph,
+ resource_uri,
+ resource,
+ transform_uri_by_name=transform_uri_by_name,
+ vertex_uri_by_name=vertex_uri_by_name,
+ edge_uri_by_id=edge_uri_by_id,
+ )
+
+ def _emit_proto_transform(
+ self,
+ graph: Graph,
+ transform_uri: URIRef,
+ transform: ProtoTransform,
+ ) -> None:
+ graph.add((transform_uri, RDF.type, ns.ProtoTransform))
+ add_literal(graph, transform_uri, ns.name, transform.name)
+ add_literal(graph, transform_uri, ns.transformModule, transform.module)
+ add_literal(graph, transform_uri, ns.transformFunction, transform.foo)
+
+ for item in transform.input:
+ add_literal(graph, transform_uri, ns.transformInput, item)
+ for item in transform.output:
+ add_literal(graph, transform_uri, ns.transformOutput, item)
+
+ extra_payload: dict[str, Any] = {}
+ if transform.params:
+ extra_payload["params"] = transform.params
+ if transform.input_groups:
+ extra_payload["input_groups"] = [
+ list(group) for group in transform.input_groups
+ ]
+ if transform.output_groups:
+ extra_payload["output_groups"] = [
+ list(group) for group in transform.output_groups
+ ]
+ if extra_payload:
+ graph.add((transform_uri, ns.transformParams, json_literal(extra_payload)))
+
+ add_enum_individual(
+ graph,
+ transform_uri,
+ ns.transformTarget,
+ transform.target,
+ ns.ENUM_REGISTRIES["transform_target"],
+ )
+
+ if transform.dress is not None:
+ dress_uri = BNode()
+ graph.add((transform_uri, ns.hasDress, dress_uri))
+ self._emit_dress_config(graph, dress_uri, transform.dress)
+
+ if transform.keys.mode != "all" or transform.keys.names:
+ keys_uri = BNode()
+ graph.add((transform_uri, ns.hasKeySelection, keys_uri))
+ self._emit_key_selection(graph, keys_uri, transform.keys)
+
+ def _emit_dress_config(
+ self, graph: Graph, dress_uri: BNode, dress: DressConfig
+ ) -> None:
+ graph.add((dress_uri, RDF.type, ns.DressConfig))
+ add_literal(graph, dress_uri, ns.dressKey, dress.key)
+ add_literal(graph, dress_uri, ns.dressValue, dress.value)
+
+ def _emit_key_selection(
+ self,
+ graph: Graph,
+ keys_uri: BNode,
+ keys: KeySelectionConfig,
+ ) -> None:
+ graph.add((keys_uri, RDF.type, ns.KeySelectionConfig))
+ add_enum_individual(
+ graph,
+ keys_uri,
+ ns.keySelectionMode,
+ keys.mode,
+ ns.ENUM_REGISTRIES["key_selection_mode"],
+ )
+ for key_name in keys.names:
+ add_literal(graph, keys_uri, ns.keySelectionName, key_name)
+
+ def _emit_resource(
+ self,
+ graph: Graph,
+ resource_uri: URIRef,
+ resource: Any,
+ *,
+ transform_uri_by_name: dict[str, URIRef] | None = None,
+ vertex_uri_by_name: dict[str, URIRef] | None = None,
+ edge_uri_by_id: dict[EdgeId, URIRef] | None = None,
+ ) -> None:
+ graph.add((resource_uri, RDF.type, ns.Resource))
+ add_literal(graph, resource_uri, ns.name, resource.name)
+
+ payload = self._model_payload(resource, ns.MODEL_PAYLOAD_EXCLUDES["resource"])
+ if payload:
+ graph.add((resource_uri, ns.resourcePayload, json_literal(payload)))
+
+ for index, step in enumerate(resource.pipeline):
+ step_node = self._emit_actor_step(
+ graph,
+ step,
+ index=index,
+ transform_uri_by_name=transform_uri_by_name,
+ vertex_uri_by_name=vertex_uri_by_name,
+ edge_uri_by_id=edge_uri_by_id,
+ )
+ graph.add((resource_uri, ns.hasActor, step_node))
+
+ for spec in resource.infer_edge_only:
+ spec_uri = BNode()
+ graph.add((resource_uri, ns.hasEdgeInferOnly, spec_uri))
+ self._emit_edge_infer_spec(graph, spec_uri, spec)
+ for spec in resource.infer_edge_except:
+ spec_uri = BNode()
+ graph.add((resource_uri, ns.hasEdgeInferExcept, spec_uri))
+ self._emit_edge_infer_spec(graph, spec_uri, spec)
+
+ def _emit_edge_infer_spec(self, graph: Graph, spec_uri: BNode, spec: Any) -> None:
+ graph.add((spec_uri, RDF.type, ns.EdgeInferSpec))
+ graph.add(
+ (
+ spec_uri,
+ ns.stepPayload,
+ json_literal(
+ {
+ "source": spec.source,
+ "target": spec.target,
+ "relation": spec.relation,
+ }
+ ),
+ )
+ )
+
+ def _emit_actor_step(
+ self,
+ graph: Graph,
+ step: dict[str, Any],
+ *,
+ index: int,
+ transform_uri_by_name: dict[str, URIRef] | None = None,
+ vertex_uri_by_name: dict[str, URIRef] | None = None,
+ edge_uri_by_id: dict[EdgeId, URIRef] | None = None,
+ ) -> BNode:
+ step_node = BNode()
+ step_type = actor_step_type(step)
+ graph.add((step_node, RDF.type, URIRef(str(actor_step_class(step_type)))))
+ graph.add((step_node, RDF.type, ns.Actor))
+ add_literal(graph, step_node, ns.actorType, step_type)
+ add_literal(graph, step_node, ns.stepIndex, index)
+ graph.add((step_node, ns.stepPayload, json_literal(step)))
+ if step_type == "vertex":
+ vertex_name = step.get("vertex")
+ if (
+ isinstance(vertex_name, str)
+ and vertex_uri_by_name is not None
+ and vertex_name in vertex_uri_by_name
+ ):
+ graph.add(
+ (step_node, ns.targetsVertex, vertex_uri_by_name[vertex_name])
+ )
+ if step_type == "vertex_router" and vertex_uri_by_name is not None:
+ type_map = step.get("type_map")
+ if isinstance(type_map, dict):
+ for mapped in type_map.values():
+ if isinstance(mapped, str) and mapped in vertex_uri_by_name:
+ graph.add(
+ (step_node, ns.targetsVertex, vertex_uri_by_name[mapped])
+ )
+ if step_type == "edge" and edge_uri_by_id is not None:
+
+ def _link_edge(source: str, target: str, relation: str | None) -> None:
+ edge_uri = edge_uri_by_id.get((source, target, relation))
+ if edge_uri is not None:
+ graph.add((step_node, ns.targetsEdge, edge_uri))
+
+ source = step.get("from")
+ target = step.get("to")
+ relation = step.get("relation")
+ if isinstance(source, str) and isinstance(target, str):
+ _link_edge(
+ source, target, relation if isinstance(relation, str) else None
+ )
+ links = step.get("links")
+ if isinstance(links, list):
+ for link in links:
+ if not isinstance(link, dict):
+ continue
+ link_source = link.get("from")
+ link_target = link.get("to")
+ link_relation = link.get("relation")
+ if isinstance(link_source, str) and isinstance(link_target, str):
+ _link_edge(
+ link_source,
+ link_target,
+ link_relation if isinstance(link_relation, str) else None,
+ )
+ if step_type == "transform":
+ transform_name = step.get("name")
+ if not isinstance(transform_name, str):
+ call_spec = step.get("call")
+ if isinstance(call_spec, dict):
+ use_name = call_spec.get("use")
+ if isinstance(use_name, str):
+ transform_name = use_name
+ if not isinstance(transform_name, str):
+ transform_step = step.get("transform")
+ if isinstance(transform_step, dict):
+ direct_name = transform_step.get("name")
+ if isinstance(direct_name, str):
+ transform_name = direct_name
+ nested_call = transform_step.get("call")
+ if not isinstance(transform_name, str) and isinstance(
+ nested_call, dict
+ ):
+ nested_use = nested_call.get("use")
+ if isinstance(nested_use, str):
+ transform_name = nested_use
+ if isinstance(transform_name, str) and transform_uri_by_name is not None:
+ transform_uri = transform_uri_by_name.get(transform_name)
+ if transform_uri is not None:
+ graph.add((step_node, ns.executesTransform, transform_uri))
+
+ if step_type == "descend":
+ nested_steps = step.get("pipeline")
+ if isinstance(nested_steps, list):
+ for nested_index, nested_step in enumerate(nested_steps):
+ if isinstance(nested_step, dict):
+ nested_node = self._emit_actor_step(
+ graph,
+ cast(dict[str, Any], nested_step),
+ index=nested_index,
+ transform_uri_by_name=transform_uri_by_name,
+ vertex_uri_by_name=vertex_uri_by_name,
+ edge_uri_by_id=edge_uri_by_id,
+ )
+ graph.add((step_node, ns.hasActor, nested_node))
+ return step_node
+
+ def _emit_bindings(
+ self,
+ graph: Graph,
+ base_uri: str,
+ bindings_uri: URIRef,
+ bindings: Any,
+ ) -> None:
+ graph.add((bindings_uri, RDF.type, ns.Bindings))
+
+ for index, connector in enumerate(bindings.connectors):
+ connector_hash = connector.hash or connector.__class__.__name__
+ connector_uri = URIRef(
+ join_uri(base_uri, "bindings", "connector", connector_hash)
+ )
+ graph.add((bindings_uri, ns.hasConnector, connector_uri))
+ add_literal(graph, connector_uri, ns.artifactIndex, index)
+ self._emit_connector(graph, connector_uri, connector)
+
+ for mapping in bindings.resource_connector:
+ binding_uri = BNode()
+ graph.add((bindings_uri, ns.bindsResourceToConnector, binding_uri))
+ graph.add((binding_uri, RDF.type, ns.ResourceConnectorBinding))
+ resource = (
+ mapping.resource
+ if hasattr(mapping, "resource")
+ else mapping["resource"]
+ )
+ connector = (
+ mapping.connector
+ if hasattr(mapping, "connector")
+ else mapping["connector"]
+ )
+ add_literal(graph, binding_uri, ns.resourceName, resource)
+ add_literal(graph, binding_uri, ns.connectorName, connector)
+
+ for mapping in bindings.connector_connection:
+ binding_uri = BNode()
+ graph.add((bindings_uri, ns.bindsConnectorToConnProxy, binding_uri))
+ graph.add((binding_uri, RDF.type, ns.ConnectorConnectionBinding))
+ connector = (
+ mapping.connector
+ if hasattr(mapping, "connector")
+ else mapping["connector"]
+ )
+ proxy = (
+ mapping.conn_proxy
+ if hasattr(mapping, "conn_proxy")
+ else mapping["conn_proxy"]
+ )
+ add_literal(graph, binding_uri, ns.connectorName, connector)
+ add_literal(graph, binding_uri, ns.connProxy, proxy)
+
+ for mapping in bindings.staging_proxy:
+ binding_uri = BNode()
+ graph.add((bindings_uri, ns.hasStagingProxy, binding_uri))
+ graph.add((binding_uri, RDF.type, ns.StagingProxyBinding))
+ name = mapping.name if hasattr(mapping, "name") else mapping["name"]
+ proxy = (
+ mapping.conn_proxy
+ if hasattr(mapping, "conn_proxy")
+ else mapping["conn_proxy"]
+ )
+ add_literal(graph, binding_uri, ns.name, name)
+ add_literal(graph, binding_uri, ns.connProxy, proxy)
+
+ def _emit_connector(
+ self,
+ graph: Graph,
+ connector_uri: URIRef,
+ connector: FileConnector | TableConnector | SparqlConnector,
+ ) -> None:
+ connector_class = ns.CONNECTOR_CLASSES[type(connector).__name__]
+ graph.add((connector_uri, RDF.type, URIRef(str(connector_class))))
+ graph.add((connector_uri, RDF.type, ns.BoundConnector))
+ add_literal(graph, connector_uri, ns.name, connector.name)
+ add_literal(graph, connector_uri, ns.resourceName, connector.resource_name)
+ add_enum_individual(
+ graph,
+ connector_uri,
+ ns.boundSourceKind,
+ connector.bound_source_kind().value,
+ ns.ENUM_REGISTRIES["bound_source_kind"],
+ )
+
+ payload = self._model_payload(connector, ns.MODEL_PAYLOAD_EXCLUDES["connector"])
+ if payload:
+ graph.add((connector_uri, ns.connectorPayload, json_literal(payload)))
+
+ @staticmethod
+ def _model_payload(model: Any, exclude_fields: set[str]) -> dict[str, Any]:
+ payload = model.model_dump(
+ mode="json",
+ by_alias=True,
+ exclude=exclude_fields,
+ exclude_none=True,
+ exclude_defaults=True,
+ )
+ return payload if isinstance(payload, dict) else {}
+
+ @staticmethod
+ def _edge_key(edge: Edge) -> str:
+ relation = edge.relation or "relates"
+ return f"{edge.source}_{relation}_{edge.target}"
diff --git a/graflo/rdf/utils.py b/graflo/rdf/utils.py
new file mode 100644
index 00000000..90a4ba84
--- /dev/null
+++ b/graflo/rdf/utils.py
@@ -0,0 +1,137 @@
+"""Shared helpers for GraFlo RDF serialization."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+from rdflib import BNode, Graph, Literal, RDF, URIRef
+from rdflib.namespace import XSD
+
+from graflo.architecture.pipeline.runtime.actor.config.normalize import (
+ normalize_actor_step,
+)
+from graflo.rdf import namespace as ns
+
+
+def ontology_path() -> Path:
+ """Return the packaged GraFlo meta-ontology Turtle file path."""
+ return Path(__file__).resolve().parent / "ontology" / "graflo.ttl"
+
+
+def load_ontology_graph() -> Graph:
+ """Load the GraFlo meta-ontology into an rdflib graph."""
+ graph = Graph()
+ graph.parse(str(ontology_path()), format="turtle")
+ return graph
+
+
+def slug_token(value: str) -> str:
+ """Normalize arbitrary text into a URI path segment."""
+ cleaned = re.sub(r"[^A-Za-z0-9._-]+", "-", value.strip())
+ return quote(cleaned.strip("-") or "item", safe="-._~")
+
+
+def join_uri(base_uri: str, *parts: str) -> str:
+ """Join base URI with path segments."""
+ base = base_uri.rstrip("/") + "/"
+ tail = "/".join(slug_token(part) for part in parts if part)
+ return base + tail if tail else base.rstrip("/")
+
+
+def json_literal(value: Any) -> Literal:
+ """Encode a Python value as an xsd:string JSON literal."""
+ return Literal(json.dumps(value, sort_keys=True), datatype=XSD.string)
+
+
+def parse_json_literal(value: Literal | str | None) -> Any:
+ """Decode a JSON literal back to Python."""
+ if value is None:
+ return None
+ text = str(value)
+ if not text:
+ return None
+ return json.loads(text)
+
+
+def add_literal(
+ graph: Graph,
+ subject: URIRef | BNode,
+ predicate: URIRef,
+ value: Any,
+) -> None:
+ """Add a literal triple when value is not None."""
+ if value is None:
+ return
+ if isinstance(value, bool):
+ graph.add((subject, predicate, Literal(value, datatype=XSD.boolean)))
+ elif isinstance(value, int):
+ graph.add((subject, predicate, Literal(value, datatype=XSD.integer)))
+ elif isinstance(value, float):
+ graph.add((subject, predicate, Literal(value, datatype=XSD.decimal)))
+ else:
+ graph.add((subject, predicate, Literal(str(value))))
+
+
+def add_enum_individual(
+ graph: Graph,
+ subject: URIRef | BNode,
+ predicate: URIRef,
+ value: str | None,
+ mapping: dict[str, object],
+) -> None:
+ """Link subject to a named enumeration individual."""
+ if value is None:
+ return
+ individual = mapping.get(str(value))
+ if individual is not None:
+ graph.add((subject, predicate, URIRef(str(individual))))
+
+
+def add_rdf_list(
+ graph: Graph,
+ values: list[str],
+) -> BNode | None:
+ """Build an RDF collection for string values."""
+ if not values:
+ return None
+ head = BNode()
+ current = head
+ for index, item in enumerate(values):
+ graph.add((current, RDF.first, Literal(item)))
+ if index == len(values) - 1:
+ graph.add((current, RDF.rest, RDF.nil))
+ else:
+ nxt = BNode()
+ graph.add((current, RDF.rest, nxt))
+ current = nxt
+ return head
+
+
+def actor_step_type(step: dict[str, Any]) -> str:
+ """Return normalized actor step type."""
+ normalized = normalize_actor_step(dict(step))
+ step_type = normalized.get("type")
+ if not isinstance(step_type, str):
+ raise ValueError(f"Unsupported pipeline step: {step!r}")
+ return step_type
+
+
+def actor_step_class(step_type: str) -> object:
+ """Map actor step type to ontology class."""
+ cls = ns.ACTOR_STEP_CLASSES.get(step_type)
+ if cls is None:
+ raise ValueError(f"Unknown actor step type: {step_type!r}")
+ return cls
+
+
+def reverse_enum(mapping: dict[str, object], individual: URIRef | BNode) -> str | None:
+ """Resolve named individual IRI back to enum string."""
+ individual_str = str(individual)
+ for value, term in mapping.items():
+ if str(term) == individual_str:
+ return value
+ return None
diff --git a/mkdocs.yml b/mkdocs.yml
index 29da77fe..d2f07903 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -66,6 +66,8 @@ nav:
- Runtime connector updates: concepts/runtime_connector_updates.md
- Backend Index Behavior: concepts/backend_indexes.md
- Document cast errors and doc error sink: concepts/ingestion_doc_errors.md
+- Model:
+ - GraFlo ontology (manifest RDF): model/graflo_ontology.md
- Guides:
- TigerGraph bulk load (CSV + LOADING JOB): guides/tigergraph_bulk_load.md
- Examples:
diff --git a/pyproject.toml b/pyproject.toml
index 67a9eaee..3a016b3a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,11 +36,11 @@ dependencies = [
"urllib3>=2.0.0",
"xmltodict>=0.14.2,<0.15"
]
-description = "A framework for transforming tabular (CSV, SQL) and hierarchical data (JSON, XML) into property graphs and ingesting them into graph databases (ArangoDB, Neo4j, TigerGraph, FalkorDB, Memgraph, NebulaGraph). Features automatic PostgreSQL schema inference."
+description = "Manifest-driven Graph Schema & Transformation Language (GSTL): define labeled property graph schemas, ingest from CSV/JSON/Parquet/SQL/RDF/SPARQL/API sources, infer schemas from PostgreSQL 3NF or OWL/RDFS ontologies, apply schema migrations, and project to ArangoDB, Neo4j, TigerGraph, FalkorDB, Memgraph, or NebulaGraph."
name = "graflo"
readme = "README.md"
requires-python = ">=3.11"
-version = "1.7.34"
+version = "1.8.0"
[project.optional-dependencies]
dev = [
@@ -66,8 +66,10 @@ plot = [
ingest = "graflo.cli.ingest:ingest"
install_tigergraph_queries = "graflo.cli.install_tigergraph_queries:install_tigergraph_queries"
manage_dbs = "graflo.cli.manage_dbs:manage_dbs"
+manifest_to_rdf = "graflo.rdf.cli:manifest_to_rdf"
migrate_schema = "graflo.cli.migrate_schema:migrate_schema"
plot_manifest = "graflo.cli.plot_manifest:plot_manifest"
+rdf_to_manifest = "graflo.rdf.cli:rdf_to_manifest"
run_tigergraph_queries = "graflo.cli.run_tigergraph_queries:run_tigergraph_queries"
xml2json = "graflo.cli.plot_schema:xml2json"
diff --git a/test/docs/test_build_ontology_viz.py b/test/docs/test_build_ontology_viz.py
new file mode 100644
index 00000000..41aa5808
--- /dev/null
+++ b/test/docs/test_build_ontology_viz.py
@@ -0,0 +1,92 @@
+"""Smoke tests for the GraFlo ontology visualization build script."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+from pathlib import Path
+
+from rdflib import Graph, Literal, URIRef
+from rdflib.namespace import OWL, RDF, RDFS, SKOS
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+BUILD_SCRIPT = REPO_ROOT / "docs" / "scripts" / "build_ontology_viz.py"
+EXTRACT_SCRIPT = REPO_ROOT / "docs" / "scripts" / "ontology_viz" / "extract.py"
+OUTPUT_DIR = REPO_ROOT / "docs" / "assets" / "graflo-ontology-viz"
+INDEX_HTML = OUTPUT_DIR / "index.html"
+EMBED_HTML = OUTPUT_DIR / "embed.html"
+GRAPH_JSON = OUTPUT_DIR / "graph-data.json"
+ONTOLOGY_IRI = "https://ontology.growgraph.dev/graflo"
+
+
+def _load_module(path: Path, name: str):
+ spec = importlib.util.spec_from_file_location(name, path)
+ assert spec is not None and spec.loader is not None
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def test_committed_ontology_viz_assets_exist() -> None:
+ assert INDEX_HTML.is_file(), (
+ "Run docs/scripts/build_ontology_viz.py and commit assets"
+ )
+ assert EMBED_HTML.is_file()
+ assert GRAPH_JSON.is_file()
+ assert (OUTPUT_DIR / "graph-view.js").is_file()
+
+
+def test_committed_ontology_viz_contains_metadata() -> None:
+ html = INDEX_HTML.read_text(encoding="utf-8")
+ assert "GraFlo Ontology" in html
+ assert "GRAFLO_ONTOLOGY_GRAPH" in html
+ payload = json.loads(GRAPH_JSON.read_text(encoding="utf-8"))
+ assert payload["ontology"] == ONTOLOGY_IRI
+ assert payload["nodes"]
+ assert any(edge["kind"] == "subClassOf" for edge in payload["edges"])
+
+
+def test_build_ontology_viz_script_runs() -> None:
+ module = _load_module(BUILD_SCRIPT, "build_ontology_viz")
+ viz_id = module.build_ontology_viz()
+ assert viz_id == "hierarchical-graph"
+ assert INDEX_HTML.is_file()
+ assert EMBED_HTML.is_file()
+
+
+def test_extract_graph_has_subclass_and_property_edges() -> None:
+ extract = _load_module(EXTRACT_SCRIPT, "ontology_viz_extract")
+ payload = extract.extract_ontology_graph()
+ kinds = {edge["kind"] for edge in payload["edges"]}
+ assert "subClassOf" in kinds
+ assert "objectProperty" in kinds or "datatypeProperty" in kinds
+ assert payload["nodeWidth"] > 0
+ assert payload["nodeHeight"] > 0
+
+
+def test_extract_prefers_skos_pref_label_for_nodes() -> None:
+ extract = _load_module(EXTRACT_SCRIPT, "ontology_viz_extract")
+ graph = Graph()
+ node_uri = URIRef("https://ontology.growgraph.dev/graflo/LabelNode")
+ graph.add((node_uri, RDF.type, OWL.Class))
+ graph.add((node_uri, RDFS.label, Literal("Technical Label")))
+ graph.add((node_uri, SKOS.prefLabel, Literal("User Label")))
+
+ payload = extract.extract_ontology_graph(graph)
+ node = next(item for item in payload["nodes"] if item["id"] == str(node_uri))
+ assert node["label"] == "User Label"
+
+
+def test_extract_label_fallback_is_rdfs_then_local_name() -> None:
+ extract = _load_module(EXTRACT_SCRIPT, "ontology_viz_extract")
+ graph = Graph()
+ rdfs_node = URIRef("https://ontology.growgraph.dev/graflo/RdfsNode")
+ local_node = URIRef("https://ontology.growgraph.dev/graflo/LocalNode")
+ graph.add((rdfs_node, RDF.type, OWL.Class))
+ graph.add((rdfs_node, RDFS.label, Literal("From RDFS")))
+ graph.add((local_node, RDF.type, OWL.Class))
+
+ payload = extract.extract_ontology_graph(graph)
+ labels = {item["id"]: item["label"] for item in payload["nodes"]}
+ assert labels[str(rdfs_node)] == "From RDFS"
+ assert labels[str(local_node)] == "LocalNode"
diff --git a/test/rdf/test_manifest_rdf.py b/test/rdf/test_manifest_rdf.py
new file mode 100644
index 00000000..65d46dff
--- /dev/null
+++ b/test/rdf/test_manifest_rdf.py
@@ -0,0 +1,180 @@
+"""Tests for GraphManifest RDF round-trip conversion."""
+
+from __future__ import annotations
+
+import pathlib
+
+import yaml
+from rdflib import Graph, URIRef
+from rdflib.namespace import OWL, RDF
+
+from graflo import GraphManifest
+from graflo.architecture.database_features import EdgePhysicalSpec
+from graflo.architecture.graph_types import Index
+from graflo.rdf import namespace as ns
+from graflo.rdf.deserializer import ManifestRdfDeserializer
+from graflo.rdf.serializer import ManifestRdfSerializer
+from graflo.rdf.utils import load_ontology_graph, ontology_path
+
+
+EXAMPLES_DIR = pathlib.Path(__file__).resolve().parents[2] / "examples"
+BASE_URI = "https://growgraph.dev/manifests/test/"
+
+
+def _load_example_manifest(name: str) -> GraphManifest:
+ path = EXAMPLES_DIR / name / "manifest.yaml"
+ with path.open(encoding="utf-8") as handle:
+ data = yaml.safe_load(handle)
+ return GraphManifest.from_dict(data)
+
+
+def _canonical(manifest: GraphManifest) -> dict:
+ return manifest.to_minimal_canonical_dict()
+
+
+def test_ontology_file_exists_and_loads() -> None:
+ path = ontology_path()
+ assert path.is_file()
+ graph = load_ontology_graph()
+ ontology_uri = URIRef(ns.GF_ONTOLOGY_IRI)
+ assert (ontology_uri, RDF.type, OWL.Ontology) in graph
+ assert (ontology_uri, OWL.versionIRI, URIRef(ns.GF_VERSION_IRI)) in graph
+ version_info = next(graph.objects(ontology_uri, OWL.versionInfo), None)
+ assert version_info is not None
+ assert str(version_info) == ns.GF_VERSION
+
+
+def test_manifest_to_rdf_contains_core_triples() -> None:
+ manifest = _load_example_manifest("1-ingest-csv")
+ serializer = ManifestRdfSerializer(include_ontology=False)
+ graph = serializer.to_graph(manifest, BASE_URI)
+
+ manifest_uri = URIRef(BASE_URI.rstrip("/"))
+ assert (manifest_uri, RDF.type, ns.GraphManifest) in graph
+ assert (manifest_uri, ns.hasSchema, None) is not True
+ assert len(list(graph.objects(manifest_uri, ns.hasSchema))) == 1
+ assert len(list(graph.objects(manifest_uri, ns.hasIngestionModel))) == 1
+ assert len(list(graph.objects(manifest_uri, ns.hasBindings))) == 1
+
+
+def test_round_trip_example_1_ingest_csv() -> None:
+ original = _load_example_manifest("1-ingest-csv")
+ serializer = ManifestRdfSerializer(include_ontology=False)
+ deserializer = ManifestRdfDeserializer()
+
+ ttl = serializer.to_turtle(original, BASE_URI)
+ restored = deserializer.from_turtle(ttl, BASE_URI.rstrip("/"))
+
+ assert _canonical(restored) == _canonical(original)
+
+
+def test_round_trip_example_2_with_transforms() -> None:
+ original = _load_example_manifest("2-ingest-self-references")
+ serializer = ManifestRdfSerializer(include_ontology=False)
+ deserializer = ManifestRdfDeserializer()
+
+ graph = serializer.to_graph(original, BASE_URI)
+ restored = deserializer.from_graph(graph, BASE_URI.rstrip("/"))
+
+ assert _canonical(restored) == _canonical(original)
+
+
+def test_round_trip_example_3_edge_weights() -> None:
+ original = _load_example_manifest("3-ingest-csv-edge-weights")
+ serializer = ManifestRdfSerializer(include_ontology=False)
+ deserializer = ManifestRdfDeserializer()
+
+ ttl = serializer.to_turtle(original, BASE_URI)
+ restored = deserializer.from_turtle(ttl, BASE_URI.rstrip("/"))
+
+ assert _canonical(restored) == _canonical(original)
+
+
+def test_turtle_output_serializes_with_ontology() -> None:
+ manifest = _load_example_manifest("1-ingest-csv")
+ serializer = ManifestRdfSerializer(include_ontology=True)
+ ttl = serializer.to_turtle(manifest, BASE_URI)
+
+ graph = Graph()
+ graph.parse(data=ttl, format="turtle")
+ manifest_uri = URIRef(BASE_URI.rstrip("/"))
+ assert (manifest_uri, RDF.type, ns.GraphManifest) in graph
+
+
+def test_json_ld_output_is_parseable() -> None:
+ manifest = _load_example_manifest("1-ingest-csv")
+ serializer = ManifestRdfSerializer(include_ontology=False)
+ payload = serializer.to_json_ld(manifest, BASE_URI)
+
+ graph = Graph()
+ graph.parse(data=payload, format="json-ld")
+ restored = ManifestRdfDeserializer().from_graph(graph, BASE_URI.rstrip("/"))
+ assert _canonical(restored) == _canonical(manifest)
+
+
+def test_round_trip_preserves_vertex_config_policy_fields() -> None:
+ original = _load_example_manifest("1-ingest-csv")
+ assert original.graph_schema is not None
+ original.graph_schema.core_schema.vertex_config.force_types = {
+ "Person": ["STRING", "INT"]
+ }
+ original.graph_schema.core_schema.vertex_config.identity_from_all_properties = False
+
+ serializer = ManifestRdfSerializer(include_ontology=False)
+ deserializer = ManifestRdfDeserializer()
+ restored = deserializer.from_graph(
+ serializer.to_graph(original, BASE_URI), BASE_URI.rstrip("/")
+ )
+
+ assert restored.graph_schema is not None
+ restored_vertex_cfg = restored.graph_schema.core_schema.vertex_config
+ assert restored_vertex_cfg.force_types == {"Person": ["STRING", "INT"]}
+ assert restored_vertex_cfg.identity_from_all_properties is False
+
+
+def test_context_has_new_vertex_config_and_label_terms() -> None:
+ context_path = (
+ pathlib.Path(__file__).resolve().parents[2]
+ / "graflo"
+ / "rdf"
+ / "ontology"
+ / "graflo-context.jsonld"
+ )
+ payload = context_path.read_text(encoding="utf-8")
+ assert '"forceTypes": "gf:forceTypes"' in payload
+ assert '"identityFromAllProperties": "gf:identityFromAllProperties"' in payload
+ assert '"prefLabel": "skos:prefLabel"' in payload
+
+
+def test_profile_and_transform_actor_semantic_links_are_emitted() -> None:
+ manifest = _load_example_manifest("2-ingest-self-references")
+ assert manifest.graph_schema is not None
+ manifest.graph_schema.db_profile.vertex_indexes = {
+ "Person": [Index(fields=["name"])]
+ }
+ manifest.graph_schema.db_profile.edge_specs = [
+ EdgePhysicalSpec(
+ source="Person",
+ target="Person",
+ relation="follows",
+ indexes=[Index(fields=["created_at"])],
+ )
+ ]
+
+ graph = ManifestRdfSerializer(include_ontology=False).to_graph(manifest, BASE_URI)
+
+ profile_nodes = list(graph.subjects(RDF.type, ns.DatabaseProfile))
+ assert profile_nodes
+ profile_node = profile_nodes[0]
+ vertex_index_nodes = list(graph.objects(profile_node, ns.hasVertexIndex))
+ edge_spec_nodes = list(graph.objects(profile_node, ns.hasEdgeSpec))
+ assert vertex_index_nodes
+ assert edge_spec_nodes
+ assert any(graph.objects(vertex_index_nodes[0], ns.indexField))
+ assert any(graph.objects(edge_spec_nodes[0], ns.hasIndex))
+
+ transform_actor_nodes = list(graph.subjects(RDF.type, ns.TransformActorStep))
+ assert transform_actor_nodes
+ assert any(
+ any(graph.objects(node, ns.executesTransform)) for node in transform_actor_nodes
+ )
diff --git a/uv.lock b/uv.lock
index 5f0f2efb..91a03445 100644
--- a/uv.lock
+++ b/uv.lock
@@ -434,7 +434,7 @@ dependencies = [
]
name = "graflo"
source = {editable = "."}
-version = "1.7.34"
+version = "1.8.0"
[package.metadata]
provides-extras = ["dev", "docs", "plot"]