Skip to content

CLAUDE.md

Latest commit

 

History

History
52 lines (39 loc) · 2.73 KB

CLAUDE.md

File metadata and controls

52 lines (39 loc) · 2.73 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Go implementation of JSON Reference (RFC 3986-based URI references with JSON Pointer fragments). JSON References are used extensively in OpenAPI and JSON Schema specifications to express $ref links between documents and within a single document.

The Ref type parses a reference string into its URL and JSON Pointer components, classifies it (full URL, path-only, fragment-only, file scheme), and supports inheritance (resolving a child reference against a parent).

See docs/MAINTAINERS.md for CI/CD, release process, and repo structure details.

Package layout (single package)

File Contents
reference.go Ref type, constructors (New, MustCreateRef), accessors (GetURL, GetPointer, String), classification (IsRoot, IsCanonical), and Inherits for parent-child resolution
internal/normalize_url.go URL normalization (lowercase scheme/host, remove default ports, deduplicate slashes) — replaces the deprecated purell library

Key API

  • Ref — the core type representing a parsed JSON Reference
  • New(string) (Ref, error) — parse a JSON Reference string
  • MustCreateRef(string) Ref — parse or panic
  • (*Ref).GetURL() *url.URL — the underlying URL
  • (*Ref).GetPointer() *jsonpointer.Pointer — the JSON Pointer fragment
  • (*Ref).Inherits(child Ref) (*Ref, error) — resolve a child reference against this parent
  • (*Ref).IsRoot() bool — true if this is a root document reference
  • (*Ref).IsCanonical() bool — true if the reference starts with http(s):// or file://

Dependencies

  • github.com/go-openapi/jsonpointer — JSON Pointer (RFC 6901) implementation
  • github.com/go-openapi/testify/v2 — test-only assertions (zero-dep testify fork)

Notable design decisions

  • Replaced purell with internal normalization — the internal/normalize_url.go file replaces the unmaintained purell library. It performs only the safe normalizations that were previously used: lowercase scheme/host, remove default HTTP(S) ports, and deduplicate path slashes.
  • Classification flags on Ref — rather than re-parsing on each query, the parse method sets boolean flags (HasFullURL, HasURLPathOnly, HasFragmentOnly, HasFileScheme, HasFullFilePath) once at construction time.
  • JSON Pointer errors are silently ignored — if the URL fragment is not a valid JSON Pointer, the pointer is left as zero-value. This allows the type to represent any URI reference, not just those with valid JSON Pointer fragments.