jsonapi

package
v0.0.0-...-9031c82 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 4, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ISO8601TimeFormat = "2006-01-02T15:04:05.999Z"

	// MediaType is the identifier for the JSON API media type
	//
	// see http://jsonapi.org/format/#document-structure
	MediaType = "application/vnd.api+json"

	// KeyFirstPage is the key to the links object whose value contains a link to
	// the first page of data
	KeyFirstPage = "first"
	// KeyLastPage is the key to the links object whose value contains a link to
	// the last page of data
	KeyLastPage = "last"
	// KeyPreviousPage is the key to the links object whose value contains a link
	// to the previous page of data
	KeyPreviousPage = "prev"
	// KeyNextPage is the key to the links object whose value contains a link to
	// the next page of data
	KeyNextPage = "next"

	// QueryParamPageNumber is a JSON API query parameter used in a page based
	// pagination strategy in conjunction with QueryParamPageSize
	QueryParamPageNumber = "page[number]"
	// QueryParamPageSize is a JSON API query parameter used in a page based
	// pagination strategy in conjunction with QueryParamPageNumber
	QueryParamPageSize = "page[size]"

	// QueryParamPageOffset is a JSON API query parameter used in an offset based
	// pagination strategy in conjunction with QueryParamPageLimit
	QueryParamPageOffset = "page[offset]"
	// QueryParamPageLimit is a JSON API query parameter used in an offset based
	// pagination strategy in conjunction with QueryParamPageOffset
	QueryParamPageLimit = "page[limit]"

	// QueryParamPageCursor is a JSON API query parameter used with a cursor-based
	// strategy
	QueryParamPageCursor = "page[cursor]"

	// KeySelfLink is the key within a top-level links object that denotes the link that
	// generated the current response document.
	KeySelfLink = "self"
)

Variables

View Source 
var (
	// ErrInvalidTime is returned when a struct has a time.Time type field, but
	// the JSON value was not a unix timestamp integer.
	ErrInvalidTime = errors.New("Only numbers can be parsed as dates, unix timestamps")
	// ErrInvalidISO8601 is returned when a struct has a time.Time type field and includes
	// "iso8601" in the tag spec, but the JSON value was not an ISO8601 timestamp string.
	ErrInvalidISO8601 = errors.New("Only strings can be parsed as dates, ISO8601 timestamps")
	// ErrInvalidRFC3339 is returned when a struct has a time.Time type field and includes
	// "rfc3339" in the tag spec, but the JSON value was not an RFC3339 timestamp string.
	ErrInvalidRFC3339 = errors.New("Only strings can be parsed as dates, RFC3339 timestamps")
	// ErrInvalidDateFormat is returned when a struct has a time.Time type field and includes
	// "fmt:date" in the tag spec, but the JSON value was not a date string (YYYY-MM-DD).
	ErrInvalidDateFormat = errors.New("Only strings can be parsed as dates, format: YYYY-MM-DD")
	// ErrInvalidTimeFormat is returned when a struct has a time.Time type field and includes
	// "fmt:time" in the tag spec, but the JSON value was not a time string (HH:MM:SS).
	ErrInvalidTimeFormat = errors.New("Only strings can be parsed as times, format: HH:MM:SS")
	// ErrUnknownFieldNumberType is returned when the JSON value was a float
	// (numeric) but the Struct field was a non numeric type (i.e. not int, uint,
	// float, etc)
	ErrUnknownFieldNumberType = errors.New("The struct field was not of a known number type")
	// ErrInvalidType is returned when the given type is incompatible with the expected type.
	ErrInvalidType = errors.New("Invalid type provided") // I wish we used punctuation.
	// ErrTypeNotFound is returned when the given type not found on the model.
	ErrTypeNotFound = errors.New("no primary type annotation found on model")
)
View Source 
var (
	// ErrBadJSONAPIStructTag is returned when the Struct field's JSON API
	// annotation is invalid.
	ErrBadJSONAPIStructTag = errors.New("Bad jsonapi struct tag format")
	// ErrBadJSONAPIID is returned when the Struct JSON API annotated "id" field
	// was not a valid numeric type.
	ErrBadJSONAPIID = errors.New(
		"id should be either string, int(8,16,32,64) or uint(8,16,32,64)")
	// ErrExpectedSlice is returned when a variable or argument was expected to
	// be a slice of *Structs; MarshalMany will return this error when its
	// interface{} argument is invalid.
	ErrExpectedSlice = errors.New("models should be a slice of struct pointers")
	// ErrUnexpectedType is returned when marshalling an interface; the interface
	// had to be a pointer or a slice; otherwise this error is returned.
	ErrUnexpectedType = errors.New("models should be a struct pointer or slice of struct pointers")
	// ErrUnexpectedNil is returned when a slice of relation structs contains nil values
	ErrUnexpectedNil = errors.New("slice of struct pointers cannot contain nil")
)

Functions

func MarshalErrors 

func MarshalErrors(w io.Writer, errorObjects []*ErrorObject) error

MarshalErrors writes a JSON API response using the given `[]error`.

For more information on JSON API error payloads, see the spec here: http://jsonapi.org/format/#document-top-level and here: http://jsonapi.org/format/#error-objects.

func MarshalManyPayloads 

func MarshalManyPayloads[T any](w io.Writer, models ListResponse[T], opts ...MarshalOption) error

func MarshalOnePayloadEmbedded 

func MarshalOnePayloadEmbedded(w io.Writer, model interface{}) error

MarshalOnePayloadEmbedded - This method not meant to for use in implementation code, although feel free. The purpose of this method is for use in tests. In most cases, your request payloads for create will be embedded rather than sideloaded for related records. This method will serialize a single struct pointer into an embedded json response. In other words, there will be no, "included", array in the json all relationships will be serailized inline in the data.

However, in tests, you may want to construct payloads to post to create methods that are embedded to most closely resemble the payloads that will be produced by the client. This is what this method is intended for.

model interface{} should be a pointer to a struct.

func MarshalPayload 

func MarshalPayload[T any](w io.Writer, models T, opts ...MarshalOption) error

MarshalPayload writes a jsonapi response for one or many records. The related records are sideloaded into the "included" array. If this method is given a struct pointer as an argument it will serialize in the form "data": {...}. If this method is given a slice of pointers, this method will serialize in the form "data": [...]

One Example: you could pass it, w, your http.ResponseWriter, and, models, a ptr to a Blog to be written to the response body: 

 func ShowBlog(w http.ResponseWriter, r *http.Request) {
	 blog := &Blog{}

	 w.Header().Set("Content-Type", jsonapi.MediaType)
	 w.WriteHeader(http.StatusOK)

	 if err := jsonapi.MarshalPayload(w, blog); err != nil {
		 http.Error(w, err.Error(), http.StatusInternalServerError)
	 }
 }

Many Example: you could pass it, w, your http.ResponseWriter, and, models, a slice of Blog struct instance pointers to be written to the response body: 

	 func ListBlogs(w http.ResponseWriter, r *http.Request) {
    blogs := []*Blog{}

		 w.Header().Set("Content-Type", jsonapi.MediaType)
		 w.WriteHeader(http.StatusOK)

		 if err := jsonapi.MarshalPayload(w, blogs); err != nil {
			 http.Error(w, err.Error(), http.StatusInternalServerError)
		 }
	 }

Types

type ErrUnsupportedPtrType 

type ErrUnsupportedPtrType struct {
	// contains filtered or unexported fields
}

ErrUnsupportedPtrType is returned when the Struct field was a pointer but the JSON value was of a different type

func (ErrUnsupportedPtrType) Error 

func (eupt ErrUnsupportedPtrType) Error() string

type ErrorObject 

type ErrorObject struct {
	// ID is a unique identifier for this particular occurrence of a problem.
	ID string `json:"id,omitempty"`

	// Title is a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
	Title string `json:"title,omitempty"`

	// Detail is a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
	Detail string `json:"detail,omitempty"`

	// Status is the HTTP status code applicable to this problem, expressed as a string value.
	Status string `json:"status,omitempty"`

	// Code is an application-specific error code, expressed as a string value.
	Code string `json:"code,omitempty"`

	// Source is an object containing references to the primary source of the error.
	Source *ErrorSource `json:"source,omitempty"`

	// Meta is an object containing non-standard meta-information about the error.
	Meta *map[string]interface{} `json:"meta,omitempty"`
}

ErrorObject is an `Error` implementation as well as an implementation of the JSON API error object.

The main idea behind this struct is that you can use it directly in your code as an error type and pass it directly to `MarshalErrors` to get a valid JSON API errors payload. For more information on Golang errors, see: https://golang.org/pkg/errors/ For more information on the JSON API spec's error objects, see: http://jsonapi.org/format/#error-objects

func UnmarshalErrors 

func UnmarshalErrors(reader io.Reader) ([]*ErrorObject, error)

UnmarshalErrors reads a JSON API error payload into a slice of ErrorObject.

func (*ErrorObject) Error 

func (e *ErrorObject) Error() string

Error implements the `Error` interface.

type ErrorSource 

type ErrorSource struct {
	// Pointer is a JSON Pointer (RFC6901) indicating the value in the request document that caused the error.
	Pointer string `json:"pointer,omitempty"`

	// Parameter is a string indicating which query or path parameter caused the error.
	Parameter string `json:"parameter,omitempty"`

	// Header is a string indicating the name of a single request header which caused the error.
	Header string `json:"header,omitempty"`
}

ErrorSource is an object containing references to the primary source of the error. Only one field should be populated depending on the source of the error.

type ErrorsPayload 

type ErrorsPayload struct {
	Spec   *Spec          `json:"jsonapi,omitempty"`
	Errors []*ErrorObject `json:"errors"`
}

ErrorsPayload is a serializer struct for representing a valid JSON API errors payload. 

type Link struct {
	Href string `json:"href"`
	Meta Meta   `json:"meta,omitempty"`
}

Link is used to represent a member of the `links` object.

type Linkable 

type Linkable interface {
	JSONAPILinks() *Links
}

Linkable is used to include document links in response data e.g. {"self": "http://example.com/posts/1"} 

type Links map[string]interface{}

Links is used to represent a `links` object. http://jsonapi.org/format/#document-links

type ListResponse 

type ListResponse[T any] interface {
	Results() []T
}

type ManyPayload 

type ManyPayload struct {
	Spec     *Spec   `json:"jsonapi,omitempty"`
	Data     []*Node `json:"data"`
	Included []*Node `json:"included,omitempty"`
	Links    *Links  `json:"links,omitempty"`
	Meta     *Meta   `json:"meta,omitempty"`
}

ManyPayload is used to represent a generic JSON API payload where many resources (Nodes) were included in an [] in the "data" key

type MarshalHook 

type MarshalHook interface {
	// BeforeMarshal is called before an object is marshalled to JSON
	// If it returns an error, marshalling will be aborted
	BeforeMarshal() error
}

MarshalHook defines the interface for objects that provide BeforeMarshal hooks

type MarshalOption 

type MarshalOption func(*MarshalOptions)

MarshalOption is a function that modifies MarshalOptions

func WithInclude 

func WithInclude(relations ...string) MarshalOption

WithInclude specifies which relationships to include in the response

type MarshalOptions 

type MarshalOptions struct {
	// IncludeRelations is a list of relationship names to include in the response.
	// If empty, all relationships will be included.
	// If non-empty, only the relationships specified will be included.
	// Supports dot notation for nested relationships (e.g., "author.comments")
	IncludeRelations []string
}

MarshalOptions contains options for the Marshal functions

type Meta 

type Meta map[string]interface{}

Meta is used to represent a `meta` object. http://jsonapi.org/format/#document-meta

type Metable 

type Metable interface {
	JSONAPIMeta() *Meta
}

Metable is used to include document meta in response data e.g. {"foo": "bar"}

type Node 

type Node struct {
	Type          string                 `json:"type"`
	ID            string                 `json:"id,omitempty"`
	ClientID      string                 `json:"client-id,omitempty"`
	Attributes    map[string]interface{} `json:"attributes,omitempty"`
	Relationships map[string]interface{} `json:"relationships,omitempty"`
	Links         *Links                 `json:"links,omitempty"`
	Meta          *Meta                  `json:"meta,omitempty"`
}

Node is used to represent a generic JSON API Resource

type NullableAttr 

type NullableAttr[T any] map[bool]T

NullableAttr is a generic type, which implements a field that can be one of three states:

- field is not set in the request - field is explicitly set to `null` in the request - field is explicitly set to a valid value in the request

NullableAttr is intended to be used with JSON marshalling and unmarshalling. This is generally useful for PATCH requests, where attributes with zero values are intentionally not marshaled into the request payload so that existing attribute values are not overwritten.

Internal implementation details:

- map[true]T means a value was provided - map[false]T means an explicit null was provided - nil or zero map means the field was not provided

If the field is expected to be optional, add the `omitempty` JSON tags. Do NOT use `*NullableAttr`!

Adapted from https://www.jvt.me/posts/2024/01/09/go-json-nullable/

func NewNullNullableAttr 

func NewNullNullableAttr[T any]() NullableAttr[T]

NewNullNullableAttr is a convenience helper to allow constructing a NullableAttr with an explicit `null`, for instance to construct a field inside a struct without introducing an intermediate variable

func NewNullableAttrWithValue 

func NewNullableAttrWithValue[T any](t T) NullableAttr[T]

NewNullableAttrWithValue is a convenience helper to allow constructing a NullableAttr with a given value, for instance to construct a field inside a struct without introducing an intermediate variable.

func (NullableAttr[T]) Get 

func (t NullableAttr[T]) Get() (T, error)

Get retrieves the underlying value, if present, and returns an error if the value was not present

func (NullableAttr[T]) IsNull 

func (t NullableAttr[T]) IsNull() bool

IsNull indicate whether the field was sent, and had a value of `null`

func (NullableAttr[T]) IsSpecified 

func (t NullableAttr[T]) IsSpecified() bool

IsSpecified indicates whether the field was sent

func (*NullableAttr[T]) Set 

func (t *NullableAttr[T]) Set(value T)

Set sets the underlying value to a given value

func (*NullableAttr[T]) SetInterface 

func (t *NullableAttr[T]) SetInterface(value interface{})

Set sets the underlying value to a given value

func (*NullableAttr[T]) SetNull 

func (t *NullableAttr[T]) SetNull()

SetNull sets the value to an explicit `null`

func (*NullableAttr[T]) SetUnspecified 

func (t *NullableAttr[T]) SetUnspecified()

SetUnspecified sets the value to be absent from the serialized payload

type NullableRelationship 

type NullableRelationship[T any] map[bool]T

NullableRelationship is a generic type, which implements a field that can be one of three states:

- relationship is not set in the request - relationship is explicitly set to `null` in the request - relationship is explicitly set to a valid relationship value in the request

NullableRelationship is intended to be used with JSON marshalling and unmarshalling. This is generally useful for PATCH requests, where relationships with zero values are intentionally not marshaled into the request payload so that existing attribute values are not overwritten.

Internal implementation details:

- map[true]T means a value was provided - map[false]T means an explicit null was provided - nil or zero map means the field was not provided

If the relationship is expected to be optional, add the `omitempty` JSON tags. Do NOT use `*NullableRelationship`!

Slice types are not currently supported for NullableRelationships as the nullable nature can be expressed via empty array `polyrelation` JSON tags are NOT currently supported.

NullableRelationships must have an inner type of pointer:

- NullableRelationship[*Comment] - valid - NullableRelationship[[]*Comment] - invalid - NullableRelationship[Comment] - invalid

func NewNullNullableRelationship 

func NewNullNullableRelationship[T any]() NullableRelationship[T]

NewNullNullableRelationship is a convenience helper to allow constructing a NullableRelationship with an explicit `null`, for instance to construct a field inside a struct without introducing an intermediate variable

func NewNullableRelationshipWithValue 

func NewNullableRelationshipWithValue[T any](t T) NullableRelationship[T]

NewNullableRelationshipWithValue is a convenience helper to allow constructing a NullableRelationship with a given value, for instance to construct a field inside a struct without introducing an intermediate variable.

func (NullableRelationship[T]) Get 

func (t NullableRelationship[T]) Get() (T, error)

Get retrieves the underlying value, if present, and returns an error if the value was not present

func (NullableRelationship[T]) IsNull 

func (t NullableRelationship[T]) IsNull() bool

IsNull indicates whether the field was sent, and had a value of `null`

func (NullableRelationship[T]) IsSpecified 

func (t NullableRelationship[T]) IsSpecified() bool

IsSpecified indicates whether the field was sent

func (*NullableRelationship[T]) Set 

func (t *NullableRelationship[T]) Set(value T)

Set sets the underlying value to a given value

func (*NullableRelationship[T]) SetInterface 

func (t *NullableRelationship[T]) SetInterface(value interface{})

SetInterface sets the underlying value from an empty interface, performing a type assertion to T.

func (*NullableRelationship[T]) SetNull 

func (t *NullableRelationship[T]) SetNull()

SetNull sets the value to an explicit `null`

func (*NullableRelationship[T]) SetUnspecified 

func (t *NullableRelationship[T]) SetUnspecified()

SetUnspecified sets the value to be absent from the serialized payload

type OnePayload 

type OnePayload struct {
	Spec     *Spec   `json:"jsonapi,omitempty"`
	Data     *Node   `json:"data"`
	Included []*Node `json:"included,omitempty"`
	Links    *Links  `json:"links,omitempty"`
	Meta     *Meta   `json:"meta,omitempty"`
}

OnePayload is used to represent a generic JSON API payload where a single resource (Node) was included as an {} in the "data" key

type Payloader 

type Payloader interface {
	// contains filtered or unexported methods
}

Payloader is used to encapsulate the One and Many payload types

func Marshal 

func Marshal[T any](model T, opts ...MarshalOption) (Payloader, error)

Marshal does the same as MarshalPayload except it just returns the payload and doesn't write out results. Useful if you use your own JSON rendering library.

func MarshalMany 

func MarshalMany[T any](models ListResponse[T], opts ...MarshalOption) (Payloader, error)

type RelationshipLinkable 

type RelationshipLinkable interface {
	// JSONAPIRelationshipLinks will be invoked for each relationship with the corresponding relation name (e.g. `comments`)
	JSONAPIRelationshipLinks(relation string) *Links
}

RelationshipLinkable is used to include relationship links in response data e.g. {"related": "http://example.com/posts/1/comments"}

type RelationshipManyNode 

type RelationshipManyNode struct {
	Data  []*Node `json:"data"`
	Links *Links  `json:"links,omitempty"`
	Meta  *Meta   `json:"meta,omitempty"`
}

RelationshipManyNode is used to represent a generic has many JSON API relation

type RelationshipMetable 

type RelationshipMetable interface {
	// JSONRelationshipMeta will be invoked for each relationship with the corresponding relation name (e.g. `comments`)
	JSONAPIRelationshipMeta(relation string) *Meta
}

RelationshipMetable is used to include relationship meta in response data

type RelationshipOneNode 

type RelationshipOneNode struct {
	Data  *Node  `json:"data"`
	Links *Links `json:"links,omitempty"`
	Meta  *Meta  `json:"meta,omitempty"`
}

RelationshipOneNode is used to represent a generic has one JSON API relation

type Spec 

type Spec struct {
	Version    string   `json:"version,omitempty"`
	Extensions []string `json:"ext,omitempty"`
	Profiles   []string `json:"profile,omitempty"`
	Metadata   Meta     `json:"meta,omitempty"`
}

type UnmarshalHook 

type UnmarshalHook interface {
	// AfterUnmarshal is called after an object is unmarshalled from JSON
	// If it returns an error, unmarshalling will be aborted
	AfterUnmarshal() error
}

UnmarshalHook defines the interface for objects that provide AfterUnmarshal hooks

type UnmarshalResult 

type UnmarshalResult[T any] struct {
	Data T
	Meta any
}

func UnmarshalManyPayload 

func UnmarshalManyPayload[T any](in io.Reader) (*UnmarshalResult[[]T], error)

UnmarshalManyPayload converts an io into a set of struct instances using jsonapi tags on the type's struct fields.

func UnmarshalPayload 

func UnmarshalPayload[T any](in io.Reader) (*UnmarshalResult[T], error)

UnmarshalPayload converts an io into a struct instance using jsonapi tags on struct fields. This method supports single request payloads only, at the moment. Bulk creates and updates are not supported yet.

Will Unmarshal embedded and sideloaded payloads. The latter is only possible if the object graph is complete. That is, in the "relationships" data there are type and id, keys that correspond to records in the "included" array.

For example you could pass it, in, req.Body and, model, a BlogPost struct instance to populate in an http handler, 

func CreateBlog(w http.ResponseWriter, r *http.Request) {
	blog := new(Blog)

	if err := jsonapi.UnmarshalPayload(r.Body, blog); err != nil {
		http.Error(w, err.Error(), 500)
		return
	}

	// ...do stuff with your blog...

	w.Header().Set("Content-Type", jsonapi.MediaType)
	w.WriteHeader(201)

	if err := jsonapi.MarshalPayload(w, blog); err != nil {
		http.Error(w, err.Error(), 500)
	}
}

Visit https://github.com/google/jsonapi#create for more info.

model interface{} should be a pointer to a struct.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.