doc: add portable agentic instructions (#86) · go-openapi/jsonreference@839f84e (original) (raw)
``
1
`+
CLAUDE.md
`
``
2
+
``
3
`+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
`
``
4
+
``
5
`+
Project Overview
`
``
6
+
``
7
`+
Go implementation of JSON Reference
`
``
8
`+
(RFC 3986-based URI references with JSON Pointer fragments). JSON References are used
`
``
9
`` +
extensively in OpenAPI and JSON Schema specifications to express $ref links between
``
``
10
`+
documents and within a single document.
`
``
11
+
``
12
`` +
The Ref type parses a reference string into its URL and JSON Pointer components, classifies
``
``
13
`+
it (full URL, path-only, fragment-only, file scheme), and supports inheritance (resolving a
`
``
14
`+
child reference against a parent).
`
``
15
+
``
16
`+
See docs/MAINTAINERS.md for CI/CD, release process, and repo structure details.
`
``
17
+
``
18
`+
Package layout (single package)
`
``
19
+
``
20
`+
| File | Contents |
`
``
21
`+
|------|----------|
`
``
22
`` +
| reference.go | Ref type, constructors (New, MustCreateRef), accessors (GetURL, GetPointer, String), classification (IsRoot, IsCanonical), and Inherits for parent-child resolution |
``
``
23
`` +
| internal/normalize_url.go | URL normalization (lowercase scheme/host, remove default ports, deduplicate slashes) — replaces the deprecated purell library |
``
``
24
+
``
25
`+
Key API
`
``
26
+
``
27
`` +
Ref— the core type representing a parsed JSON Reference
``
``
28
`` +
New(string) (Ref, error)— parse a JSON Reference string
``
``
29
`` +
MustCreateRef(string) Ref— parse or panic
``
``
30
`` +
(*Ref).GetURL() *url.URL— the underlying URL
``
``
31
`` +
(*Ref).GetPointer() *jsonpointer.Pointer— the JSON Pointer fragment
``
``
32
`` +
(*Ref).Inherits(child Ref) (*Ref, error)— resolve a child reference against this parent
``
``
33
`` +
(*Ref).IsRoot() bool— true if this is a root document reference
``
``
34
`` +
(*Ref).IsCanonical() bool— true if the reference starts withhttp(s)://orfile://
``
``
35
+
``
36
`+
Dependencies
`
``
37
+
``
38
`` +
github.com/go-openapi/jsonpointer— JSON Pointer (RFC 6901) implementation
``
``
39
`` +
github.com/go-openapi/testify/v2— test-only assertions (zero-dep testify fork)
``
``
40
+
``
41
`+
Notable design decisions
`
``
42
+
``
43
`` +
- Replaced
purellwith internal normalization — theinternal/normalize_url.gofile
``
``
44
`` +
replaces the unmaintained purell library. It performs only the safe normalizations that
``
``
45
`+
were previously used: lowercase scheme/host, remove default HTTP(S) ports, and deduplicate
`
``
46
`+
path slashes.
`
``
47
`` +
- Classification flags on
Ref— rather than re-parsing on each query, theparsemethod
``
``
48
`` +
sets boolean flags (HasFullURL, HasURLPathOnly, HasFragmentOnly, HasFileScheme,
``
``
49
`` +
HasFullFilePath) once at construction time.
``
``
50
`+
- JSON Pointer errors are silently ignored — if the URL fragment is not a valid JSON Pointer,
`
``
51
`+
the pointer is left as zero-value. This allows the type to represent any URI reference, not
`
``
52
`+
just those with valid JSON Pointer fragments.
`