jsonreference

README

jsonreference

---

An implementation of JSON Reference for golang.

Announcements

• 2025-12-19 : new community chat on discord
  • a new discord community channel is available to be notified of changes and support users
  • our venerable Slack channel remains open, and will be eventually discontinued on 2026-03-31

You may join the discord community by clicking the invite link on the discord badge (also above).

Or join our Slack channel:

Status

API is stable.

Import this library in your project

go get github.com/go-openapi/jsonreference

Dependencies

• https://github.com/go-openapi/jsonpointer

Basic usage

// Creating a new reference
ref, err := jsonreference.New("http://example.com/doc.json#/definitions/Pet")

// Fragment-only reference
fragRef := jsonreference.MustCreateRef("#/definitions/Pet")

// Resolving references
parent, _ := jsonreference.New("http://example.com/base.json")
child, _ := jsonreference.New("#/definitions/Pet")
resolved, _ := parent.Inherits(child)
// Result: "http://example.com/base.json#/definitions/Pet"

Change log

See https://github.com/go-openapi/jsonreference/releases

References

• http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07
• http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03

Licensing

This library ships under the SPDX-License-Identifier: Apache-2.0.

See the license NOTICE, which recalls the licensing terms of all the pieces of software on top of which it has been built.

Other documentation

• All-time contributors
• Contributing guidelines
• Maintainers documentation
• Code style

Cutting a new release

Maintainers can cut a new release by either:

• running this workflow
• or pushing a semver tag
  • signed tags are preferred
  • The tag message is prepended to release notes

Documentation

Index

• Variables
• type Ref
  • func MustCreateRef(ref string) Ref
  • func New(jsonReferenceString string) (Ref, error)
  • func (r *Ref) GetPointer() *jsonpointer.Pointer
  • func (r *Ref) GetURL() *url.URL
  • func (r *Ref) Inherits(child Ref) (*Ref, error)
  • func (r *Ref) IsCanonical() bool
  • func (r *Ref) IsRoot() bool
  • func (r *Ref) String() string

Examples

• Ref.GetURL
• Ref.Inherits

Variables

var ErrChildURL = errors.New("child url is nil")

ErrChildURL is raised when there is no child.

Types

type Ref

type Ref struct {
	HasFullURL      bool
	HasURLPathOnly  bool
	HasFragmentOnly bool
	HasFileScheme   bool
	HasFullFilePath bool
	// contains filtered or unexported fields
}

Ref represents a json reference object.

func MustCreateRef

func MustCreateRef(ref string) Ref

MustCreateRef parses the ref string and panics when it's invalid. Use the New method for a version that returns an error.

func New

func New(jsonReferenceString string) (Ref, error)

New creates a new reference for the given string.

func (*Ref) GetPointer

func (r *Ref) GetPointer() *jsonpointer.Pointer

GetPointer gets the json pointer for this reference.

func (*Ref) GetURL

func (r *Ref) GetURL() *url.URL

GetURL gets the URL for this reference.

Example

package main

import (
	"fmt"

	"github.com/go-openapi/jsonreference"
)

func main() {
	fragRef := jsonreference.MustCreateRef("#/definitions/Pet")

	fmt.Printf("URL: %s\n", fragRef.GetURL())

}

Output:

URL: #/definitions/Pet

func (*Ref) Inherits

func (r *Ref) Inherits(child Ref) (*Ref, error)

Inherits creates a new reference from a parent and a child If the child cannot inherit from the parent, an error is returned.

Example

package main

import (
	"fmt"
	"log"

	"github.com/go-openapi/jsonreference"
)

func main() {
	parent := jsonreference.MustCreateRef("http://example.com/base.json")
	child, err := jsonreference.New("#/definitions/Pet")
	if err != nil {
		log.Printf("%v", err)

		return
	}

	resolved, err := parent.Inherits(child)
	if err != nil {
		log.Printf("%v", err)

		return
	}

	fmt.Printf("URL: %v\n", resolved)

}

Output:

URL: http://example.com/base.json#/definitions/Pet

func (*Ref) IsCanonical

func (r *Ref) IsCanonical() bool

IsCanonical returns true when this pointer starts with http(s):// or file://.

func (*Ref) IsRoot

func (r *Ref) IsRoot() bool

IsRoot returns true if this reference is a root document.

func (*Ref) String

func (r *Ref) String() string

String returns the best version of the url for this reference.