head

Documentation

Overview

Package head defines the contents to be used in envelope headers.

Index

• Variables
• func StampsHas(provider cbc.Key) validation.Rule
• func WithHead(header *Header) schema.Option
• type CorrectionOptions
• type Header
  • func NewHeader() *Header
  • func (h *Header) AddLink(l *Link)
  • func (h *Header) AddStamp(s *Stamp)
  • func (h *Header) Contains(h2 *Header) bool
  • func (h *Header) GetStamp(provider cbc.Key) *Stamp
  • func (h *Header) Link(key cbc.Key) *Link
  • func (h *Header) Stamp(provider cbc.Key) *Stamp
  • func (h *Header) Validate() error
  • func (h *Header) ValidateWithContext(ctx context.Context) error
• type Link
  • func AppendLink(list []*Link, l *Link) []*Link
  • func LinkByKey(list []*Link, k cbc.Key) *Link
  • func (l *Link) Validate() error
• type Stamp
  • func AddStamp(in []*Stamp, s *Stamp) []*Stamp
  • func GetStamp(in []*Stamp, provider cbc.Key) *Stamp
  • func NormalizeStamps(in []*Stamp) []*Stamp
  • func (s *Stamp) In(ss []*Stamp) bool
  • func (s *Stamp) Validate() error

Variables

var DetectDuplicateLinks = validation.By(detectDuplicateLinks)

DetectDuplicateLinks checks if the list of links contains duplicate keys.

var DetectDuplicateStamps = validation.By(detectDuplicateStamps)

DetectDuplicateStamps checks if the list of stamps contains duplicate provider keys.

Functions

func StampsHas

func StampsHas(provider cbc.Key) validation.Rule

StampsHas provides a validation rule that checks if a list of stamps includes one for the given provider.

func WithHead

func WithHead(header *Header) schema.Option

WithHead ensures the original envelope's header is included in the set of correction options. If the head.CorrectionOptions is not defined in the options, this will be ignored.

Types

type CorrectionOptions

type CorrectionOptions struct {
	Head *Header `json:"-"` // copy of the original document header
}

CorrectionOptions is used to define base correction options that can be shared between documents.

type Header

type Header struct {
	// Unique UUIDv1 identifier for the envelope.
	UUID uuid.UUID `json:"uuid" jsonschema:"title=UUID"`

	// Digest of the canonical JSON body.
	Digest *dsig.Digest `json:"dig" jsonschema:"title=Digest"`

	// Seals of approval from other organisations that can only be added to
	// non-draft envelopes.
	Stamps []*Stamp `json:"stamps,omitempty" jsonschema:"title=Stamps"`

	// Links provide URLs to other resources that are related to this envelope
	// and unlike stamps can be added even in the draft state.
	Links []*Link `json:"links,omitempty" jsonschema:"title=Links"`

	// Set of labels that describe but have no influence on the data.
	Tags []string `json:"tags,omitempty" jsonschema:"title=Tags"`

	// Additional semi-structured information about this envelope.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`

	// Any information that may be relevant to other humans about this envelope
	Notes string `json:"notes,omitempty" jsonschema:"title=Notes"`
}

Header defines the metadata of the body. The header is used as the payload for the JSON Web Signatures, so we want this to be as compact as possible.

func NewHeader

func NewHeader() *Header

NewHeader creates a new header and automatically assigns a UUIDv1.

func (*Header) AddLink

func (h *Header) AddLink(l *Link)

AddLink will add the link to the header, or update a link with the same key.

func (*Header) AddStamp

func (h *Header) AddStamp(s *Stamp)

AddStamp adds a new stamp to the header. If the stamp already exists, it will be overwritten.

func (*Header) Contains

func (h *Header) Contains(h2 *Header) bool

Contains compares the provided header to ensure that all the fields and properties are contained within the base header. Only a subset of the most important fields are compared.

func (*Header) GetStamp

func (h *Header) GetStamp(provider cbc.Key) *Stamp

GetStamp provides the stamp for the given provider or nil. Deprecated: use Stamp instead.

func (*Header) Link

func (h *Header) Link(key cbc.Key) *Link

Link provides the link with the matching key in the header, or nil.

func (*Header) Stamp

func (h *Header) Stamp(provider cbc.Key) *Stamp

Stamp provides the stamp for the given provider or nil.

func (*Header) Validate

func (h *Header) Validate() error

Validate checks that the header contains the basic information we need to function.

func (*Header) ValidateWithContext

func (h *Header) ValidateWithContext(ctx context.Context) error

ValidateWithContext checks that the header contains the basic information we need to function.

type Link

type Link struct {
	// Key is a unique identifier for the link.
	Key cbc.Key `json:"key"`
	// Title of the resource to use when presenting to users.
	Title string `json:"title,omitempty" jsonschema:"title=Title"`
	// Description of the resource to use when presenting to users.
	Description string `json:"description,omitempty" jsonschema:"title=Description"`
	// Expected MIME type of the link's content.
	MIME string `json:"mime,omitempty" jsonschema:"title=MIME Type,format=mime"`
	// URL of the resource.
	URL string `json:"url" jsonschema:"title=URL,format=uri"`
}

Link defines a link between this document and another resource. Much like stamps, links must be defined with a specific key, but do allow for additional data that can help with presentation. It is important that a link once generated cannot be updated, so this is not suitable for dynamic or potentially insecure.

Links have a specific advantage over stamps in that they are also allowed while the envelope is still a draft.

func AppendLink

func AppendLink(list []*Link, l *Link) []*Link

AppendLink will add the link to the provided list and return the new updated list. If the link already exists, it will be updated.

func LinkByKey

func LinkByKey(list []*Link, k cbc.Key) *Link

LinkByKey finds the link with the given key from the provided list.

func (*Link) Validate

func (l *Link) Validate() error

Validate checks that the link contains the basic information we need to function.

type Stamp

type Stamp struct {
	// Identity of the agency used to create the stamp usually defined by each region.
	Provider cbc.Key `json:"prv" jsonschema:"title=Provider"`
	// The serialized stamp value generated for or by the external agency
	Value string `json:"val" jsonschema:"title=Value"`
}

Stamp defines an official seal of approval from a third party like a governmental agency or intermediary and should thus be included in any official envelopes.

func AddStamp

func AddStamp(in []*Stamp, s *Stamp) []*Stamp

AddStamp makes it easier to add a new Stamp by replacing a previous entry with a matching Key.

func GetStamp

func GetStamp(in []*Stamp, provider cbc.Key) *Stamp

GetStamp provides the matching stamp for the given provider.

func NormalizeStamps

func NormalizeStamps(in []*Stamp) []*Stamp

NormalizeStamps will try to clean the stamps by removing rows with empty providers or values. If empty, the function will return nil.

func (*Stamp) In

func (s *Stamp) In(ss []*Stamp) bool

In checks if the stamp is in the list of stamps.

func (*Stamp) Validate

func (s *Stamp) Validate() error

Validate checks that the header contains the basic information we need to function.