From 4c0c95f1bc15f3aea7a2b53200fa04abc4c86adb Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sun, 8 Mar 2026 18:52:36 +0100 Subject: [PATCH] doc: added instructions for claude and copilot Signed-off-by: Frederic BIDON --- .claude/CLAUDE.md | 54 ++++++++++++++++++--------------- .github/copilot-instructions.md | 18 ++++++++--- 2 files changed, 42 insertions(+), 30 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 6dd8d33..9f6ac06 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -4,41 +4,45 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -Go implementation of [JSON Pointer (RFC 6901)](https://datatracker.ietf.org/doc/html/rfc6901) for navigating -and mutating JSON documents represented as Go values. Unlike most implementations, it works not only with -`map[string]any` and slices, but also with Go structs (resolved via `json` struct tags and reflection). +Go library for validating OpenAPI v2 (Swagger) specifications and JSON Schema draft 4 data. +It is part of the [go-openapi](https://github.com/go-openapi) ecosystem and used by [go-swagger](https://github.com/go-swagger/go-swagger). + +The library provides two main capabilities: +1. **Spec validation** — validates a Swagger 2.0 spec document against the JSON meta-schema, plus extra semantic rules (path uniqueness, parameter consistency, $ref resolution, etc.) +2. **Schema validation** — validates arbitrary data against a JSON Schema draft 4 schema (tested against the official JSON-Schema-Test-Suite) + +API is stable. This is legacy/maintenance code — deep refactoring is not worthwhile; +a ground-up replacement is the long-term plan. See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, and repo structure details. -### Package layout (single package) +### Package layout -| File | Contents | -|------|----------| -| `pointer.go` | Core types (`Pointer`, `JSONPointable`, `JSONSetable`), `New`, `Get`, `Set`, `Offset`, `Escape`/`Unescape` | -| `errors.go` | Sentinel errors: `ErrPointer`, `ErrInvalidStart`, `ErrUnsupportedValueType` | +| Package | Contents | +|---------|----------| +| `validate` (root) | Spec validator (`SpecValidator`), schema validator (`SchemaValidator`), `AgainstSchema()`, individual type/format/object/slice/string/number validators, result handling, pools | +| `post` | Post-validation transforms: `ApplyDefaults` (fills in schema defaults) and `Prune` (removes additional properties) | ### Key API -- `New(string) (Pointer, error)` — parse a JSON pointer string (e.g. `"/foo/0/bar"`) -- `Pointer.Get(document any) (any, reflect.Kind, error)` — retrieve a value -- `Pointer.Set(document, value any) (any, error)` — set a value (document must be pointer/map/slice) -- `Pointer.Offset(jsonString string) (int64, error)` — byte offset of token in raw JSON -- `GetForToken` / `SetForToken` — single-level convenience helpers -- `Escape` / `Unescape` — RFC 6901 token escaping (`~0` ↔ `~`, `~1` ↔ `/`) - -Custom types can implement `JSONPointable` (for Get) or `JSONSetable` (for Set) to bypass reflection. +- `Spec(doc, formats) error` — high-level spec validation +- `NewSpecValidator(schema, formats) *SpecValidator` — configurable spec validator +- `AgainstSchema(schema, data, formats, ...Option) error` — validate data against a JSON schema +- `NewSchemaValidator(schema, root, path, formats, ...Option) *SchemaValidator` — configurable schema validator +- `post.ApplyDefaults(result)` — apply default values from validation result +- `post.Prune(result)` — remove undeclared properties from validation result ### Dependencies -- `github.com/go-openapi/swag/jsonname` — struct tag → JSON field name resolution -- `github.com/go-openapi/testify/v2` — test-only assertions - -### Notable historical design decisions +Key runtime dependencies (see `go.mod` for full list): +- `github.com/go-openapi/spec` — Swagger 2.0 spec model +- `github.com/go-openapi/analysis` — spec analysis and flattening +- `github.com/go-openapi/loads` — spec loading (used in tests/examples) +- `github.com/go-openapi/errors` — structured validation errors +- `github.com/go-openapi/strfmt` — format registry (date-time, uuid, email, etc.) +- `github.com/go-openapi/testify/v2` — test-only assertions (zero-dep testify fork) -See also .claude/plans/ROADMAP.md. +### Architecture notes -- Struct fields **must** have a `json` tag to be reachable; untagged fields are ignored - (differs from `encoding/json` which defaults to the Go field name). -- Anonymous embedded struct fields are traversed only if tagged. -- The RFC 6901 `"-"` array suffix (append) is **not** implemented. +The validator chain is built from `valueValidator` implementations (type, format, string, number, slice, object, common, schemaProps), assembled by `SchemaValidator`. Validators and results are pooled for performance (`pools.go`). The codebase has known complexity issues (many `//nolint:gocognit` deferrals) stemming from the original design. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7f405f1..ae0a14b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,19 +2,27 @@ ## Project Overview -Go implementation of a OpenAPI v2 (swagger) validator and JSON Schema draft 4 validator +Go library for validating OpenAPI v2 (Swagger) specifications and JSON Schema draft 4 data. +Part of the [go-openapi](https://github.com/go-openapi) ecosystem. API is stable; maintenance-only. -## Package Layout (single package) +## Package Layout -| File | Contents | -|------|----------| +| Package | Contents | +|---------|----------| +| `validate` (root) | Spec validator, schema validator, type/format/object/slice/string/number validators, result handling, pools | +| `post` | Post-validation transforms: `ApplyDefaults` and `Prune` | ## Key API -## Design Decisions +- `Spec(doc, formats) error` — high-level spec validation +- `AgainstSchema(schema, data, formats, ...Option) error` — validate data against a JSON schema +- `NewSchemaValidator(schema, root, path, formats, ...Option) *SchemaValidator` +- `post.ApplyDefaults(result)` / `post.Prune(result)` ## Dependencies +- `github.com/go-openapi/spec`, `analysis`, `loads`, `errors`, `strfmt` + ## Conventions - All `.go` files must have SPDX license headers (Apache-2.0).