swecommon

type BinaryByteOrder ¶

type BinaryByteOrder uint8

BinaryByteOrder is the wire byte order for the binary encoding. Default and recommendation: big-endian (network byte order). The producer and consumer must agree; the schema's BinaryEncoding metadata block carries the choice on the wire.

const (
	// BigEndian — default. Matches network byte order.
	BigEndian BinaryByteOrder = iota
	// LittleEndian — opt-in for producers that want to skip the
	// host-to-network byte swap on x86/ARM.
	LittleEndian
)

type BinaryEncoding ¶

type BinaryEncoding struct {
	ByteOrder BinaryByteOrder
}

BinaryEncoding configures the SWE BinaryEncoding (SWE Common §7.4.4) options. The framework Phase 1 supports the "packed primitives" variant: each field is encoded back-to-back with no padding, types per the wire format below.

Per-field wire format:

• Quantity → 8 bytes IEEE 754 float64
• Count → 8 bytes int64
• Time → uint32 length prefix + UTF-8 RFC 3339 bytes
• Boolean → 1 byte (0 = false, 1 = true)
• Text → uint32 length prefix + UTF-8 bytes
• Category → uint32 length prefix + UTF-8 bytes

Nil values: a separate nil bitmap precedes each record. The bitmap is ceil(nfields/8) bytes, big-endian bit order (high bit = field 0). A 1 bit means the field is nil; the value bytes are skipped for nil fields.

func DefaultBinaryEncoding() BinaryEncoding

type Boolean ¶

type Boolean struct {
	CommonFields
}

Boolean is a true/false value (SWE Common §7.6.2). Round-trips through Go bool.

func (Boolean) Kind() ComponentKind

type Category ¶

type Category struct {
	CommonFields

	// CodeSpace is the IRI of the code list this category draws
	// from. Empty = free-form token (legal but limits validation).
	CodeSpace string `json:"codeSpace,omitempty"`
}

Category is a controlled-vocabulary token (SWE Common §7.6.7). CodeSpace is the IRI of the code list; values are short tokens drawn from that list. Round-trips through Go string.

func (Category) Kind() ComponentKind

type CommonFields ¶

type CommonFields struct {
	LabelValue      string `json:"label,omitempty"`
	DefinitionValue string `json:"definition,omitempty"`

	// NilValue is the wire-side stand-in token a producer emits when
	// the field is absent. Decoders treat any value equal to this
	// token (after format-specific normalization) as Go `nil`.
	// Per SWE Common §7.5 NilValues — Phase 1 supports a single
	// stand-in; the multi-reason NilValues block is deferred.
	NilValue string `json:"nilValue,omitempty"`
}

CommonFields is the embedded base for every concrete component. It carries the label + definition + nilValue stand-in that every SWE component may optionally declare. JSON tag rules: omit when empty so a minimal Quantity{} round-trips to `{"type":"Quantity"}`.

func (c CommonFields) Definition() string

func (c CommonFields) Label() string

func (c CommonFields) Nil() string

type ComponentKind ¶

type ComponentKind string

ComponentKind is the SWE Common data-component discriminator. Every concrete DataComponent reports one of these so encoders and decoders can dispatch without reflection. The string values match the `type` discriminator field in OGC SWE Common JSON Encoding (22-022), so they double as the wire-format type tag.

const (
	KindRecord   ComponentKind = "DataRecord"
	KindQuantity ComponentKind = "Quantity"
	KindCount    ComponentKind = "Count"
	KindTime     ComponentKind = "Time"
	KindBoolean  ComponentKind = "Boolean"
	KindText     ComponentKind = "Text"
	KindCategory ComponentKind = "Category"
)

type Count ¶

type Count struct {
	CommonFields
}

Count is a discrete integer count with no unit of measure (SWE Common §7.6.6). Round-trips through int64.

func (Count) Kind() ComponentKind

type DataComponent ¶

type DataComponent interface {
	// Kind reports which SWE Common component this is.
	Kind() ComponentKind

	// Label is the human-readable name; empty when unset.
	Label() string

	// Definition is the IRI of the controlled concept that defines
	// this component's semantics (e.g. a QUDT QuantityKind or a
	// SWEET property concept). Empty when unset.
	Definition() string
	// contains filtered or unexported methods
}

DataComponent is the sealed supertype for SWE Common data components. Implementations live in this package only — adding a new kind requires updating the encoders, decoders, and the register tables in schema.go, which would not compile otherwise.

type DataRecord ¶

type DataRecord struct {
	CommonFields

	// Fields are the record's typed members, in declaration order.
	// Order is wire-significant for CSV and binary encodings.
	Fields []Field
}

DataRecord is the schema for a heterogeneous record of named typed fields (SWE Common §7.6.8). It is the framework's observation-result and command-payload model.

func UnmarshalSchema(data []byte) (*DataRecord, error)

func (r *DataRecord) FieldByName(name string) (Field, bool)

func (*DataRecord) Kind() ComponentKind

func (r *DataRecord) Validate() error

type Field ¶

type Field struct {
	// Name is the field's identifier within its parent record. Must
	// be unique across the record's fields, non-empty, and (for
	// CSV/text encoding) free of the configured token separator.
	Name string

	// Component is the typed schema for this field's values.
	Component DataComponent
}

Field is a named member of a DataRecord. The name is the dictionary key in the record's value map (and the column header in CSV / position index in binary). Component carries the typed schema for the field's values.

type Quantity ¶

type Quantity struct {
	CommonFields

	// UoM is the unit of measure. Carry a UCUM symbol (e.g. "Cel",
	// "m/s") via Code OR a QUDT/OGC unit IRI via Href. Both empty
	// = dimensionless quantity, which is legal but lossy through
	// the SWE+csv encoding.
	UoMCode string `json:"uomCode,omitempty"`
	UoMHref string `json:"uomHref,omitempty"`
}

Quantity is a numeric value with a unit of measure (SWE Common §7.6.4). Round-trips through float64; producers needing higher precision (int64-fidelity counts, decimal-fixed) should declare a Count or carry the value as Text instead.

func (Quantity) Kind() ComponentKind

type Text ¶

type Text struct {
	CommonFields
}

Text is a free-text string (SWE Common §7.6.3). Round-trips through Go string; binary encoding length-prefixes the UTF-8 bytes with a uint32.

func (Text) Kind() ComponentKind

type TextEncoding ¶

type TextEncoding struct {
	// TokenSeparator separates values within a record. Default ",".
	TokenSeparator string

	// BlockSeparator separates records. Default "\n".
	BlockSeparator string

	// DecimalSeparator is the decimal point. Must be ".".
	DecimalSeparator string

	// CollapseWhiteSpace controls whether the decoder trims
	// leading/trailing whitespace from each token. Defaults true.
	CollapseWhiteSpace bool

	// EmitHeader controls whether the encoder emits the field-name
	// header row before the first record. CS API SWE text streams
	// typically omit it (the schema is advertised separately); the
	// framework default is false to match.
	EmitHeader bool
}

TextEncoding configures the SWE TextEncoding (SWE Common §7.4.3) separators. CS API requires the producer/consumer to agree on these; the framework defaults match the CSV media type and are safe round-trip targets.

Token separator splits values within one record (column delimiter). Block separator splits records (row delimiter). Decimal separator must be "." to round-trip JSON-compatible floats; encoders surface a configuration error otherwise.

func DefaultTextEncoding() TextEncoding

type Time ¶

type Time struct {
	CommonFields

	// UoMHref carries the temporal reference IRI (e.g.
	// "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"). The
	// SWE JSON encoding emits this as uom.href on the wire.
	UoMHref string `json:"uomHref,omitempty"`

	// ReferenceFrame is the optional temporal frame IRI for
	// non-UTC time values. Empty = UTC.
	ReferenceFrame string `json:"referenceFrame,omitempty"`
}

Time is a temporal instant (SWE Common §7.6.5). Round-trips through ISO 8601 / RFC 3339 strings — Phase 1 does not encode epoch-seconds doubles. Time-zone-frame and reference-frame are carried as IRIs; missing frame is treated as UTC by convention.

func (Time) Kind() ComponentKind

type Values ¶

type Values map[string]any

Values is one record's worth of typed field values, keyed by field name. Missing keys are treated as nil (encoders emit the schema's nilValue or JSON null). Per-field Go types:

• Quantity → float64
• Count → int64
• Time → time.Time (or RFC 3339 string — encoders convert)
• Boolean → bool
• Text → string
• Category → string

Encoders are tolerant on input: a Quantity field accepts any numeric type (int, int32, int64, float32, float64) and rounds through float64; a Time field accepts either time.Time or an RFC 3339 string. Decoders always populate the canonical type.

func DecodeBinary(r io.Reader, schema *DataRecord, enc BinaryEncoding) ([]Values, error)

func DecodeJSON(r io.Reader, schema *DataRecord) ([]Values, error)

func DecodeText(r io.Reader, schema *DataRecord, enc TextEncoding) ([]Values, error)

func UnmarshalBinaryRows(data []byte, schema *DataRecord, enc BinaryEncoding) ([]Values, error)

func UnmarshalJSONRows(data []byte, schema *DataRecord) ([]Values, error)

func UnmarshalTextRows(data []byte, schema *DataRecord, enc TextEncoding) ([]Values, error)