Skip to content

copilot-instructions.md

Latest commit

 

History

History
73 lines (57 loc) · 4.3 KB

copilot-instructions.md

File metadata and controls

73 lines (57 loc) · 4.3 KB

Copilot Instructions

Project Overview

Go library that gives first-class Go types to the format keyword from JSON Schema and OpenAPI.

In those specs, format is a string annotation that hints at richer semantics — "date-time", "uuid", "email", "uri", "duration", etc. This package turns each format into a concrete Go type (DateTime, UUID, Email, …) that knows how to validate, parse, and round-trip through JSON, SQL (driver.Valuer/sql.Scanner), text, and BSON encodings. A pluggable Registry lets consumers (code generators, validators, runtime libraries) discover and work with formats generically.

The package is a foundational building block of the go-swagger ecosystem, but is useful anywhere OpenAPI/JSON Schema formats need to travel across serialization boundaries.

This is a mono-repo (go.work) with three modules: root, enable/mongodb, internal/testintegration.

Package Layout

File Contents
ifaces.go Core interfaces: Format (string + text marshaling) and Registry (format registration, validation, parsing)
format.go Default registry, NewFormats(), NewSeededFormats(), NameNormalizer
default.go Simple string-wrapper types: URI, Email, Hostname, IPv4, IPv6, CIDR, MAC, UUID/UUID3-7, ISBN, CreditCard, SSN, HexColor, RGBColor, Password, Base64; validators
date.go Date type (wraps time.Time, RFC3339 full-date)
time.go DateTime type (wraps time.Time, RFC3339 date-time with flexible parsing)
duration.go Duration type (wraps time.Duration, ISO 8601 duration parsing)
ulid.go ULID type (wraps oklog/ulid)
bson.go ObjectId type ([12]byte), hex encoding, no mongo-driver dependency
mongo.go MarshalBSON/UnmarshalBSON for all types via internal/bsonlite codec
errors.go ErrFormat sentinel error
conv/ Pointer helpers: conv.Date(v) → *Date, conv.DateValue(p) → Date, etc.

Key API

  • Format interface — String() + encoding.TextMarshaler / encoding.TextUnmarshaler
  • Registry interface — Add(), DelByName(), GetType(), ContainsName(), Validates(), Parse()
  • Default — global Registry, pre-seeded with all built-in formats
  • Format types — Date, DateTime, Duration, ULID, ObjectId, UUID, Email, URI, Hostname, Base64, …
  • Validators — IsDate(), IsDateTime(), IsDuration(), IsUUID(), IsEmail(), …

Design Decisions

  • Types self-register via init() — importing the package makes all formats available.
  • BSON without mongo-driver — internal/bsonlite provides a minimal codec; enable/mongodb swaps in the real driver.
  • ObjectId is [12]byte, not a string — zero-allocation hex encoding, efficient comparison.
  • DateTime accepts flexible RFC3339 input (with/without fractional seconds, Z vs offset).
  • Duration parses both Go-style (1h30m) and ISO 8601 (P1DT12H) strings.
  • Formatted types carry a swagger:strfmt [format] annotation consumed by go-swagger (see rules).

Dependencies

  • github.com/go-openapi/errors — validation error types
  • github.com/go-viper/mapstructure/v2 — decode hook for format-aware struct mapping
  • github.com/google/uuid — UUID parsing and validation
  • github.com/oklog/ulid/v2 — ULID implementation
  • golang.org/x/net — IDNA hostname validation
  • github.com/go-openapi/testify/v2 — test-only assertions (zero-dep fork of stretchr/testify)

Conventions

  • All .go files must have SPDX license headers (Apache-2.0).
  • Commits require DCO sign-off (git commit -s).
  • Linting: golangci-lint run — config in .golangci.yml (posture: default: all with explicit disables).
  • Every //nolint directive must have an inline comment explaining why.
  • Tests: go test work ./... (mono-repo). CI runs on {ubuntu, macos, windows} x {stable, oldstable} with -race.
  • Test framework: github.com/go-openapi/testify/v2 (not stretchr/testify; testifylint does not work).

See .github/copilot/ (symlinked to .claude/rules/) for detailed rules on Go conventions, linting, testing, and swagger comments.