What Kind of Datasets Does OpenSpec Work With?

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 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 (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:

# 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:

# 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 metadata file defined in 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 (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 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 files per src/utils/change-metadata.ts.
• The Skills Query CLI (documented in 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 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 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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}