isoxml-go

README

isoxml-go

This is an internal agrirouter library for working with ISOXML taskdata format (ISO 11783-10).

It is not intended for use outside of agrirouter and no guarantees are made about API stability at this time. If you decide to use this library, please be aware that breaking changes may occur without warning and no support is guaranteed due to limited intended scope of this lib.

Library Design

The library provides a set of Go structs that mirror the structure of ISOXML taskdata files directly, with struct tags for XML marshaling/unmarshaling. Structures themselves represent taskdata format in its original form with any transformations to golang types being done via accessor methods.

For example this is allocation stamp structure:

type AllocationStamp struct {
	Start    string    `xml:"A,attr"`
	Stop     string    `xml:"B,attr,omitempty"`
	Duration uint64    `xml:"C,attr,omitempty"`
	Type     string    `xml:"D,attr"`
	Position *Position `xml:"PTN,omitempty"`
}

The name of struct is AllocationStamp as is described in the standard, names of fields Start, Stop, etc are all also as described in the standard. Using Start and Stop fields directly might not be possible for situations when client code needs to work with these values as timestamps, so a transformation to time.Time type is required.

Standard defines that Start and Stop are ISO8601 timestamps and this understanding is encoded in accessor methods:

func (s *AllocationStamp) StartTime(loc *time.Location) (time.Time, error)
func (s *AllocationStamp) StopTime(loc *time.Location) (time.Time, error)

These methods would return native time.Time values for Start and Stop fields correspondingly. An important note: these methods take optional *time.Location parameter, which allows to specify timezone for parsing timestamps. This is because ISO8601 timestamps can be either timezone-aware (with Z suffix or timezone offset) or timezone-naive (without any timezone information). In the latter case, library will assume that timestamps are in the timezone specified by loc parameter, and if it is nil lirary would not make any assumptions in regards to timezone and would return an error to avoid hard-to-debug timestamp bugs.

This example demonstrates several important design choices of the library:

1. Structs mirror ISOXML structure directly, with no transformations to Go types at XML unmarshaling/marshaling stage.
2. Any transformations to Go types are done via accessor methods, which also encode any assumptions or special handling required by the standard (like timezone handling for timestamps).
3. Library follows specification as closely as possible and in case of any ambiguities or edge cases in the standard, library errs on the side of caution and might return an error instead of potentially incorrect data.