# What Kind of Datasets Does OpenSpec Work With?

> OpenSpec handles diverse datasets like JSON, CSV, databases, code, and binaries. Use Markdown specs to integrate any data with OpenSpec.

- Repository: [Fission/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- Tags: tutorial
- Published: 2026-06-28

---

**OpenSpec is deliberately data-agnostic and works with any dataset you can describe in a Markdown-based spec, including JSON, CSV, database schemas, code files, and binary assets.**

OpenSpec (Fission-AI/OpenSpec) treats any collection of information that can be described in text as a dataset. Rather than enforcing specific formats or storage locations, the framework captures dataset identity, version, and validation rules in [`.openspec.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/.openspec.yaml) metadata files and Markdown artefacts, making any describable data AI-readable and version-controlled.

## Structured Records and Serialised Formats

OpenSpec handles **JSON**, **CSV**, **TSV**, and **YAML** files natively by referencing them directly in your specs. According to the [`README.md`](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) (lines 151-156), the CLI can emit their contents in machine-readable form using `--json` mode, allowing you to process structured records without transformation.

### Working with JSON and CSV Files

You can initialise a project and immediately begin tracking data files:

```bash

# Initialise a project – OpenSpec will track any files you add

openspec init

# Add a JSON data file and reference it in a spec

mkdir data && echo '{"users": []}' > data/users.json
cat > specs/add-user/spec.md <<'EOF'

# Add‑User Change

## Overview

Create an endpoint that returns the list of users from `data/users.json`.

## Requirements

- Read `data/users.json`
- Expose `/api/users` that returns the JSON payload
EOF

# Run a skill that queries the JSON file and returns its schema

openspec skill query data/users.json --format json

```

For CSV datasets, describe the column headers in your spec to reason about the data shape:

```bash

# Example of a CSV dataset

echo "id,name,score\n1,Alice,95\n2,Bob,88" > data/participants.csv

# Spec referencing the CSV columns

cat > specs/scoreboard/spec.md <<'EOF'

# Scoreboard Change

## Overview

Render a leaderboard from `data/participants.csv`.

## Columns

- `id`   (integer)
- `name` (string)
- `score` (integer)
EOF

```

## Code and Configuration Files

OpenSpec reads **source code**, **build scripts**, **dependency manifests**, and **Dockerfiles** as part of the repository tree. These files are treated as datasets that describe behaviour, allowing you to generate or validate specs that capture their functionality.

## Database Schemas and Query Results

You can incorporate **SQL DDL**, **query outputs**, and **migration scripts** without requiring a live database connection. OpenSpec captures schema fragments and example result rows directly in spec files, storing the structural metadata as text-based artefacts.

## Binary Assets and API Payloads

**Images**, **binaries**, and **compiled artifacts** are treated as opaque blobs within OpenSpec. You record their paths, version hashes, or checksum metadata in your specs. Additionally, **custom API payloads** retrieved from external services can be embedded as JSON within specs for later use, enabling OpenSpec to work with third-party data sources.

## How OpenSpec Stores Dataset Metadata

Dataset identity and versioning are managed through the [`.openspec.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/.openspec.yaml) metadata file defined in [`src/utils/change-metadata.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/change-metadata.ts). This file stores dataset identifiers, versions, and formats, ensuring that any data you reference remains portable and version-controlled alongside your code.

## Querying Structured Data with the Skills CLI

When invoking slash-commands like `/opsx:explore` or `/opsx:propose`, OpenSpec queries structured data via the **Skills Query CLI**. As documented in [`docs/opsx.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md) (line 416), this CLI can process any structured payload the skill returns, regardless of whether it originates from a JSON file, database query, or third-party API. The [`docs/supported-tools.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md) file lists how OpenSpec installs skills and commands that interact with these arbitrary datasets.

## Summary

- OpenSpec is **data-agnostic** and imposes no specific format requirements.
- Works with **JSON**, **CSV**, **YAML**, **code files**, **database schemas**, **binary assets**, and **API payloads**.
- Dataset metadata is stored in [`.openspec.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/.openspec.yaml) files per [`src/utils/change-metadata.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/change-metadata.ts).
- The **Skills Query CLI** (documented in [`docs/opsx.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md)) enables interaction with structured data from any source.
- Any dataset describable in Markdown/YAML artefacts can be incorporated into the framework.

## Frequently Asked Questions

### Does OpenSpec require a specific database to work with datasets?

No. OpenSpec does not require a live database connection. You can capture SQL DDL, schema fragments, and example result rows directly in your spec files, allowing the framework to reason about database structure without runtime dependencies.

### Can OpenSpec handle binary files like images or compiled executables?

Yes. Binary assets are treated as opaque blobs. You record their paths, version hashes, or checksum metadata in your [`.openspec.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/.openspec.yaml) or Markdown specs, enabling version control and tracking without parsing the binary content itself.

### How does OpenSpec validate dataset formats?

OpenSpec validates datasets by referencing the metadata and validation rules stored in your repository's [`.openspec.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/.openspec.yaml) files. Because the framework is description-based, validation occurs against the spec's definition of the data shape rather than enforcing a particular schema language.

### What is the Skills Query CLI used for?

The Skills Query CLI, documented in [`docs/opsx.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md) (line 416), allows OpenSpec to query structured data when running slash-commands. It processes payloads from JSON files, database queries, or external APIs, returning machine-readable results that can be embedded back into your specs.