Thesaurus Go

A lightweight Go package for English thesaurus lookups using an embedded, Open English WordNet (OEWN) dataset.

Features

• Zero runtime dependencies: pure Go, standard library only

• Embedded dataset: Open English WordNet (OEWN) compiled into the binary via go:embed; no external files required at runtime

• Compressed embedded data: synonym and antonym indexes are stored as gzip-compressed JSON to reduce binary size

• 45,000+ English words: far broader coverage than small curated thesaurus lists

• Simple API: Lookup, WordsWithPrefix, Contains, Count, and AllWords

• Case-insensitive lookups: input is automatically normalized by trimming whitespace and converting to lowercase

• Well tested: lookup behavior, merge logic, normalization, and unknown words are all covered

Installation

go get github.com/bobadilla-tech/thesaurus-go

Usage

package main

import (
	"fmt"
	"log"

	thesaurus "github.com/bobadilla-tech/thesaurus-go"
)

func main() {
	entry, ok := thesaurus.Lookup("happy")

	if !ok {
		log.Fatal("word not found")
	}

	fmt.Println("Synonyms:", entry.Synonyms)
	fmt.Println("Antonyms:", entry.Antonyms)
}

Output:

Synonyms: [glad joyful felicitous cheerful ...]
Antonyms: [unhappy sad]

API

func Lookup(word string) (Entry, bool)

Returns:

type Entry struct {
	Synonyms []string
	Antonyms []string
}

If the word does not exist in the dataset:

entry, ok := thesaurus.Lookup("xyznotaword")

// ok == false

func WordsWithPrefix(prefix string) []string

Every known word starting with prefix (case-insensitive), sorted:

thesaurus.WordsWithPrefix("happ") // ["happen", "happening", "happily", "happy", ...]

func Contains(word string) bool

Reports whether word has an entry, without needing the full Entry:

thesaurus.Contains("happy") // true

func Count() int

Total number of distinct words the package can look up (45,695 as of the current dataset).

func AllWords() []string

Every known word, sorted. Returns a copy — safe to mutate.

CLI Tool

cmd/thesaurus is a small example CLI over the package's own API — stdlib only, no dependencies:

go install github.com/bobadilla-tech/thesaurus-go/cmd/thesaurus@latest

$ thesaurus lookup happy
Synonyms: [joyful cheerful content pleased delighted glad elated blissful]
Antonyms: [sad unhappy miserable sorrowful dejected gloomy melancholy]

$ thesaurus prefix happ
happen
happening
happenstance
happily
happiness
happy

$ thesaurus count
45695

How It Works

1. Normalize: input words are trimmed and converted to lowercase.
2. Curated lookup: a small hand-maintained dataset is checked first. Curated entries always take precedence over OEWN.
3. OEWN fallback: if the word is not present in the curated dataset, synonyms and antonyms are resolved from the embedded Open English WordNet indexes.
4. Embedded data: the generated JSON indexes are gzip-compressed and embedded into the binary using go:embed.

Regenerating the Dataset

The repository includes a build-time preprocessor located in cmd/datasetbuild. Data sources are pluggable through a Provider interface (see cmd/datasetbuild/provider.go) — oewn is the only one implemented today, but adding another means implementing Provider and registering it, with no changes to main().

The oewn provider parses the official Open English WordNet XML (GWN-LMF format) and generates the compressed JSON files embedded by the package.

Example:

go run ./cmd/datasetbuild \
  -input english-wordnet-2025.xml \
  -output-dir ./dataset \
  -provider oewn

-provider defaults to oewn. This command generates:

• synonyms_oewn.json.gz
• antonyms_oewn.json.gz

Both live in dataset/, alongside the hand-maintained curated.json, and are consumed automatically through go:embed.

Benchmarks & Design Notes

• FST (vellum) spike — evaluated github.com/blevesearch/vellum as an alternative lookup backend. Rejected: 12.6x slower on steady-state point lookup (map: 22ns/op, 0 allocs vs FST: 277ns/op, 1 alloc), wash-to-worse on embedded artifact size. Full writeup and prototype on the spike/vellum-fst branch, not merged — see docs/fst-benchmark.md on that branch.

Testing

Run the tests:

go test -v ./...

Used in Production

This package powers the Thesaurus endpoint on Requiems API, an all-in-one backend API for SaaS products (auth, fraud detection, payments intelligence, global data, data integrity).

• Full API docs: https://requiems.xyz/en/apis
• Systems overview: https://requiems.xyz/en/systems

Need more language tooling? Requiems API's Text & Language system also provides dictionary lookups, spell checking, language detection, sentiment analysis, text similarity, and more through a single API.

License

This project is licensed under the MIT License.

Credits

• Word data derived from Open English WordNet (OEWN).
• Open English WordNet is developed by the Global WordNet Association and distributed under the CC BY 4.0 License.