cbc

Documentation

Overview

Package cbc provides a set of Common Basic Components.

Name is take from the similar namespace used in UBL.

Index

• Variables
• func CodeMapHas(keys ...Key) validation.Rule
• func HasValidKeyIn(keys ...Key) validation.Rule
• type Code
  • func (c Code) In(ary ...Code) bool
  • func (c Code) IsEmpty() bool
  • func (Code) JSONSchema() *jsonschema.Schema
  • func (c Code) String() string
  • func (c Code) Validate() error
• type CodeMap
  • func (cs CodeMap) Equals(other CodeMap) bool
  • func (cs CodeMap) Has(keys ...Key) bool
  • func (CodeMap) JSONSchemaExtend(schema *jsonschema.Schema)
  • func (cs CodeMap) Validate() error
• type DefNoteKey
• type Key
  • func (k Key) Has(ke Key) bool
  • func (k Key) HasPrefix(ke Key) bool
  • func (k Key) In(set ...Key) bool
  • func (k Key) IsEmpty() bool
  • func (Key) JSONSchema() *jsonschema.Schema
  • func (k Key) String() string
  • func (k Key) Validate() error
  • func (k Key) With(ke Key) Key
• type Meta
  • func (Meta) JSONSchemaExtend(schema *jsonschema.Schema)
  • func (m Meta) Validate() error
• type Note
  • func (Note) JSONSchemaExtend(schema *jsonschema.Schema)
  • func (n *Note) UNTDID4451() Code
  • func (n *Note) Validate() error
  • func (n *Note) WithSrc(src Key) *Note

Variables

var (
	CodePattern          = `^[A-Z0-9]+(\.?[A-Z0-9]+)*$`
	CodeMinLength uint64 = 1
	CodeMaxLength uint64 = 24
)

Basic code constants.

var (
	// KeyPattern describes what should keys look like
	KeyPattern = `^(?:[a-z]|[a-z0-9][a-z0-9-+]*[a-z0-9])$`
	// KeyValidationRegexp is used for key validation
	KeyValidationRegexp = regexp.MustCompile(KeyPattern)
	// KeySeparator is used to separate keys join using the "With"
	// method.
	KeySeparator = "+"
)

var (
	// KeyMinLength defines the minimum key length
	KeyMinLength uint64 = 1
	// KeyMaxLength defines the maximum key length
	KeyMaxLength uint64 = 64
)

var NoteKeyDefinitions = []DefNoteKey{
	{
		Key:         NoteKeyGoods,
		Title:       "Goods",
		Description: "Goods Description",
		UNTDID4451:  "AAA",
	},
	{
		Key:         NoteKeyPayment,
		Title:       "Payment",
		Description: "Terms of Payment",
		UNTDID4451:  "PMT",
	},
	{
		Key:         NoteKeyLegal,
		Title:       "Legal",
		Description: "Legal or regulatory information",
		UNTDID4451:  "ABY",
	},
	{
		Key:         NoteKeyDangerousGoods,
		Title:       "Dangerous Goods",
		Description: "Dangerous goods additional information",
		UNTDID4451:  "AAC",
	},
	{
		Key:         NoteKeyAck,
		Title:       "Acknowledgement",
		Description: "Acknowledgement Description",
		UNTDID4451:  "AAE",
	},
	{
		Key:         NoteKeyRate,
		Title:       "Rate",
		Description: "Rate additional information",
		UNTDID4451:  "AAF",
	},
	{
		Key:         NoteKeyReason,
		Title:       "Reason",
		Description: "Explanation of something relevant to the document",
		UNTDID4451:  "ACD",
	},
	{
		Key:         NoteKeyDispute,
		Title:       "Dispute",
		Description: "Details on a dispute.",
		UNTDID4451:  "ACE",
	},
	{
		Key:         NoteKeyCustomer,
		Title:       "Customer",
		Description: "Customer remarks",
		UNTDID4451:  "CUR",
	},
	{
		Key:         NoteKeyGlossary,
		Title:       "Glossary",
		Description: "Glossary of terms",
		UNTDID4451:  "ACZ",
	},
	{
		Key:         NoteKeyCustoms,
		Title:       "Customs",
		Description: "Customs declaration information",
		UNTDID4451:  "CUS",
	},
	{
		Key:         NoteKeyGeneral,
		Title:       "General",
		Description: "General information",
		UNTDID4451:  "AAI",
	},
	{
		Key:         NoteKeyHandling,
		Title:       "Handling",
		Description: "Handling instructions",
		UNTDID4451:  "HAN",
	},
	{
		Key:         NoteKeyPackaging,
		Title:       "Packaging",
		Description: "Packaging information",
		UNTDID4451:  "PKG",
	},
	{
		Key:         NoteKeyLoading,
		Title:       "Loading",
		Description: "Loading instructions",
		UNTDID4451:  "LOI",
	},
	{
		Key:         NoteKeyPrice,
		Title:       "Price",
		Description: "Price conditions",
		UNTDID4451:  "AAK",
	},
	{
		Key:         NoteKeyPriority,
		Title:       "Priority",
		Description: "Priority information",
		UNTDID4451:  "PRI",
	},
	{
		Key:         NoteKeyRegulatory,
		Title:       "Regulatory",
		Description: "Regulatory information",
		UNTDID4451:  "REG",
	},
	{
		Key:         NoteKeySafety,
		Title:       "Safety",
		Description: "Safety instructions",
		UNTDID4451:  "SAF",
	},
	{
		Key:         NoteKeyShipLine,
		Title:       "Ship Line",
		Description: "Ship line",
		UNTDID4451:  "SLR",
	},
	{
		Key:         NoteKeySupplier,
		Title:       "Supplier",
		Description: "Supplier remarks",
		UNTDID4451:  "SUR",
	},
	{
		Key:         NoteKeyTransport,
		Title:       "Transport",
		Description: "Transportation information",
		UNTDID4451:  "TRA",
	},
	{
		Key:         NoteKeyDelivery,
		Title:       "Delivery",
		Description: "Delivery information",
		UNTDID4451:  "DEL",
	},
	{
		Key:         NoteKeyQuarantine,
		Title:       "Quarantine",
		Description: "Quarantine information",
		UNTDID4451:  "QIN",
	},
	{
		Key:         NoteKeyTax,
		Title:       "Tax",
		Description: "Tax declaration",
		UNTDID4451:  "TXD",
	},
}

NoteKeyDefinitions provides a map of Note Keys to their definitions including a description and UNTDID code.

Functions

func CodeMapHas

func CodeMapHas(keys ...Key) validation.Rule

CodeMapHas returns a validation rule that ensures the code set contains the provided keys.

func HasValidKeyIn

func HasValidKeyIn(keys ...Key) validation.Rule

HasValidKeyIn provides a validator to check the Key's value is within the provided known set.

Types

type Code

type Code string

Code represents a string used to uniquely identify the data we're looking at. We use "code" instead of "id", to reenforce the fact that codes should be more easily set and used by humans within definitions than IDs or UUIDs. Codes are standardised so that when validated they must contain between 1 and 24 inclusive upper-case letters or numbers with optional periods to separate blocks.

const CodeEmpty Code = ""

CodeEmpty is used when no code is defined.

func (Code) In

func (c Code) In(ary ...Code) bool

In returns true if the code's value matches one of those in the provided list.

func (Code) IsEmpty

func (c Code) IsEmpty() bool

IsEmpty returns true if no code is specified.

func (Code) JSONSchema

func (Code) JSONSchema() *jsonschema.Schema

JSONSchema provides a representation of the struct for usage in Schema.

func (Code) String

func (c Code) String() string

String returns string representation of code.

func (Code) Validate

func (c Code) Validate() error

Validate ensures that the code complies with the expected rules.

type CodeMap

type CodeMap map[Key]Code

CodeMap is a map of keys to specific codes, useful to determine regime specific codes from their key counterparts.

func (CodeMap) Equals

func (cs CodeMap) Equals(other CodeMap) bool

Equals returns true if the code map has the same keys and values as the provided map.

func (CodeMap) Has

func (cs CodeMap) Has(keys ...Key) bool

Has returns true if the code map has values for all the provided keys.

func (CodeMap) JSONSchemaExtend

func (CodeMap) JSONSchemaExtend(schema *jsonschema.Schema)

JSONSchemaExtend ensures the pattern property is set correctly.

func (CodeMap) Validate

func (cs CodeMap) Validate() error

Validate ensures the code maps data looks correct.

type DefNoteKey

type DefNoteKey struct {
	// Key to match against
	Key Key `json:"key" jsonschema:"title=Key"`
	// Brief name of the key
	Title string `json:"title" jsonschema:"title=Title"`
	// Description of the Note Key
	Description string `json:"description" jsonschema:"title=Description"`
	// UNTDID 4451 code
	UNTDID4451 Code `json:"untdid4451" jsonschema:"title=UNTDID4451 Code"`
}

DefNoteKey holds a note key definition

type Key

type Key string

Key is used to define an ID or code that more closely represents a human name. The objective is to make it easier to define constants that can be re-used more easily.

const (
	// Goods Description
	NoteKeyGoods Key = "goods"
	// Terms of Payment
	NoteKeyPayment Key = "payment"
	// Legal or regulatory information
	NoteKeyLegal Key = "legal"
	// Dangerous goods additional information
	NoteKeyDangerousGoods Key = "dangerous-goods"
	// Acknowledgement Description
	NoteKeyAck Key = "ack"
	// Rate additional information
	NoteKeyRate Key = "rate"
	// Reason
	NoteKeyReason Key = "reason"
	// Dispute
	NoteKeyDispute Key = "dispute"
	// Customer remarks
	NoteKeyCustomer Key = "customer"
	// Glossary
	NoteKeyGlossary Key = "glossary"
	// Customs declaration information
	NoteKeyCustoms Key = "customs"
	// General information
	NoteKeyGeneral Key = "general"
	// Handling instructions
	NoteKeyHandling Key = "handling"
	// Packaging information
	NoteKeyPackaging Key = "packaging"
	// Loading instructions
	NoteKeyLoading Key = "loading"
	// Price conditions
	NoteKeyPrice Key = "price"
	// Priority information
	NoteKeyPriority Key = "priority"
	// Regulatory information
	NoteKeyRegulatory Key = "regulatory"
	// Safety Instructions
	NoteKeySafety Key = "safety"
	// Ship Line
	NoteKeyShipLine Key = "ship-line"
	// Supplier remarks
	NoteKeySupplier Key = "supplier"
	// Transportation information
	NoteKeyTransport Key = "transport"
	// Delivery Information
	NoteKeyDelivery Key = "delivery"
	// Quarantine Information
	NoteKeyQuarantine Key = "quarantine"
	// Tax declaration
	NoteKeyTax Key = "tax"
)

Predefined list of supported note keys based on the UNTDID 4451 list of text subject qualifiers. We've picked the ones which we think are most useful, but if you require an additional code, please send a pull request.

const KeyEmpty Key = ""

KeyEmpty is used when no key is available.

func (Key) Has

func (k Key) Has(ke Key) bool

Has returns true if the key contains the provided key.

func (Key) HasPrefix

func (k Key) HasPrefix(ke Key) bool

HasPrefix checks to see if the key starts with the provided key. As per `Has`, only the complete key between `+` symbols are matched.

func (Key) In

func (k Key) In(set ...Key) bool

In returns true if the key's value matches one of those in the provided list.

func (Key) IsEmpty

func (k Key) IsEmpty() bool

IsEmpty returns true if the key has no value.

func (Key) JSONSchema

func (Key) JSONSchema() *jsonschema.Schema

JSONSchema provides a representation of the struct for usage in Schema.

func (Key) String

func (k Key) String() string

String provides string representation of key

func (Key) Validate

func (k Key) Validate() error

Validate ensures the key complies with the basic syntax requirements.

func (Key) With

func (k Key) With(ke Key) Key

With provides a new key that combines another joining them together with a `+` symbol.

type Meta

type Meta map[Key]string

Meta defines a structure for data about the data being defined. Typically would be used for adding additional IDs or specifications not already defined or required by the base structure.

GOBL is focussed on ensuring the recipient has everything they need, as such, meta should only be used for data that may be used by intermediary conversion processes that should not be needed by the end-user.

We need to always use strings for values so that meta-data is easy to convert into other formats, such as protobuf which has strict type requirements.

func (Meta) JSONSchemaExtend

func (Meta) JSONSchemaExtend(schema *jsonschema.Schema)

JSONSchemaExtend ensures the meta keys are valid.

func (Meta) Validate

func (m Meta) Validate() error

Validate ensures the meta data looks correct.

type Note

type Note struct {
	// Key specifying subject of the text
	Key Key `json:"key,omitempty" jsonschema:"title=Key"`
	// Code used for additional data that may be required to identify the note.
	Code string `json:"code,omitempty" jsonschema:"title=Code"`
	// Source of this note, especially useful when auto-generated.
	Src Key `json:"src,omitempty" jsonschema:"title=Source"`
	// The contents of the note
	Text string `json:"text" jsonschema:"title=Text"`
	// Additional information about the note
	Meta Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

Note represents a free text of additional information that may be added to a document.

func (Note) JSONSchemaExtend

func (Note) JSONSchemaExtend(schema *jsonschema.Schema)

JSONSchemaExtend adds the list of definitions for the notes.

func (*Note) UNTDID4451

func (n *Note) UNTDID4451() Code

UNTDID4451 provides the note's UNTDID 4451 equivalent value. If not available, returns CodeEmpty.

func (*Note) Validate

func (n *Note) Validate() error

Validate checks that the note looks okay.

func (*Note) WithSrc

func (n *Note) WithSrc(src Key) *Note

WithSrc instantiates a new source instance with the provided source property set. This is a useful pattern for regional configurations.