opencli-go

Go types for the OpenCLI spec.

This project implements a subset of a variation of the OpenCLI specification. The current version is 0.1-block.1, which differs from the upstream spec in two ways:

1. The Document object extends the Command object — see spectreconsole/open-cli#70
2. Command supports the field defaultCommand — see spectreconsole/open-cli#77

Installation

go get github.com/block/opencli-go

Usage

import "github.com/block/opencli-go"

Marshaling

Document.MarshalJSON always writes the current version constant:

doc := opencli.Document{
    Info: opencli.CliInfo{Version: "1.0.0"},
    Command: opencli.Command{
        Name: "myapp",
        Commands: []opencli.Command{
            {Name: "serve"},
        },
    },
}
data, _ := json.Marshal(doc)
// {"opencli":"0.1-block.1","info":{"version":"1.0.0"},"name":"myapp",...}

Unmarshaling

Document.UnmarshalJSON validates the "opencli" field and rejects missing or unrecognized versions:

var doc opencli.Document
err := json.Unmarshal(data, &doc)
// Returns an error if "opencli" is missing or unsupported

Version support

This module can unmarshal any OpenCLI version it supports and always marshals to the latest version (opencli.Version).

When a future version of this module introduces breaking type changes, it will use Go's semantic import versioning (e.g. github.com/block/opencli-go/v2). A program can import multiple major versions simultaneously:

import (
    opencli   "github.com/block/opencli-go"
    opencliv2 "github.com/block/opencli-go/v2"
)

Adding a new schema version

Types are code-generated from JSON Schema files in schema/. To add support for a new version:

1. Add the schema file (e.g. schema/0.2-block.1.json).
2. Run just generate-types to create internal/v0_2_block_1/types_gen.go.
3. Add internal/v0_2_block_1/unmarshal.go with any custom unmarshal logic (e.g. Arity defaults).
4. Add a case "0.2-block.1": branch to Document.UnmarshalJSON in opencli.go.
5. If this becomes the new current version, update the Version constant and re-point the public type aliases to the new internal package.

Development

This project uses Hermit for tool management. Activate the environment:

. ./bin/activate-hermit

Generate types from schemas:

just generate-types

Run tests:

go test ./...

Project Resources

Resource	Description
CODEOWNERS	Outlines the project lead(s)
GOVERNANCE.md	Project governance
LICENSE	Apache License, Version 2.0