Identity (TypeID)

Every entity in Shield gets a type-prefixed, K-sortable, UUIDv7-based identifier using the TypeID specification. IDs are validated at parse time to ensure the prefix matches the expected type.

Prefix table

Constructors

Each type has a constructor that generates a new UUIDv7-based ID with the correct prefix:

import "github.com/xraph/shield/id"

scanID    := id.NewScanID()           // scan_01h...
policyID  := id.NewPolicyID()         // pol_01h...
instID    := id.NewInstinctID()       // inst_01h...
judgID    := id.NewJudgmentID()       // jdg_01h...
profileID := id.NewSafetyProfileID()  // sprf_01h...

Parsing

Parse functions validate both the format and the prefix:

scanID, err := id.ParseScanID("scan_01h2xcejqtf2nbrexx3vqjhp41")
// err is nil — prefix matches

_, err = id.ParseScanID("inst_01h455vb4pex5vsknk084sn02q")
// err: id: expected prefix "scan", got "inst"

Use id.ParseAny when you need to accept any valid TypeID regardless of prefix:

anyID, err := id.ParseAny("inst_01h455vb4pex5vsknk084sn02q")
// anyID.Prefix() == "inst"

K-sortability

TypeIDs embed UUIDv7 timestamps, making them naturally sortable by creation time. This means:

• Database indexes on TypeID columns are efficient for time-range queries
• IDs created later always sort after earlier IDs
• No need for separate created_at indexes for ordering