### Install yaml.v3 with go get

Source: https://github.com/sixafter/types/blob/main/vendor/gopkg.in/yaml.v3/README.md

Install the yaml package using the go get command.

```go
go get gopkg.in/yaml.v3
```

--------------------------------

### Example program output

Source: https://github.com/sixafter/types/blob/main/vendor/gopkg.in/yaml.v3/README.md

Output produced by the example program. Shows the unmarshaled struct and map, and the YAML dumps for both. Note the flow-style list in the struct dump versus the block-style list in the map dump.

```text
--- t:
{Easy! {2 [3 4]}}

--- t dump:
a: Easy!
b:
  c: 2
  d: [3, 4]


--- m:
map[a:Easy! b:map[c:2 d:[3 4]]]

--- m dump:
a: Easy!
b:
  c: 2
  d:
  - 3
  - 4

```

--------------------------------

### Install types module with go get

Source: https://github.com/sixafter/types/blob/main/README.md

Command to add the types module as a dependency.

```shell
go get -u github.com/sixafter/types
```

--------------------------------

### Geofence usage example in Go

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/geofence.md

Shows constructing a Geofence with a polygon and iterating over its polygons using GetPolygons().

```go
zone := &pb.Geofence{
    Name: "Campus Zone",
    Polygons: []*pb.MapPolygon{
        {Points: []*pb.MapPoint{
            {X: 0, Y: 0, Coordinate: &pb.GeospatialCoordinate{Latitude: 32.9829, Longitude: -97.1876}},
            {X: 10, Y: 0},
            {X: 5, Y: 5},
        }},
        // a second, disconnected polygon is allowed
    },
}
for i, p := range zone.GetPolygons() {
    fmt.Printf("polygon %d has %d points\n", i, len(p.GetPoints()))
}
```

--------------------------------

### ProtoToString usage example

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uuid.md

Converts a message to a canonical string; returns an error if Value is invalid.

```go
s, err := pb.ProtoToString(msg)
if err != nil { log.Fatal(err) }
fmt.Println(s)
```

--------------------------------

### RadialGeofence usage example in Go

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/geofence.md

Shows constructing a RadialGeofence and safely reading its center coordinate with GetCenter().

```go
fence := &pb.RadialGeofence{
    Name:   "Warehouse Perimeter",
    Center: &pb.GeospatialCoordinate{Latitude: 32.9829, Longitude: -97.1876},
    Radius: 500, // meters -> 1 km diameter
}

// Nil-safe reads
if c := fence.GetCenter(); c != nil {
    fmt.Println(c.GetLatitude(), c.GetLongitude())
}
```

--------------------------------

### Country usage example (Go)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/country.md

Constructs a Country instance and prints its name and numeric code formatted as three digits. The GetName and GetNumericCode getters return zero values if unset.

```go
us := &pb.Country{
    Name:            "United States",
    FormalName:      "United States of America",
    AlphabeticCode_2: "US",
    AlphabeticCode_3: "USA",
    NumericCode:     840, // format as three digits when displaying
}
fmt.Printf("%s (%03d)\n", us.GetName(), us.GetNumericCode()) // United States (840)
```

--------------------------------

### Import types module in Go

Source: https://github.com/sixafter/types/blob/main/README.md

Example Go import statement for the types module.

```go
package main

import (
    pb "github.com/sixafter/types/proto/v1/pb"
)
```

--------------------------------

### CountrySubdivision usage example (Go)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/country.md

Builds a CountrySubdivision reusing the Country instance from the earlier example, then safely accesses the parent country via GetCountry, which returns nil if unset.

```go
tx := &pb.CountrySubdivision{
    Name: "Texas",
    Code: "US-TX",
    Country: us, // reuses the Country built above
}
if sub := tx.GetCountry(); sub != nil {
    fmt.Println(sub.GetAlphabeticCode_2()) // US
}
```

--------------------------------

### Round-trip with standard protobuf APIs

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/email-address.md

Complete round-trip example: marshal to binary, unmarshal back, and marshal to JSON with protojson. Shows lowerCamelCase field names in JSON output.

```go
// Marshal to binary
b, err := proto.Marshal(&pb.EmailAddress{LocalPart: "john.doe", DomainPart: "example.com"})
if err != nil { log.Fatal(err) }

// Unmarshal back
var addr pb.EmailAddress
if err := proto.Unmarshal(b, &addr); err != nil { log.Fatal(err) }

// Protojson (lowerCamelCase field names)
js, err := protojson.Marshal(&addr) // {"localPart":"john.doe","domainPart":"example.com"}
```

--------------------------------

### MapPoint usage example (Go)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/map.md

Shows constructing a MapPoint with a geospatial coordinate and accessing its getters. GetX and GetY return the values, GetCoordinate returns nil if unset.

```go
pt := &pb.MapPoint{
    X: 200.5,
    Y: 150.2,
    Coordinate: &pb.GeospatialCoordinate{
        Latitude:  32.9829, // Westlake, Texas
        Longitude: -97.1876,
    },
}
fmt.Println(pt.GetX(), pt.GetY())
if c := pt.GetCoordinate(); c != nil {
    fmt.Println(c.GetLatitude())
}
```

--------------------------------

### Round-trip example (all helpers together)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uuid.md

Demonstrates the full conversion cycle: native uuid.UUID -> proto -> string -> proto -> native. Uses UUIDToProto, ValidateUUID, ProtoToString, StringToProto, and ProtoToUUID. The final comparison prints true when the round-trip preserves the original value.

```go
// native -> proto -> string -> proto -> native
orig := uuid.New()
msg := pb.UUIDToProto(orig)                      // *pb.UUID
if err := pb.ValidateUUID(msg); err != nil { log.Fatal(err) }
s, _ := pb.ProtoToString(msg)                    // canonical string
msg2, err := pb.StringToProto(s)                 // back to *pb.UUID
if err != nil { log.Fatal(err) }
parsed, err := pb.ProtoToUUID(msg2)              // back to uuid.UUID
if err != nil { log.Fatal(err) }
fmt.Println(parsed == orig)                      // true
```

--------------------------------

### StringToProto usage example

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uuid.md

Parses a canonical UUID string; returns an error if parsing fails.

```go
msg, err := pb.StringToProto("2b7e1516-28ae-4c98-8c3d-9b1636b6033c")
if err != nil { log.Fatal(err) }
```

--------------------------------

### ValidateUUID usage example

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uuid.md

Checks RFC 9562 compliance; returns an error with details if invalid.

```go
if err := pb.ValidateUUID(msg); err != nil {
    // e.g. "UUID 2b7e1516-28ae-0c98-8c3d-9b1636b6033c is not RFC 9562-compliant: variant bits 10, version 0"
    log.Fatal(err)
}
```

--------------------------------

### Protojson encoding example

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/email-address.md

Shows the JSON representation of EmailAddress when encoded with protojson. Field names use lowerCamelCase.

```json
{"localPart": "john.doe", "domainPart": "example.com"}
```

--------------------------------

### ProtoToUUID usage example

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uuid.md

Decodes a protobuf message; returns an error if the message is nil or Value is not 16 bytes.

```go
u, err := pb.ProtoToUUID(msg)
if err != nil {
    log.Fatalf("decode: %v", err) // e.g. "invalid UUID length: got 3, want 16"
}
```

--------------------------------

### Basic construction of TemporalRange

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/temporal-range.md

Creates a one-hour range starting at midnight UTC. Uses timestamppb.New and durationpb.New to set the epoch and duration fields.

```go
r := &pb.TemporalRange{
    Epoch:    timestamppb.New(time.Date(2024, 11, 17, 0, 0, 0, 0, time.UTC)),
    Duration: durationpb.New(time.Hour),
}
fmt.Println(r.GetEpoch().AsTime(), r.GetDuration().AsDuration()) // 2024-11-17 00:00:00 +0000 UTC 1h0m0s
```

--------------------------------

### UUIDToProto usage example

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uuid.md

Encodes a UUID to a protobuf message; the Value field is always 16 bytes.

```go
u := uuid.New()
msg := pb.UUIDToProto(u)
fmt.Println(len(msg.Value)) // 16
```

--------------------------------

### MapPolygon usage example (Go)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/map.md

Constructs a triangle MapPolygon with three points. The shape auto-closes by connecting the first and last points.

```go
tri := &pb.MapPolygon{Points: []*pb.MapPoint{
    {X: 0, Y: 0},
    {X: 10, Y: 0},
    {X: 5, Y: 5},
}}
```

--------------------------------

### GetEpoch

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/temporal-range.md

Returns the epoch timestamp representing the start of the temporal range. This getter is nil-safe and returns nil if the field is not set.

```APIDOC
## GetEpoch

### Description
Returns the epoch timestamp representing the start of the temporal range. This getter is nil-safe and returns nil if the field is not set.

### Method
`func (x *TemporalRange) GetEpoch() *timestamppb.Timestamp`

### Parameters
None

### Returns
- `*timestamppb.Timestamp` - The epoch timestamp, or `nil` if not set.

### Example
```go
r := &pb.TemporalRange{
    Epoch: timestamppb.New(time.Date(2024, 11, 17, 0, 0, 0, 0, time.UTC)),
}
fmt.Println(r.GetEpoch().AsTime()) // 2024-11-17 00:00:00 +0000 UTC
```
```

--------------------------------

### Reading TemporalRange boundaries

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/temporal-range.md

Unmarshals a TemporalRange from data and computes the start and exclusive end boundaries using the well-known type helpers.

```go
var out pb.TemporalRange
if err := proto.Unmarshal(data, &out); err != nil { log.Fatal(err) }

start := out.GetEpoch().AsTime()      // incl. start
end := start.Add(out.GetDuration().AsDuration()) // exclusive end
fmt.Printf("range: %s .. %s\n", start, end)
```

--------------------------------

### TemporalRange proto message definition

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/temporal-range.md

Defines the TemporalRange message with an epoch timestamp and a duration. The epoch is the start boundary and the duration is the span measured from it.

```proto
message TemporalRange {
  google.protobuf.Timestamp epoch = 1;      // start of the range; reference point for the duration
  google.protobuf.Duration duration = 2;    // span of the range measured from the epoch
}
```

--------------------------------

### URI with credentials, query, and explicit port (Go)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uri.md

Builds a pb.Uri with user info, port 443, path, query, and fragment, then prints the full URI using the getters. Demonstrates formatting with fmt.Printf.

```go
u2 := &pb.Uri{
    Scheme:   "https",
    UserInfo: "user:password",
    Host:     "example.com",
    Port:     443,
    Path:     "/a/b",
    Query:    "x=1",
    Fragment: "f",
}
fmt.Printf("%s://%s@%s:%d%s?%s#%s\n",
    u2.GetScheme(), u2.GetUserInfo(), u2.GetHost(), u2.GetPort(),
    u2.GetPath(), u2.GetQuery(), u2.GetFragment())
```

--------------------------------

### Basic Version construction

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/version.md

Constructs a Version with major, minor, patch, and prerelease, then prints the version string. Outputs '1.4.2'.

```go
v := &pb.Version{Major: 1, Minor: 4, Patch: 2, Prerelease: "alpha.1"}
fmt.Printf("%d.%d.%d", v.GetMajor(), v.GetMinor(), v.GetPatch()) // 1.4.2
```

--------------------------------

### Representing a URI with a fragment (Go)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uri.md

Constructs a pb.Uri for https://example.com/page#section1 and prints its scheme, host, path, and fragment using the nil-safe getters.

```go
u := &pb.Uri{
    Scheme:   "https",
    Host:     "example.com",
    Path:     "/page",
    Fragment: "section1",
}
fmt.Println(u.GetScheme(), u.GetHost(), u.GetPath(), u.GetFragment())
```

--------------------------------

### Unmarshal and Marshal YAML with yaml.v3

Source: https://github.com/sixafter/types/blob/main/vendor/gopkg.in/yaml.v3/README.md

Complete Go program demonstrating yaml.Unmarshal and yaml.Marshal with a struct and a map. The struct uses yaml tags to rename fields and force flow style. The program prints the unmarshaled struct and map, then dumps both back to YAML.

```go
package main

import (
        "fmt"
        "log"

        "gopkg.in/yaml.v3"
)

var data = `
a: Easy!
b:
  c: 2
  d: [3, 4]
`

// Note: struct fields must be public in order for unmarshal to
// correctly populate the data.
type T struct {
        A string
        B struct {
                RenamedC int   `yaml:"c"`
                D        []int `yaml:",flow"`
        }
}

func main() {
        t := T{}
    
        err := yaml.Unmarshal([]byte(data), &t)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- t:\n%v\n\n", t)
    
        d, err := yaml.Marshal(&t)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- t dump:\n%s\n\n", string(d))
    
        m := make(map[interface{}]interface{})
    
        err = yaml.Unmarshal([]byte(data), &m)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- m:\n%v\n\n", m)
    
        d, err = yaml.Marshal(&m)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- m dump:\n%s\n\n", string(d))
}
```

--------------------------------

### Nil-safe getter on LineSegment

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/geometry.md

Shows that calling GetStart() on a nil *pb.LineSegment returns nil without panicking.

```go
var seg *pb.LineSegment
fmt.Println(seg.GetStart()) // <nil>
```

--------------------------------

### GetBuildMetadata

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/version.md

Returns the build metadata string. Nil-safe: returns an empty string if the receiver is nil.

```APIDOC
## GetBuildMetadata

### Description
Returns the build metadata string. Nil-safe: returns an empty string if the receiver is nil.

### Method
GetBuildMetadata

### Signature
`func (x *Version) GetBuildMetadata() string`

### Returns
- **string** - The build metadata, or "" if nil.

```

--------------------------------

### Constructing and validating EntityMetadata

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/entity-metadata.md

Shows how to create an EntityMetadata instance with timestamps, flags, version, tags, and attributes, then validate the tags using pb.ValidateTags. Requires importing the protobuf and structpb/timestamppb packages.

```go
import (
    "time"

    pb "github.com/sixafter/types/proto/v1/pb"
    "google.golang.org/protobuf/types/known/structpb"
    "google.golang.org/protobuf/types/known/timestamppb"
)

attrs, _ := structpb.NewStruct(map[string]any{
    "source": "API",
    "priority": "high",
    "retries": 3,
    "flags": []any{"beta"},
})

meta := &pb.EntityMetadata{
    CreatedAt:  timestamppb.New(time.Now()),
    ModifiedAt: timestamppb.New(time.Now()),
    Ephemeral:  true,
    Replicable: false,
    Immutable:  false,
    Version:    &pb.Version{Major: 1, Minor: 0, Patch: 0},
    Tags:       []string{"finance", "report2024"},
    Attributes: attrs,
}

if err := pb.ValidateTags(meta.GetTags()); err != nil {
    log.Fatalf("invalid tags: %v", err)
}
```

--------------------------------

### GetPrerelease

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/version.md

Returns the pre-release version string. Nil-safe: returns an empty string if the receiver is nil.

```APIDOC
## GetPrerelease

### Description
Returns the pre-release version string. Nil-safe: returns an empty string if the receiver is nil.

### Method
GetPrerelease

### Signature
`func (x *Version) GetPrerelease() string`

### Returns
- **string** - The pre-release version, or "" if nil.

```

--------------------------------

### Basic construction of Language (Go)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/language.md

Constructs a Language with English name and multiple BCP 47 tags, then prints the 3-letter code and each tag/display name pair.

```go
lang := &pb.Language{
    Name:             "English",
    AlphabeticCode_2: "en",
    AlphabeticCode_3: "eng",
    Bcp47Tags: []*pb.Language_Bcp47Tag{
        {Tag: "en", DisplayName: "English"},
        {Tag: "en-US", DisplayName: "English (United States)"},
        {Tag: "en-GB", DisplayName: "English (United Kingdom)"},
    },
}
fmt.Println(lang.GetAlphabeticCode_3()) // eng
for _, t := range lang.GetBcp47Tags() {
    fmt.Printf("%s = %s\n", t.GetTag(), t.GetDisplayName())
}
```

--------------------------------

### Version with build metadata and EntityMetadata

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/version.md

Creates a Version with build metadata and uses it in EntityMetadata. Includes validation of tags with pb.ValidateTags.

```go
v := &pb.Version{
    Major:         2,
    Minor:         0,
    Patch:         0,
    Prerelease:    "beta",
    BuildMetadata: "exp.sha.5114f85",
}

meta := &pb.EntityMetadata{
    Version:    v, // SemVer 2.0.0 of the entity's content
    CreatedAt:  timestamppb.Now(),
    Immutable:  true, // e.g. for a released schema document
    Tags:       []string{"schema", "v2"},
}
if err := pb.ValidateTags(meta.GetTags()); err != nil { log.Fatal(err) }
```

--------------------------------

### Get<Field>

Source: https://github.com/sixafter/types/blob/main/_autodocs/index.md

Nil-safe getter for each field of the message. Returns the field value or the zero value for scalar fields, nil for message/slice fields, or the _UNSPECIFIED enum value for enum fields when the receiver is nil or the field is unset.

```APIDOC
## Get<Field>

### Description
Nil-safe getter for each field of the message. Returns the field value or the zero value for scalar fields, nil for message/slice fields, or the _UNSPECIFIED enum value for enum fields when the receiver is nil or the field is unset.

### Method
Get<Field>

### Signature
`func (x *T) Get<Field>() <ReturnType>`

### Parameters
- **x** (*T) - Receiver of the message type.

### Returns
- **<ReturnType>** - Field value or zero value (scalar), nil (message/slice), or _UNSPECIFIED enum value (enum) when unset or receiver is nil.
```

--------------------------------

### Build 2D Euclidean point and triangle polygon

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/geometry.md

Creates a 2D Euclidean Cartesian space, a point at (10,20), and a triangle polygon with vertices (0,0), (10,0), (5,10). Prints the vertex count (3).

```go
plane := &pb.Space{
    GeometryType:    pb.GeometryType_GEOMETRY_TYPE_EUCLIDEAN,
    CoordinateSystem: pb.CoordinateSystem_COORDINATE_SYSTEM_CARTESIAN,
    Dimension:       2,
}

p := &pb.Point{
    Space: plane,
    Position: &pb.Coordinate{Values: []*pb.Scalar{
        {UnscaledValue: 10}, // 10
        {UnscaledValue: 20}, // 20
    }},
}

tri := &pb.Polygon{
    Space: plane,
    Vertices: []*pb.Coordinate{
        {Values: []*pb.Scalar{{UnscaledValue: 0}, {UnscaledValue: 0}}},
        {Values: []*pb.Scalar{{UnscaledValue: 10}, {UnscaledValue: 0}}},
        {Values: []*pb.Scalar{{UnscaledValue: 5}, {UnscaledValue: 10}}},
    },
}
fmt.Println(len(tri.GetVertices())) // 3
```

--------------------------------

### Basic construction of EmailAddress

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/email-address.md

Constructs an EmailAddress with local and domain parts and prints the combined address using getters. Getters are nil-safe.

```go
addr := &pb.EmailAddress{
    LocalPart:  "john.doe",
    DomainPart: "example.com",
}
fmt.Printf("%s@%s\n", addr.GetLocalPart(), addr.GetDomainPart()) // john.doe@example.com
```

--------------------------------

### GetHost

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uri.md

Returns the host component of the URI, or an empty string if not set. Nil-safe.

```APIDOC
## GetHost

### Description
Returns the host component of the URI, or an empty string if not set. Nil-safe.

### Method
GetHost

### Signature
`func (x *Uri) GetHost() string`

### Returns
- **string** - The host, or `""` if not set.

```

--------------------------------

### Nil handling with getters

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/email-address.md

Demonstrates that getters are nil-safe and return empty strings when the receiver is nil.

```go
var zero *pb.EmailAddress
fmt.Println(zero.GetLocalPart(), zero.GetDomainPart()) //  (empty strings)
```

--------------------------------

### Serialization with proto.Marshal and proto.Unmarshal

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/email-address.md

Shows binary serialization and deserialization of EmailAddress using the standard protobuf APIs. Handles errors with log.Fatal.

```go
data, err := proto.Marshal(addr)
if err != nil { log.Fatal(err) }

var out pb.EmailAddress
if err := proto.Unmarshal(data, &out); err != nil { log.Fatal(err) }
```

--------------------------------

### Building a fix with elevation (reader-friendly)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/geospatial.md

Constructs a GeospatialLocation with coordinate, elevation, heading, course, speed, and timestamp. Elevation uses sea-level datum and altitude in meters. Heading includes magnetic heading and accuracy. Course and speed are in degrees and m/s respectively.

```go
fix := &pb.GeospatialLocation{
    Coordinate: &pb.GeospatialCoordinate{
        Latitude:  32.9829, // Westlake, Texas
        Longitude: -97.1876,
        Elevation: &pb.GeospatialElevation{
            Datum:    pb.GeodeticDatum_GEODETIC_DATUM_SEA_LEVEL,
            Altitude: 212, // meters above mean sea level
        },
    },
    Heading: &pb.CompassHeading{MagneticHeading: 87.5, HeadingAccuracy: 1.0},
    Course:  90.0, // moving east
    Speed:   3.5,  // m/s (walking pace)
    Timestamp: timestamppb.Now(),
}
```

--------------------------------

### Uri message definition (proto)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uri.md

Defines the Uri protobuf message with fields for scheme, fragment, host, port, query, user_info, and path. Port is uint32 with 0 meaning no port given; user_info is optional credentials before host.

```proto
message Uri {
  string scheme = 1;         // e.g. "https", "ftp", "mailto"
  string fragment = 2;       // part after "#", e.g. "section1"
  string host = 3;           // domain name or IP address, e.g. "example.com"
  uint32 port = 4;           // 1–65535; 0 = no port given (scheme default applies)
  string query = 5;          // part after "?", e.g. "id=123&name=test"
  string user_info = 6;      // optional credentials before host, e.g. "user:password"
  string path = 7;           // hierarchical part after authority; may be empty
}
```

--------------------------------

### Serialize CompassHeading to wire format

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/compass-heading.md

Uses proto.Marshal and proto.Unmarshal to serialize and deserialize a CompassHeading. Requires the standard google.golang.org/protobuf APIs.

```go
data, err := proto.Marshal(h)
if err != nil { log.Fatal(err) }

var out pb.CompassHeading
if err := proto.Unmarshal(data, &out); err != nil { log.Fatal(err) }
fmt.Println(out.GetTrueHeading())
```

--------------------------------

### Handling unassigned ISO 639-1 code (Go)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/language.md

Constructs a Language for Cantonese where the 639-1 code is empty but the 639-3 code 'yue' is set, and prints the empty 2-letter code and the first BCP 47 tag.

```go
cantonese := &pb.Language{
    Name:             "Cantonese",
    AlphabeticCode_2: "",   // ISO 639-1 not assigned
    AlphabeticCode_3: "yue",
    Bcp47Tags:        []*pb.Language_Bcp47Tag{{Tag: "yue", DisplayName: "Cantonese"}},
}
fmt.Println(cantonese.GetAlphabeticCode_2()) // empty string
fmt.Println(cantonese.GetBcp47Tags()[0].GetTag())
```

--------------------------------

### Verify source archive and checksums with Cosign

Source: https://github.com/sixafter/types/blob/main/README.md

Commands to fetch the latest release, download the tarball and checksums, verify them with Cosign using the published public key, and confirm local integrity with shasum. If valid, Cosign outputs 'Verified OK'.

```sh
# Fetch the latest release tag from GitHub API (e.g., "v1.61.0")
TAG=$(curl -s https://api.github.com/repos/sixafter/types/releases/latest | jq -r .tag_name)

# Remove the leading "v" for filenames (e.g., "v1.61.0" -> "1.61.0")
VERSION=${TAG#v}

# ---------------------------------------------------------------------
# Verify the source archive using Sigstore bundles
# ---------------------------------------------------------------------

# Download the release tarball and its signature bundle
curl -LO "https://github.com/sixafter/types/releases/download/${TAG}/types-${VERSION}.tar.gz"
curl -LO "https://github.com/sixafter/types/releases/download/${TAG}/types-${VERSION}.tar.gz.sigstore.json"

# Verify the tarball with Cosign using the published public key
cosign verify-blob \
  --key "https://raw.githubusercontent.com/sixafter/types/main/cosign.pub" \
  --bundle "types-${VERSION}.tar.gz.sigstore.json" \
  "types-${VERSION}.tar.gz"

# ---------------------------------------------------------------------
# Verify the checksums manifest using Sigstore bundles
# ---------------------------------------------------------------------

curl -LO "https://github.com/sixafter/types/releases/download/${TAG}/checksums.txt"
curl -LO "https://github.com/sixafter/types/releases/download/${TAG}/checksums.txt.sigstore.json"

# Verify checksums.txt with Cosign
cosign verify-blob \
  --key "https://raw.githubusercontent.com/sixafter/types/main/cosign.pub" \
  --bundle "checksums.txt.sigstore.json" \
  "checksums.txt"

# ---------------------------------------------------------------------
# Confirm local artifact integrity
# ---------------------------------------------------------------------

shasum -a 256 -c checksums.txt
```

--------------------------------

### GetQuery

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uri.md

Returns the query component of the URI, or an empty string if not set. Nil-safe.

```APIDOC
## GetQuery

### Description
Returns the query component of the URI, or an empty string if not set. Nil-safe.

### Method
GetQuery

### Signature
`func (x *Uri) GetQuery() string`

### Returns
- **string** - The query, or `""` if not set.

```

--------------------------------

### Port semantics: 0 means no port given (Go)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uri.md

Shows that GetPort() returns 0 when no port is set, indicating the scheme default applies (e.g., 443 for https by convention, not resolved here).

```go
noPort := &pb.Uri{Scheme: "https", Host: "example.com"}
if noPort.GetPort() == 0 {
    fmt.Println("scheme default port applies") // 443 for https by convention; not resolved here
}
```

--------------------------------

### GetUserInfo

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uri.md

Returns the user info component of the URI, or an empty string if not set. Nil-safe.

```APIDOC
## GetUserInfo

### Description
Returns the user info component of the URI, or an empty string if not set. Nil-safe.

### Method
GetUserInfo

### Signature
`func (x *Uri) GetUserInfo() string`

### Returns
- **string** - The user info, or `""` if not set.

```

--------------------------------

### Version message definition (proto)

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/version.md

Defines the Version message with fields for major, minor, patch, prerelease, and build metadata. Comments document SemVer semantics per field.

```proto
message Version {
  uint32 major = 1;          // major version; 0.y.z = initial development, unstable
  uint32 minor = 2;          // incremented on backwards-compatible additions
  uint32 patch = 3;          // incremented on backwards-compatible fixes
  string prerelease = 4;     // e.g. "1.0.0-alpha.1"; lower precedence than the normal version
  string build_metadata = 5; // e.g. "1.0.0+20130313144700"; ignored for precedence
}
```

--------------------------------

### Construct and read CompassHeading with GeospatialLocation

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/compass-heading.md

Shows basic construction of CompassHeading, attaching it to a GeospatialLocation, and nil-safe getters on a zero value. The getters return zero values or nil when unset.

```go
import (
    "time"

    pb "github.com/sixafter/types/proto/v1/pb"
    "google.golang.org/protobuf/types/known/timestamppb"
)

h := &pb.CompassHeading{
    MagneticHeading: 87.5,
    TrueHeading:     90.2, // magnetic declination compensated
    HeadingAccuracy: 1.0,
    Timestamp:       timestamppb.New(time.Now()),
    X:               18.4,
    Y:               8.2,
    Z:               -42.7,
}

// Attach to a location sample
loc := &pb.GeospatialLocation{
    Coordinate: &pb.GeospatialCoordinate{Latitude: 32.9829, Longitude: -97.1876},
    Heading:    h,
    Course:     90.0,
    Speed:      3.5,
    Timestamp:  timestamppb.Now(),
}

// Getters are nil-safe even on zero values
var zero *pb.CompassHeading
fmt.Println(zero.GetMagneticHeading(), zero.GetTimestamp()) // 0 <nil>
```

--------------------------------

### GetMajor

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/version.md

Returns the major version number. Nil-safe: returns 0 if the receiver is nil.

```APIDOC
## GetMajor

### Description
Returns the major version number. Nil-safe: returns 0 if the receiver is nil.

### Method
GetMajor

### Signature
`func (x *Version) GetMajor() uint32`

### Returns
- **uint32** - The major version, or 0 if nil.

```

--------------------------------

### GetScheme

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uri.md

Returns the scheme component of the URI, or an empty string if not set. Nil-safe.

```APIDOC
## GetScheme

### Description
Returns the scheme component of the URI, or an empty string if not set. Nil-safe.

### Method
GetScheme

### Signature
`func (x *Uri) GetScheme() string`

### Returns
- **string** - The scheme, or `""` if not set.

```

--------------------------------

### Import the types Go package

Source: https://github.com/sixafter/types/blob/main/_autodocs/index.md

Import the generated Go package for the types module. The package name is `types` and the import path is `github.com/sixafter/types/proto/v1/pb`.

```go
import (
    pb "github.com/sixafter/types/proto/v1/pb"
)
```

--------------------------------

### Decimal coordinates with scale in Poincaré disk

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/geometry.md

Creates a 2D hyperbolic Poincaré disk space and a polyline with vertices using scaled decimal coordinates (0.5 = {unscaled_value: 5, scale: 1}).

```go
hyper := &pb.Space{
    GeometryType:    pb.GeometryType_GEOMETRY_TYPE_HYPERBOLIC,
    CoordinateSystem: pb.CoordinateSystem_COORDINATE_SYSTEM_POINCARE_DISK,
    Dimension:       2,
}
path := &pb.Polyline{
    Space: hyper,
    Vertices: []*pb.Coordinate{
        {Values: []*pb.Scalar{{UnscaledValue: 0}, {UnscaledValue: 0}}},
        {Values: []*pb.Scalar{{UnscaledValue: 5, Scale: 1}, {UnscaledValue: 0}}},
        {Values: []*pb.Scalar{{UnscaledValue: 5, Scale: 1}, {UnscaledValue: 5, Scale: 1}}},
    },
}
```

--------------------------------

### GetPath

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uri.md

Returns the path component of the URI, or an empty string if not set. Nil-safe.

```APIDOC
## GetPath

### Description
Returns the path component of the URI, or an empty string if not set. Nil-safe.

### Method
GetPath

### Signature
`func (x *Uri) GetPath() string`

### Returns
- **string** - The path, or `""` if not set.

```

--------------------------------

### GetMinor

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/version.md

Returns the minor version number. Nil-safe: returns 0 if the receiver is nil.

```APIDOC
## GetMinor

### Description
Returns the minor version number. Nil-safe: returns 0 if the receiver is nil.

### Method
GetMinor

### Signature
`func (x *Version) GetMinor() uint32`

### Returns
- **uint32** - The minor version, or 0 if nil.

```

--------------------------------

### String

Source: https://github.com/sixafter/types/blob/main/_autodocs/index.md

Returns a human-readable compact text representation of the message in protobuf text format. This method is part of the standard protobuf runtime surface.

```APIDOC
## String

### Description
Returns a human-readable compact text representation (protobuf text format).

### Method
String

### Signature
`func (x *T) String() string`

### Parameters
- **x** (*T) - Receiver of the message type.

### Returns
- **string** - Compact text form of the message.
```

--------------------------------

### Error-style handling for unknown/invalid values

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/geospatial.md

Shows documented semantics: nil elevation means unknown, negative course/speed mean invalid or unknown, and altitude 0 with set elevation means at the datum. Uses getters to check conditions.

```go
// Unset elevation means "unknown"
if fix.GetCoordinate().GetElevation() == nil {
    fmt.Println("elevation unknown")
}

// Negative course/speed mean invalid or unknown
if fix.GetCourse() < 0 || fix.GetSpeed() < 0 {
    log.Println("course or speed invalid")
}
// A set elevation with altitude 0 means "at the datum"
if el := fix.GetCoordinate().GetElevation(); el != nil && el.GetAltitude() == 0 {
    fmt.Println("at datum:", el.GetDatum())
}
```

--------------------------------

### GetFragment

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uri.md

Returns the fragment component of the URI, or an empty string if not set. Nil-safe.

```APIDOC
## GetFragment

### Description
Returns the fragment component of the URI, or an empty string if not set. Nil-safe.

### Method
GetFragment

### Signature
`func (x *Uri) GetFragment() string`

### Returns
- **string** - The fragment, or `""` if not set.

```

--------------------------------

### GetPatch

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/version.md

Returns the patch version number. Nil-safe: returns 0 if the receiver is nil.

```APIDOC
## GetPatch

### Description
Returns the patch version number. Nil-safe: returns 0 if the receiver is nil.

### Method
GetPatch

### Signature
`func (x *Version) GetPatch() uint32`

### Returns
- **uint32** - The patch version, or 0 if nil.

```

--------------------------------

### Go enum surface for GeometryType, CoordinateSystem, AngleUnit

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/geometry.md

Shows the generated Go methods for each enum type. The comment indicates the pattern applies to all three enums. Constants are prefixed with the enum name, and name/value maps are exported.

```go
// GeometryType, CoordinateSystem, AngleUnit are each:
type GeometryType int32 // etc.
func (x GeometryType) Enum() *GeometryType
func (x GeometryType) String() string
func (GeometryType) Descriptor() protoreflect.EnumDescriptor
func (GeometryType) Type() protoreflect.EnumType
func (x GeometryType) Number() protoreflect.EnumNumber
// Deprecated: Use .Descriptor instead.
func (GeometryType) EnumDescriptor() ([]byte, []int)
```

--------------------------------

### GetPort

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uri.md

Returns the port component of the URI, or 0 if not set. Nil-safe.

```APIDOC
## GetPort

### Description
Returns the port component of the URI, or 0 if not set. Nil-safe.

### Method
GetPort

### Signature
`func (x *Uri) GetPort() uint32`

### Returns
- **uint32** - The port, or `0` if not set.

```

--------------------------------

### GetVersion

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/entity-metadata.md

Returns the Version field of the EntityMetadata message, or nil if not set.

```APIDOC
## GetVersion

### Description
Returns the Version field of the EntityMetadata message, or nil if not set.

### Method
GetVersion

### Signature
`func (x *EntityMetadata) GetVersion() *Version`

### Returns
- **Version** (*Version) - The Version field, or nil if not set.
```

--------------------------------

### Catching errors in consumer code

Source: https://github.com/sixafter/types/blob/main/_autodocs/errors.md

Shows how to handle errors from StringToProto and ValidateTags. StringToProto wraps uuid.Parse errors with 'invalid UUID string: %w', and ValidateTags returns the first error encountered, identifying the failing tag by index.

```go
msg, err := pb.StringToProto("not-a-uuid")
if err != nil {
    // err text: invalid UUID string: ...
    log.Printf("parse failed: %v", err)
}

if err := pb.ValidateTags(meta.GetTags()); err != nil {
    // err text: tag 2 "annual report" contains disallowed character...
    return err
}
```

--------------------------------

### String

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/email-address.md

Returns a string representation of the EmailAddress message in protobuf text format, useful for logging and debugging.

```APIDOC
## String

### Description
Returns a string representation of the EmailAddress message in protobuf text format, useful for logging and debugging.

### Method
Method

### Signature
`func (x *EmailAddress) String() string`

### Parameters
None

### Returns
- **string** - The protobuf text format representation, e.g. `local_part:"john.doe" domain_part:"example.com"`.

### Example
```go
addr := &pb.EmailAddress{LocalPart: "john.doe", DomainPart: "example.com"}
fmt.Println(addr.String()) // local_part:"john.doe" domain_part:"example.com"
```
```

--------------------------------

### Version Go type

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/version.md

Generated Go struct for the Version message with protobuf tags. Contains unexported fields for internal use.

```go
type Version struct {
    Major         uint32 // protobuf:"varint,1,opt,name=major"
    Minor         uint32 // protobuf:"varint,2,opt,name=minor"
    Patch         uint32 // protobuf:"varint,3,opt,name=patch"
    Prerelease    string // protobuf:"bytes,4,opt,name=prerelease"
    BuildMetadata string // protobuf:"bytes,5,opt,name=build_metadata"
    // contains filtered or unexported fields
}
```

--------------------------------

### TimeZone fractional-hour offsets and unknown handling

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/time-zone.md

Shows fractional-hour offsets for Kolkata and St. Johns, and how to check for unknown offset via nil UtcOffset.

```go
kolkata := &pb.TimeZone{Name: "Asia/Kolkata", UtcOffset: durationpb.New(5*time.Hour + 30*time.Minute)}
stjohns  := &pb.TimeZone{Name: "America/St_Johns", UtcOffset: durationpb.New(-(3*time.Hour + 30*time.Minute))}

var unknown *pb.TimeZone
if unknown.GetUtcOffset() == nil { // unset means the offset is unknown
    fmt.Println("offset unknown")
} else if unknown.GetUtcOffset().AsDuration() == 0 {
    fmt.Println("offset is UTC")
}
```

--------------------------------

### Nil handling for TemporalRange getters

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/temporal-range.md

Shows that GetEpoch and GetDuration are nil-safe and return nil for a nil TemporalRange pointer.

```go
var zero *pb.TemporalRange
fmt.Println(zero.GetEpoch(), zero.GetDuration()) // <nil> <nil>
```

--------------------------------

### Error handling for tag validation failures

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/entity-metadata.md

Demonstrates the documented failure modes of pb.ValidateTags: disallowed characters, duplicates, and exceeding the maximum length. Each case prints the specific error message.

```go
bad := &pb.EntityMetadata{Tags: []string{"finance", "v1.0", "Finance"}}
if err := pb.ValidateTags(bad.GetTags()); err != nil {
    fmt.Println(err) // tag 1 "v1.0" contains disallowed character '.' at position 1
}

dup := &pb.EntityMetadata{Tags: []string{"finance", "finance"}}
if err := pb.ValidateTags(dup.GetTags()); err != nil {
    fmt.Println(err) // tag 1 "finance" is a duplicate
}

overlong := &pb.EntityMetadata{Tags: []string{strings.Repeat("a", pb.MaxTagLength+1)}}
if err := pb.ValidateTags(overlong.GetTags()); err != nil {
    fmt.Println(err) // tag 0 is 257 characters, exceeds maximum of 256
}
```

--------------------------------

### Descriptor

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/email-address.md

Returns the raw descriptor bytes and the path to the message descriptor within the file descriptor, used for protobuf reflection.

```APIDOC
## Descriptor

### Description
Returns the raw descriptor bytes and the path to the message descriptor within the file descriptor, used for protobuf reflection.

### Method
Method

### Signature
`func (x *EmailAddress) Descriptor() ([]byte, []int)`

### Parameters
None

### Returns
- **[]byte** - The raw descriptor bytes.
- **[]int** - The path to the message descriptor.

### Example
```go
b, path := addr.Descriptor()
```
```

--------------------------------

### ProtoToString function signature

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uuid.md

Signature for converting a protobuf UUID message to its canonical string form.

```go
func ProtoToString(msg *UUID) (string, error)
```

--------------------------------

### Standard protobuf runtime methods for message type T

Source: https://github.com/sixafter/types/blob/main/_autodocs/index.md

Every generated message struct in package types implements these standard protobuf runtime methods. Reset clears fields, String returns compact text form, ProtoMessage marks the type as proto.Message, ProtoReflect provides reflection (works on nil receivers), and Descriptor is deprecated in favor of ProtoReflect.Descriptor.

```go
func (x *T) Reset()                          // resets the message to its zero value
func (x *T) String() string                  // compact text form of the message
func (*T) ProtoMessage()                     // marker: T implements proto.Message
func (x *T) ProtoReflect() protoreflect.Message
func (*T) Descriptor() ([]byte, []int)       // Deprecated: use ProtoReflect.Descriptor instead
```

--------------------------------

### StringToProto function signature

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uuid.md

Signature for parsing a UUID string into a protobuf UUID message.

```go
func StringToProto(s string) (*UUID, error)
```

--------------------------------

### ProtoToString(msg *UUID) (string, error)

Source: https://github.com/sixafter/types/blob/main/_autodocs/errors.md

Converts a protobuf UUID message to its string representation. Returns an error if the message is invalid.

```APIDOC
## ProtoToString(msg *UUID) (string, error)

### Description
Converts a protobuf UUID message to its string representation. Returns an error if the message is invalid.

### Parameters
- **msg** (*UUID) - Required - The protobuf UUID message to convert.

### Returns
- **string** - The UUID string.
- **error** - Error if conversion fails.

### Errors
| Condition | Error message |
|-----------|---------------|
| Any `ProtoToUUID` failure (nil message, wrong length) | Same messages as `ProtoToUUID` |
```

--------------------------------

### UUIDToProto function signature

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/uuid.md

Signature for converting a standard-library uuid.UUID to a protobuf UUID message.

```go
func UUIDToProto(u uuid.UUID) *UUID
```

--------------------------------

### Polygon struct definition

Source: https://github.com/sixafter/types/blob/main/_autodocs/api-reference/geometry.md

Defines the Polygon protobuf message with a Space and counter-clockwise Vertices in 2D. At least 3 vertices are required; the first vertex must not be repeated.

```go
type Polygon struct {
    Space    *Space        // protobuf:"bytes,1,opt,name=space"
    Vertices []*Coordinate // protobuf:"bytes,2,rep,name=vertices"; counter-clockwise in 2D
    // contains filtered or unexported fields
}
```