# Supported File Formats for Ingestion in Semantica: Markdown and Plain-Text Only

> Discover Semantica's supported file formats for ingestion. Learn how to ingest your data using only Markdown and plain-text files for efficient graph entity generation.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: api-reference
- Published: 2026-09-04

---

**Semantica officially supports only Markdown (`.md`) and plain-text (`.txt`) files for ingestion, routing both through a unified Markdown parsing pipeline to generate graph entities.**

The `semantica-agi/semantica` repository implements a lightweight ingestion system designed specifically for text-based knowledge sources. When considering supported file formats for ingestion in Semantica, developers should note that the platform intentionally limits input to Markdown and plain-text files, with all content ultimately processed through the same rendering pipeline regardless of extension.

## How Semantica Handles File Ingestion

The ingestion system relies on a *format hint* mechanism that checks for an optional `format` property when files are loaded. If no hint is provided, Semantica defaults to treating content as Markdown. This design choice ensures backward compatibility while maintaining a simple architecture focused on text-based knowledge representation.

According to the source code, the system explicitly does not implement parsers for structured data formats. Files dropped via the UI or loaded through the API undergo immediate text extraction, with the `nodeMarkdownSync` engine handling all downstream processing.

## Core Ingestion Files and Architecture

Two critical files define the ingestion behavior:

- [`explorer/src/workspaces/VocabularyWorkspace/types.ts`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/VocabularyWorkspace/types.ts) — Declares the TypeScript interfaces including the optional `format` field that signals which parser to invoke.
- [`explorer/src/workspaces/GraphWorkspace/nodeMarkdownSync.ts`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/GraphWorkspace/nodeMarkdownSync.ts) — Contains the core synchronization logic that parses file content as Markdown and generates the corresponding graph nodes.

These files work in concert to ensure that only text-based formats are accepted into the knowledge graph.

### Vocabulary Workspace Types

In [`explorer/src/workspaces/VocabularyWorkspace/types.ts`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/VocabularyWorkspace/types.ts), the interface definitions include an optional `format` property. This field accepts string values such as `"md"` or `"txt"`, acting as a discriminator for the ingestion pipeline. When specified, it overrides automatic format detection; when omitted, the system falls back to Markdown parsing.

### Node Markdown Sync Engine

The [`nodeMarkdownSync.ts`](https://github.com/semantica-agi/semantica/blob/main/nodeMarkdownSync.ts) file implements the actual ingestion logic. This module reads file content, processes it through the Markdown renderer, and maps the resulting structure to graph entities. Notably, this same pipeline handles both `.md` and `.txt` files—plain-text files simply pass through without special markup while maintaining identical downstream processing.

## Loading Files via the API

Developers interact with the ingestion system through the `loadGraphFromFile` function exported from `@semantica/explorer`. This asynchronous function accepts a configuration object containing the file path and optional format specification.

### Loading Markdown Files

To explicitly load a Markdown file, supply the `format` property:

```typescript
import { loadGraphFromFile } from '@semantica/explorer';

await loadGraphFromFile({
  path: '/path/to/knowledge.md',
  format: 'md',               // explicit format hint
});

```

### Loading Plain-Text Files

Plain-text files require no format specification, though they undergo identical processing:

```typescript
import { loadGraphFromFile } from '@semantica/explorer';

await loadGraphFromFile({
  path: '/path/to/notes.txt', // .txt extension accepted
  // no format needed – defaults to Markdown parsing
});

```

Both examples route through [`nodeMarkdownSync.ts`](https://github.com/semantica-agi/semantica/blob/main/nodeMarkdownSync.ts), demonstrating how Semantica unifies text ingestion regardless of the original file extension.

## Unsupported Formats and Limitations

Semantica explicitly excludes binary and structured data formats from its ingestion stack. Attempting to load **JSON**, **CSV**, **XML**, or other non-text formats results in the system interpreting them as raw plain text. This parsing strategy does not produce structured graph data from these formats, effectively limiting their utility within the Semantica environment.

The architecture intentionally avoids format-specific parsers beyond the Markdown renderer, keeping the codebase lightweight and focused on textual knowledge representation.

## Summary

- Semantica supports only **Markdown (`.md`)** and **plain-text (`.txt`)** files for ingestion.
- The ingestion pipeline defaults to Markdown parsing when no format hint is provided.
- [`explorer/src/workspaces/VocabularyWorkspace/types.ts`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/VocabularyWorkspace/types.ts) defines the optional `format` field interface.
- [`explorer/src/workspaces/GraphWorkspace/nodeMarkdownSync.ts`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/GraphWorkspace/nodeMarkdownSync.ts) implements the core parsing and graph generation logic.
- Structured formats like JSON and CSV are not supported and will be treated as unstructured text.

## Frequently Asked Questions

### Can Semantica ingest JSON or CSV files?

No. According to the `semantica-agi/semantica` source code, JSON and CSV files are not part of the ingestion stack. If loaded, these files will be interpreted as plain text without producing structured graph data, as the system lacks dedicated parsers for tabular or structured JSON formats.

### How does Semantica determine which parser to use?

Semantica checks for an optional `format` property in the load configuration, as defined in [`explorer/src/workspaces/VocabularyWorkspace/types.ts`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/VocabularyWorkspace/types.ts). If this hint is absent, the system automatically falls back to the Markdown parser implemented in [`explorer/src/workspaces/GraphWorkspace/nodeMarkdownSync.ts`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/GraphWorkspace/nodeMarkdownSync.ts), treating all input as Markdown-compatible text.

### Is there a difference between loading `.md` and `.txt` files?

Functionally, no. Both file extensions route through the same `nodeMarkdownSync` pipeline. Markdown files receive full markup parsing, while plain-text files are treated as Markdown without special formatting. Both generate identical graph entity structures within the Semantica visualization workspace.

### What function is used to load files programmatically?

Use the `loadGraphFromFile` function imported from `@semantica/explorer`. This async function accepts a path and optional format parameter, ultimately invoking the `nodeMarkdownSync` logic to process the file and populate the knowledge graph.