jsonld

package module
Version: v0.0.0-...-1d862b1 Latest Latest
Warning

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

Go to latest
Published: Jun 15, 2022 License: MIT Imports: 17 Imported by: 11

README

JSON-ld for Go

MIT Licensed Build Status Test Coverage Go Report Card

Basic lib for using activity pub API in Go.

Usage

import "github.com/go-ap/jsonld"

Documentation

Overview

Package jsonld implements encoding and decoding of JSON as defined in RFC 4627. The mapping between JSON and Go values is described in the documentation for the Marshal and Unmarshal functions.

See tagLabel + " and Go" for an introduction to this package: https://golang.org/doc/articles/json_and_go.html

Index

Constants

View Source
const ContentType = `application/ld+json; profile="https://www.w3.org/ns/activitystreams`

ContentType is the content type of JsonLD documents

Variables

Functions

func Marshal

func Marshal(v interface{}) ([]byte, error)

func TagName

func TagName(n string, tag Tag) string

TagName used by structs from the ActivityPub package to Marshal and Unmarshal to/from JSON-LD

func Unmarshal

func Unmarshal(data []byte, v interface{}) error

Unmarshal parses the JSON-encoded data and stores the result in the value pointed to by v. If v is nil or not a pointer, Unmarshal returns an InvalidUnmarshalError.

Unmarshal uses the inverse of the encodings that Marshal uses, allocating maps, slices, and pointers as necessary, with the following additional rules:

To unmarshal JSON into a pointer, Unmarshal first handles the case of the JSON being the JSON literal null. In that case, Unmarshal sets the pointer to nil. Otherwise, Unmarshal unmarshals the JSON into the value pointed at by the pointer. If the pointer is nil, Unmarshal allocates a new value for it to point to.

To unmarshal JSON into a value implementing the Unmarshaler interface, Unmarshal calls that value's UnmarshalJSON method, including when the input is a JSON null. Otherwise, if the value implements encoding.TextUnmarshaler and the input is a JSON quoted string, Unmarshal calls that value's UnmarshalText method with the unquoted form of the string.

To unmarshal JSON into a struct, Unmarshal matches incoming object keys to the keys used by Marshal (either the struct field name or its tag), preferring an exact match but also accepting a case-insensitive match. Unmarshal will only set exported fields of the struct.

To unmarshal JSON into an interface value, Unmarshal stores one of these in the interface value:

bool, for JSON booleans
float64, for JSON numbers
string, for JSON strings
[]interface{}, for JSON arrays
map[string]interface{}, for JSON objects
nil for JSON null

To unmarshal a JSON array into a slice, Unmarshal resets the slice length to zero and then appends each element to the slice. As a special case, to unmarshal an empty JSON array into a slice, Unmarshal replaces the slice with a new empty slice.

To unmarshal a JSON array into a Go array, Unmarshal decodes JSON array elements into corresponding Go array elements. If the Go array is smaller than the JSON array, the additional JSON array elements are discarded. If the JSON array is smaller than the Go array, the additional Go array elements are set to zero values.

To unmarshal a JSON object into a map, Unmarshal first establishes a map to use. If the map is nil, Unmarshal allocates a new map. Otherwise Unmarshal reuses the existing map, keeping existing entries. Unmarshal then stores key-value pairs from the JSON object into the map. The map's key type must either be a string, an integer, or implement encoding.TextUnmarshaler.

If a JSON value is not appropriate for a given target type, or if a JSON number overflows the target type, Unmarshal skips that field and completes the unmarshaling as best it can. If no more serious errors are encountered, Unmarshal returns an UnmarshalTypeError describing the earliest such error. In any case, it's not guaranteed that all the remaining fields following the problematic one will be unmarshaled into the target object.

The JSON null value unmarshals into an interface, map, pointer, or slice by setting that Go value to nil. Because null is often used in JSON to mean “not present,” unmarshaling a JSON null into any other Go type has no effect on the value and produces no error.

When unmarshaling quoted strings, invalid UTF-8 or invalid UTF-16 surrogate pairs are not treated as an error. Instead, they are replaced by the Unicode replacement character U+FFFD.

func Valid

func Valid(data []byte) bool

Valid reports whether data is a valid JSON encoding.

func WithContext

func WithContext(c ...Collapsible) payloadWithContext

WithContext

Types

type Collapsible

type Collapsible interface {
	Collapse() interface{}
}

Collapsible is an interface used by the JSON-LD marshaller to collapse a struct to one single value

type Context

type Context []ContextElement

Context is of of the basic JSON-LD elements. It represents an array of ContextElements

func GetContext

func GetContext() Context

func (Context) Collapse

func (c Context) Collapse() interface{}

Collapse returns the plain text collapsed value of the current Context object

func (Context) MarshalJSON

func (c Context) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON document represented by the current Context This should return : If only one element in the context and the element has no Term -> json marshaled string If multiple elements in the context without Term -> json marshaled array of strings If multiple elements where at least one doesn't have a Term and one has a Term -> json marshaled array If multiple elements where all have Terms -> json marshaled object

func (*Context) UnmarshalJSON

func (c *Context) UnmarshalJSON(data []byte) error

UnmarshalJSON tries to load the Context from the incoming json value

type ContextElement

type ContextElement struct {
	Term Term
	IRI  IRI
}

ContextElement is used to map terms to IRIs or JSON objects. Terms are case sensitive and any valid string that is not a reserved JSON-LD keyword can be used as a term.

type ContextObject

type ContextObject struct {
	ID   interface{} `jsonld:"@id,omitempty,collapsible"`
	Type interface{} `jsonld:"@type,omitempty,collapsible"`
}

type IRI

type IRI string

IRI is a International Resource Identificator

func (IRI) Collapse

func (i IRI) Collapse() interface{}

Collapse returns the plain text collapsed value of the current IRI string

func (IRI) IsAbsolute

func (i IRI) IsAbsolute() bool

func (IRI) IsCompact

func (i IRI) IsCompact() bool

func (IRI) IsNil

func (i IRI) IsNil() bool

IsNil returns if current IRI is equal to empty string

func (IRI) IsRelative

func (i IRI) IsRelative() bool

func (IRI) MarshalText

func (i IRI) MarshalText() ([]byte, error)

MarshalText basic stringify function

type IRILike

type IRILike interface {
	IsCompact() bool
	IsAbsolute() bool
	IsRelative() bool
}

type InvalidUTF8Error

type InvalidUTF8Error struct {
	S string // the whole string value that caused the error
}

Before Go 1.2, an InvalidUTF8Error was returned by Marshal when attempting to encode a string value with invalid UTF-8 sequences. As of Go 1.2, Marshal instead coerces the string to valid UTF-8 by replacing invalid bytes with the Unicode replacement rune U+FFFD. This error is no longer generated but is kept for backwards compatibility with programs that might mention it.

func (*InvalidUTF8Error) Error

func (e *InvalidUTF8Error) Error() string

type InvalidUnmarshalError

type InvalidUnmarshalError struct {
	Type reflect.Type
}

An InvalidUnmarshalError describes an invalid argument passed to Unmarshal. (The argument to Unmarshal must be a non-nil pointer.)

func (*InvalidUnmarshalError) Error

func (e *InvalidUnmarshalError) Error() string

type LangRef

type LangRef string

Ref basic type

const NilLangRef LangRef = "-"

func (LangRef) IsNil

func (l LangRef) IsNil() bool

IsNil returns if current LangRef is equal to empty string or to its nil value

type MarshalerError

type MarshalerError struct {
	Type reflect.Type
	Err  error
}

func (*MarshalerError) Error

func (e *MarshalerError) Error() string

type Nillable

type Nillable interface {
	IsNil() bool
}

Nillable

type Number

type Number string

A Number represents a JSON number literal.

func (Number) Float64

func (n Number) Float64() (float64, error)

Float64 returns the number as a float64.

func (Number) Int64

func (n Number) Int64() (int64, error)

Int64 returns the number as an int64.

func (Number) String

func (n Number) String() string

String returns the literal text of the number.

type SyntaxError

type SyntaxError struct {
	Offset int64 // error occurred after reading Offset bytes
	// contains filtered or unexported fields
}

A SyntaxError is a description of a JSON syntax error.

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

type Tag

type Tag struct {
	Name        string
	Ignore      bool
	OmitEmpty   bool
	Collapsible bool
	NoMarshal   bool
}

Tag used by structs from the ActivityPub package to Marshal and Unmarshal to/from JSON-LD

func LoadTag

func LoadTag(tag reflect.StructTag) (Tag, bool)

LoadTag used by structs from the ActivityPub package to Marshal and Unmarshal to/from JSON-LD

type Term

type Term string

Term represents the JSON-LD term for @context maps

const (
	// @context
	// Used to define the short-hand names that are used throughout a JSON-LD document.
	// These short-hand names are called terms and help developers to express specific identifiers in a compact manner.
	// The @context keyword is described in detail in section 5.1 The Context.
	ContextKw Term = "@context"
	// @id
	//Used to uniquely identify things that are being described in the document with IRIs or blank node identifiers.
	// This keyword is described in section 5.3 Node Identifiers.
	IdKw Term = "@id"
	// @value
	// Used to specify the data that is associated with a particular property in the graph.
	// This keyword is described in section 6.9 String Internationalization and section 6.4 Typed Values.
	ValueKw Term = "@value"
	// @language
	// Used to specify the language for a particular string value or the default language of a JSON-LD document.
	// This keyword is described in section 6.9 String Internationalization.
	LanguageKw Term = "@language"
	//@type
	//Used to set the data type of a node or typed value. This keyword is described in section 6.4 Typed Values.
	TypeKw Term = "@type"
	// @container
	// Used to set the default container type for a term. This keyword is described in section 6.11 Sets and Lists.
	ContainerKw Term = "@container"
	//@list
	//Used to express an ordered set of data. This keyword is described in section 6.11 Sets and Lists.
	ListKw Term = "@list"
	// @set
	// Used to express an unordered set of data and to ensure that values are always represented as arrays.
	// This keyword is described in section 6.11 Sets and Lists.
	SetKw Term = "@set"
	// @reverse
	// Used to express reverse properties. This keyword is described in section 6.12 Reverse Properties.
	ReverseKw Term = "@reverse"
	// @index
	// Used to specify that a container is used to index information and that processing should continue deeper
	// into a JSON data structure. This keyword is described in section 6.16 Data Indexing.
	IndexKw Term = "@index"
	// @base
	// Used to set the base IRI against which relative IRIs are resolved. T
	// his keyword is described in section 6.1 Base IRI.
	BaseKw Term = "@base"
	// @vocab
	// Used to expand properties and values in @type with a common prefix IRI.
	// This keyword is described in section 6.2 Default Vocabulary.
	VocabKw Term = "@vocab"
	// @graph
	// Used to express a graph. This keyword is described in section 6.13 Named Graphs.
	GraphKw Term = "@graph"
)

From the JSON-LD spec 3.3 https://www.w3.org/TR/json-ld/#dfn-keyword

const NilTerm Term = "-"

func (Term) IsNil

func (i Term) IsNil() bool

IsNil returns if current Term is equal to empty string or to its nil value

type Terms

type Terms []Term

Terms is an array of Term values

type UnmarshalFieldError

type UnmarshalFieldError struct {
	Key   string
	Type  reflect.Type
	Field reflect.StructField
}

An UnmarshalFieldError describes a JSON object key that led to an unexported (and therefore unwritable) struct field. (No longer used; kept for compatibility.)

func (*UnmarshalFieldError) Error

func (e *UnmarshalFieldError) Error() string

type UnmarshalTypeError

type UnmarshalTypeError struct {
	Value  string       // description of JSON value - "bool", "array", "number -5"
	Type   reflect.Type // type of Go value it could not be assigned to
	Offset int64        // error occurred after reading Offset bytes
	Struct string       // name of the struct type containing the field
	Field  string       // name of the field holding the Go value
}

An UnmarshalTypeError describes a JSON value that was not appropriate for a value of a specific Go type.

func (*UnmarshalTypeError) Error

func (e *UnmarshalTypeError) Error() string

type UnsupportedTypeError

type UnsupportedTypeError struct {
	Type reflect.Type
}

An UnsupportedTypeError is returned by Marshal when attempting to encode an unsupported value type.

func (*UnsupportedTypeError) Error

func (e *UnsupportedTypeError) Error() string

type UnsupportedValueError

type UnsupportedValueError struct {
	Value reflect.Value
	Str   string
}

func (*UnsupportedValueError) Error

func (e *UnsupportedValueError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL