csvx

README

CSVX Go Engine

The Go engine is the first implementation of the CSVX specification. It is intentionally specification-first: the engine must conform to CSVX behavior, but its internal architecture does not define the format.

Current scope

The initial package provides the Phase 1 foundation:

• CSVX ZIP package loading
• Manifest and workbook loading
• UTF-8 CSV sheet loading
• Optional .meta.json sheet metadata
• Typed metadata structures for columns, formulas, caches, styles, and validation
• Sparse cell metadata addressed by A1 coordinates
• Duplicate and unsafe ZIP entry rejection
• Package and extract CLI commands for developer workflows

Formula parsing, calculation, import/export, and full CLI operations will be added behind the same canonical workbook model. Package writing and extract/package round-trip support are now available for developer workflows.

Development rule

Each capability follows this sequence:

Specify → create conformance fixtures → implement → run tests

The specification repository is the authority:

../csvx-spec/

Package

workbook, err := csvx.Open("report.csvx")
if err != nil {
    return err
}
fmt.Println(workbook.Sheets[0].Records)

CSV is the canonical sheet data layer. Metadata that CSV cannot represent is stored in the matching .meta.json sidecar.

Commands

Run commands from the repository root:

Format

gofmt -w .

Formats all Go source files before committing.

Build

go build ./...

Builds every package in the module.

To build the CLI once it is added:

go build -o bin/csvx ./cmd/csvx

Test

go test ./...

Runs all unit and package tests.

Run tests with the race detector:

go test -race ./...

Run a specific test:

go test -run TestLoadCSVBackedWorkbook ./...

Coverage

go test -cover ./...
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Static analysis

go vet ./...

Run the CLI

Build the current CLI:

go build -o bin/csvx ./cmd/csvx

The currently supported commands are:

csvx --help
csvx version
csvx inspect report.csvx
csvx inspect ../csvx-spec/examples/minimal.csvx
csvx validate report.csvx
csvx validate ../csvx-spec/examples/minimal.csvx
csvx validate --json ../csvx-spec/examples/minimal.csvx
csvx package ../csvx-spec/examples/minimal.csvx --output minimal.csvx
csvx extract minimal.csvx --output minimal-extracted
csvx xlsx-inspect ../csvx-spec/examples/example.xlsx
csvx xlsx-inspect --json ../csvx-spec/examples/example.xlsx

Both .csvx ZIP files and unpacked CSVX package directories are accepted. The following commands are planned but not implemented yet:

csvx recalc report.csvx
csvx convert report.xlsx report.csvx
csvx convert report.csvx report.xlsx
csvx convert report.csvx report.csv

Dependency and module maintenance

go mod tidy
go list -m all
go version

go mod tidy should be run when imports change. Review its changes before committing.

Development workflow

1. Update the relevant specification in ../csvx-spec/.
2. Add or update a conformance fixture.
3. Implement the behavior in the engine.
4. Run gofmt, go vet, and go test ./....
5. Document any intentionally unsupported behavior.
6. Confirm that CSV data and metadata sidecars remain round-trip safe.

Do not treat engine behavior as a specification change without updating the specification repository.

Documentation

Overview

Package csvx provides a specification-first reader and writer for CSVX workbooks.

Index

• func Convert(input, output string) error
• func ExtractPackage(filename, directory string) error
• func PackageDirectory(directory, output string) error
• func WritePackage(workbook *Workbook, output string) error
• type Calculation
• type CellMetadata
• type Column
• type Diagnostic
• type Manifest
• type Sheet
• type SheetEntry
• type SourceMetadata
• type Style
  • func (s Style) MarshalJSON() ([]byte, error)
• type ValidationResult
  • func Validate(filename string) ValidationResult
• type Value
• type Workbook
  • func Load(reader io.ReaderAt, size int64) (*Workbook, error)
  • func Open(filename string) (*Workbook, error)
  • func OpenDirectory(directory string) (*Workbook, error)
• type WorkbookDocument
• type XLSXDiagnostic
• type XLSXFeatureCounts
• type XLSXInspection
  • func InspectXLSX(filename string) (*XLSXInspection, error)
• type XLSXSheet

Functions

func Convert

func Convert(input, output string) error

Convert imports or exports a workbook based on the input and output extensions.

func ExtractPackage

func ExtractPackage(filename, directory string) error

ExtractPackage extracts a CSVX ZIP package into an unpacked directory.

func PackageDirectory

func PackageDirectory(directory, output string) error

PackageDirectory writes an unpacked CSVX package directory as a ZIP .csvx file.

func WritePackage

func WritePackage(workbook *Workbook, output string) error

WritePackage writes a workbook to a deterministic CSVX ZIP package.

Types

type Calculation

type Calculation struct {
	Mode      string `json:"mode,omitempty"`
	Iteration bool   `json:"iteration,omitempty"`
}

Calculation contains workbook calculation settings.

type CellMetadata

type CellMetadata struct {
	Type       string          `json:"type,omitempty"`
	Formula    string          `json:"formula,omitempty"`
	Cached     *Value          `json:"cached,omitempty"`
	Style      string          `json:"style,omitempty"`
	Validation json.RawMessage `json:"validation,omitempty"`
}

CellMetadata contains behavior that cannot be represented in CSV.

type Column

type Column struct {
	ID    string  `json:"id"`
	Name  string  `json:"name"`
	Type  string  `json:"type,omitempty"`
	Width float64 `json:"width,omitempty"`
}

Column describes a CSV column and its optional CSVX type.

type Diagnostic

type Diagnostic struct {
	Code     string `json:"code"`
	Path     string `json:"path,omitempty"`
	Message  string `json:"message"`
	Severity string `json:"severity"`
}

Diagnostic describes a validation error or warning at a package resource.

type Manifest

type Manifest struct {
	Format   string   `json:"format"`
	Version  string   `json:"version"`
	Workbook string   `json:"workbook"`
	Files    []string `json:"files"`
}

Manifest identifies a CSVX package and its resources.

type Sheet

type Sheet struct {
	ID           string                     `json:"id"`
	Name         string                     `json:"name"`
	Path         string                     `json:"path"`
	MetadataPath string                     `json:"metadata,omitempty"`
	Columns      []Column                   `json:"columns"`
	Records      [][]string                 `json:"records"`
	RowHeights   map[int]float64            `json:"rowHeights,omitempty"`
	Cells        map[string]CellMetadata    `json:"cells,omitempty"`
	Extra        map[string]json.RawMessage `json:"-"`
}

Sheet is a CSV-backed worksheet. Records excludes the CSV header row.

type SheetEntry

type SheetEntry struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Path     string `json:"path"`
	Metadata string `json:"metadata,omitempty"`
}

SheetEntry locates a sheet's CSV and optional metadata sidecar in a package.

type SourceMetadata

type SourceMetadata struct {
	Format     string            `json:"format"`
	Filename   string            `json:"filename"`
	SHA256     string            `json:"sha256"`
	Authority  string            `json:"authority"`
	ImportedAt string            `json:"importedAt"`
	Importer   string            `json:"importer"`
	Features   XLSXFeatureCounts `json:"features,omitempty"`
	Warnings   []XLSXDiagnostic  `json:"warnings,omitempty"`
}

SourceMetadata describes an embedded external workbook preserved for interoperability.

type Style

type Style schema.CSVXStylesStylesElem

Style is a single style record. Its field shape is generated from csvx-spec's styles.schema.json (see internal/schema/generated.go) rather than hand-typed, so it cannot silently drift from the schema the way the previous hand-written map[string]map[string]any representation did.

This is a defined type over the generated struct, not a plain alias, solely so MarshalJSON below can omit the generated AdditionalProperties bucket field until this engine implements real additionalProperties round-tripping on both read and write (styles.json is not read back in anywhere yet, so nothing currently depends on inheriting the generated UnmarshalJSON here).

func (Style) MarshalJSON

func (s Style) MarshalJSON() ([]byte, error)

MarshalJSON serializes a Style without the generated AdditionalProperties bucket field, which encoding/json would otherwise emit as a literal `"AdditionalProperties": null` key — schema- legal (styles.schema.json allows additional properties) but wrong output.

type ValidationResult

type ValidationResult struct {
	Valid    bool         `json:"valid"`
	Errors   []Diagnostic `json:"errors"`
	Warnings []Diagnostic `json:"warnings"`
}

ValidationResult contains machine-readable package validation output.

func Validate

func Validate(filename string) ValidationResult

Validate checks a CSVX ZIP file or unpacked CSVX directory.

type Value

type Value struct {
	Type    string `json:"type"`
	Value   any    `json:"value,omitempty"`
	Code    string `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
}

Value is a typed CSVX value used by formulas, caches, and diagnostics.

type Workbook

type Workbook struct {
	ID          string          `json:"id"`
	Version     string          `json:"version"`
	Sheets      []*Sheet        `json:"sheets"`
	Calculation Calculation     `json:"calculation,omitempty"`
	Source      *SourceMetadata `json:"source,omitempty"`
	Styles      []Style         `json:"styles,omitempty"`
	SourceBytes []byte          `json:"-"`
}

Workbook is the canonical in-memory representation of a CSVX workbook.

func Load

func Load(reader io.ReaderAt, size int64) (*Workbook, error)

Load reads a CSVX ZIP package from an io.ReaderAt with the supplied size.

func Open

func Open(filename string) (*Workbook, error)

Open reads a CSVX ZIP package from disk.

func OpenDirectory

func OpenDirectory(directory string) (*Workbook, error)

OpenDirectory reads an unpacked CSVX package directory.

type WorkbookDocument

type WorkbookDocument struct {
	ID          string          `json:"id"`
	Version     string          `json:"version"`
	Sheets      []SheetEntry    `json:"sheets"`
	Calculation Calculation     `json:"calculation,omitempty"`
	Source      *SourceMetadata `json:"source,omitempty"`
	Styles      string          `json:"styles,omitempty"`
}

WorkbookDocument is the serialized workbook resource.

type XLSXDiagnostic

type XLSXDiagnostic struct {
	Severity string `json:"severity"`
	Feature  string `json:"feature"`
	Path     string `json:"path,omitempty"`
	Message  string `json:"message"`
}

XLSXDiagnostic records an interoperability limitation or observation.

type XLSXFeatureCounts

type XLSXFeatureCounts struct {
	SharedStrings int `json:"sharedStrings"`
	Styles        int `json:"styles"`
	NumberFormats int `json:"numberFormats"`
	Drawings      int `json:"drawings"`
	Charts        int `json:"charts"`
	Images        int `json:"images"`
	Comments      int `json:"comments"`
	Persons       int `json:"persons"`
	Macros        int `json:"macros"`
	Relationships int `json:"relationships"`
}

XLSXFeatureCounts summarizes workbook features relevant to CSVX interoperability.

type XLSXInspection

type XLSXInspection struct {
	Format    string            `json:"format"`
	Filename  string            `json:"filename"`
	SHA256    string            `json:"sha256"`
	Sheets    []XLSXSheet       `json:"sheets"`
	Features  XLSXFeatureCounts `json:"features"`
	Resources []string          `json:"resources"`
	Warnings  []XLSXDiagnostic  `json:"warnings"`
}

XLSXInspection describes the portable features and package resources detected in an XLSX file.

func InspectXLSX

func InspectXLSX(filename string) (*XLSXInspection, error)

InspectXLSX reads an XLSX package without executing macros, links, or external resources.

type XLSXSheet

type XLSXSheet struct {
	Name          string `json:"name"`
	Path          string `json:"path"`
	Cells         int    `json:"cells"`
	Formulas      int    `json:"formulas"`
	CachedValues  int    `json:"cachedValues"`
	StyledCells   int    `json:"styledCells"`
	SharedStrings int    `json:"sharedStrings"`
}

XLSXSheet describes one worksheet and its understood cell features.