# Export formats

> Export your ontology as JSON, Markdown, CSV, PDF, AI Agent Bundle, or RDF/OWL (Turtle and JSON-LD) — and when to use each. Includes RAG, GraphRAG and vector database (Vector DB) setups.

**Category:** Import & Export | **Tab:** features

---

Export your ontology in multiple formats, each optimized for different tools and workflows.

## JSON

Structured data export for programmatic use and AI tool configuration.

**What's included:**
- All concepts with their classes and descriptions
- All terms with variants, status, and market availability
- Semantic relationships between concepts
- Market definitions and constraints

**Best for:** MCP tool configuration, API integration, TMS import, programmatic access.

## Markdown

Human-readable export with clear headings, tables, and structured prose.

**What's included:**
- Concepts organized by class with descriptions
- Terms per locale with preferred term, variants, and status
- Market availability overview
- Relationship summaries

**Best for:** LLM prompts, Gemini, Custom GPTs, internal documentation, knowledge sharing.

## CSV

Flat tabular data with configurable columns and two layout options.

**Layout options:**

- **Translation Grid** — Wide format with one row per concept and markets as columns. Best for spreadsheet review and side-by-side comparison across locales.
- **Detailed Rows** — Long format with one row per target term. Best for translation management and per-term filtering.

You can configure exactly which columns to include and in what order using the CSV column configurator.

**Best for:** Spreadsheets, translators, bulk editing, data review.

## AI Agent Bundle (ZIP)

A structured folder of Markdown files with a top-level `CLAUDE.md` entry point, optimized for AI coding agents.

**What's included:**
- `CLAUDE.md` — Agent entry point with ontology overview and navigation instructions
- Per-class folders with concept definitions
- Per-locale term files with variants and status
- Market definitions and relationship data

The AI Agent Bundle is designed for the **GitHub Sync → Claude Projects** workflow: sync your ontology to a GitHub repo, then attach it as a Claude Project for context-aware AI assistance.

You can also download the same bundle through the API with `GET /query-ontology?format=markdown-zip`, or fetch a single file with `format=markdown&path=…`. The files are identical to the in-app ZIP and GitHub Sync. Each file carries a version and a "generated at" date, and is a snapshot — the live workspace stays the source of truth. See [API Reference](/docs/integrations/api-reference).

**Best for:** Claude Projects, Claude Code, AI coding agents, developer workflows.

## RDF/OWL — Turtle and JSON-LD

Standards-based semantic web exports built on **SKOS-XL + OWL**, for graph databases, ontology tooling, and linked-data publishing.

Both files describe **exactly the same graph** — the same concept IRIs, the same labels, the same predicates. The only difference is serialization, so pick whichever your consuming tool reads most naturally.

### Turtle (`.ttl`)

Compact, human-readable RDF. The default interchange format for the semantic web stack.

**Choose Turtle when:**
- You are loading into a triple store or graph database — GraphDB, Stardog, Neo4j (via n10s), Apache Jena, Virtuoso
- You will query the data with SPARQL
- You are opening the ontology in an editor such as Protégé or TopBraid
- A reviewer needs to read the raw model by eye — Turtle is by far the most legible RDF syntax

### JSON-LD (`.jsonld`)

The same RDF expressed as JSON, with a `@context` that maps the short keys onto the full vocabulary.

**Choose JSON-LD when:**
- The consumer is a web or JavaScript pipeline that already parses JSON
- You are storing the graph in a document database, search index, or vector store alongside other JSON
- You need structured data for the web, or a procurement/tender checklist asks for a machine-readable linked-data format
- Your team is comfortable with JSON but not with RDF syntax — JSON-LD degrades gracefully to plain JSON

### What's included in both

Concepts as `skos:Concept`, source and target terms as `skosxl:Label` per locale, classes as `skos:ConceptScheme`, and semantic relationships as typed `owl:ObjectProperty` predicates. Black Ice-specific predicates (market, status, availability, allowed and forbidden variants, translation policy) live under the published namespace `https://black-ice.ai/ns#`, which is dereferenceable at `/black-ice-ns.ttl`.

Predicate names are frozen for the lifetime of schema version `1.0`, so downstream consumers can safely pin to the namespace.

**Best for:** GraphDB, Neo4j (via n10s), Stardog, Protégé, SPARQL pipelines, RAG grounding, public-sector and linked-data publishing.

> RDF/OWL exports are available on **Pro and Builder**.

### Using the graph with vector databases and GraphRAG

The RDF exports are designed to sit next to a vector index. Embeddings find the right concept by meaning; the graph then supplies the governed answer — approved term per market, forbidden variants, availability and related concepts — so retrieval never relies on similarity alone.

**Pattern 1 — Hybrid GraphRAG (Neo4j, Amazon Neptune, Memgraph, GraphDB)**

1. Load the Turtle file into the graph store (for Neo4j, use the n10s / neosemantics plugin).
2. Embed each concept's definition and its term labels, and store the vector with the concept IRI as its key.
3. At query time, embed the question, find the nearest concept IRIs, then traverse the graph from those IRIs to read the approved `skosxl:prefLabel` for the requested language tag (for example `@es-ES`), `bi:forbiddenVariant`, `bi:availability` and related concepts.
4. Pass only that governed context to the model.

**Pattern 2 — Metadata-enriched embeddings (Qdrant, Weaviate, Pinecone, Milvus, pgvector)**

1. Iterate the nodes in the JSON-LD `@graph`.
2. Embed the definition text (plus source term) of each concept.
3. Store the concept IRI, class, approved terms per locale, forbidden variants, availability per market and related concept IRIs in the vector's payload / metadata.
4. Filter on metadata at query time — for example, only concepts available in `de-DE` — so the model never sees terms that aren't live in that market.

**Framework loaders**

- **LlamaIndex** — load Turtle with an RDF reader, or build a `PropertyGraphIndex` from the triples.
- **LangChain** — use `RdfGraph` to query the Turtle file with SPARQL, alongside any LangChain vector store.
- **rdflib (Python)** / **jsonld.js (JavaScript)** — parse either file directly in your own pipeline.

**Keeping it fresh.** RDF files are snapshots from the Export dialog. Re-export and re-index when terms change, or use MCP / the API for live lookups and keep the vector index for discovery only.

## PDF

Prose document with formatted headings, tables, and structured content for document-based AI tools.

**What's included:**
- Full ontology overview with concepts organized by class
- Term tables per locale
- Market availability summaries
- Relationship descriptions

**Best for:** NotebookLM & document-based AI.

## Knowledge graph images (PNG, SVG, PDF)

Separate from the data exports above, the **Knowledge Graph** view exports the visual graph itself from its own export menu.

- **PNG** — standard, retina (2×) and print (4×) resolutions
- **SVG** — vector, scales to any size and stays editable in design tools
- **PDF** — vector page, ready to drop into a document

Retina PNG, print PNG, SVG and PDF are available on **Pro and Builder**; standard PNG is available on every plan.

**Best for:** Slides, board decks, architecture documentation, onboarding material, client presentations.

## JSON Schema

The export dialog also offers the **JSON Schema** that describes the JSON export — copy it to the clipboard or download it as a file.

**Best for:** Validating exported files in a pipeline, generating typed clients, and documenting the contract for engineering teams.

---

## Where each format comes from

| Surface | Formats produced |
|---|---|
| **Export Ontology dialog** (in app) | JSON, Markdown, CSV, AI Agent Bundle, PDF, Turtle, JSON-LD, JSON Schema |
| **Knowledge Graph view** (in app) | PNG, SVG, PDF images of the graph |
| **GitHub Sync** | AI Agent Bundle — Markdown files written into your repository |
| **Workspace API** | JSON from `GET /query-ontology`, plus the AI Agent Bundle as a ZIP (`format=markdown-zip`), a single Markdown file (`format=markdown&path=…`) or a JSON list of files (`format=markdown-files`) |
| **MCP** | JSON answers from the read tools, always live |

RDF/OWL, PDF, CSV and graph images are produced in the app rather than through the API. If you need Markdown on a schedule, pull the bundle ZIP from the API in your pipeline or use GitHub Sync. For the other formats, export from the app and commit the file.

---

## Which format should I use?

Use this table to find the right format for your tool or workflow:

| Tool / Workflow | Recommended Format |
|---|---|
| **Gemini** | Markdown |
| **Custom GPTs** | Markdown |
| **Claude Projects** | AI Agent Bundle (ZIP) |
| **Claude Code** | AI Agent Bundle (ZIP) |
| **NotebookLM** | PDF |
| **MCP tools** | JSON |
| **Spreadsheet review** | CSV (Translation Grid) |
| **Translation management** | CSV (Detailed Rows) |
| **API / TMS integration** | JSON |
| **Scheduled pipeline needing Markdown** | AI Agent Bundle via API (`format=markdown-zip`) or GitHub Sync |
| **Internal documentation** | Markdown or PDF |
| **Graph databases / triple stores** | Turtle |
| **SPARQL queries** | Turtle |
| **Ontology editors (Protégé, TopBraid)** | Turtle |
| **Web / JavaScript linked-data pipelines** | JSON-LD |
| **Public-sector tenders and RFPs** | JSON-LD (or Turtle, if specified) |
| **RAG grounding for LLMs** | JSON-LD or Turtle |
| **Hybrid GraphRAG (Neo4j, Neptune, GraphDB)** | Turtle |
| **Vector databases (Qdrant, Weaviate, Pinecone, pgvector)** | JSON-LD |
| **LlamaIndex / LangChain pipelines** | Turtle or JSON-LD |
| **Slides and presentations** | Knowledge graph PNG or SVG |
| **Validating exports in CI** | JSON Schema |

> **Tip:** If you're using GitHub Sync, the AI Agent Bundle format is automatically optimized for your synced repository structure — making it ideal for Claude Projects and AI-assisted development.