semanticid

README

SemanticID

SemanticIDs are an extended version of UUIDs, providing extra utility especially in the context of microservice infrastructures.

SemanticIDs consist of 3 parts:

<namespace>.<collection>.<uuid>

By choosing a meaningful namespace and collection, you can glean a lot of information about an ID just by looking at it. For the UUID part, a UUIDv4 is used to guarantee globally unique IDs.

Usage

SemanticID uses go modules internally, so it will seamlessly integrate with other projects using modules. This also means that go 1.11+ is required.
To use the library, simply do:

$ go get -u github.com/happenslol/semanticid

Then, import it into your code:

import "github.com/happenslol/semanticid"

Here's a simple example that shows how to create and parse IDs:

semanticid.DefaultNamespace = "myservice"
semanticid.DefaultCollection = "entities"

sid := semanticid.Must(semanticid.NewDefault())

parsed, err := semanticid.FromString(toParse)
if err != nil {
  fmt.Printf("something went wrong while parsing: %v", err)
}

Choosing namespace and collection

While you can generally choose any namespace and collection you want, here are a few guidelines that should make SemanticIDs more useful and consistent throughout your infrastructure:

Choose a namespace that suggests in which part of your infrastructure the ID was created. This could be the name of the microservice, the name of the external service the ID refers to, or your company's or project's name.

Use the plural of the entity name as the collection. This is just a convention, but it generally leads to very readable IDs and connects well with other parts of your applications - in practice, you can probably reuse that database name or URL for a specific entity as the collection name.

Only use lowercase letters and no special characters in the namespace and collection. This reduces visual noise and makes sure your IDs always stay URL safe and unambiguous.

Examples for good SemanticIDs:

accountservice.users.7da57b46-f4f4-4824-a8e8-0c05ff88d9a5

github.repos.87961165-15f0-4fb8-8d8b-d9ce59034565

blog.posts.59731722-54ea-4447-8e99-f4689c0c060a

Documentation

Index

• Variables
• type BSONSemanticIDCodec
  • func (*BSONSemanticIDCodec) DecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, val reflect.Value) error
  • func (*BSONSemanticIDCodec) EncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error
• type BSONSemanticIDPointerCodec
  • func (*BSONSemanticIDPointerCodec) DecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, val reflect.Value) error
  • func (*BSONSemanticIDPointerCodec) EncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error
• type SemanticID
  • func FromString(s string) (SemanticID, error)
  • func Must(sID SemanticID, err error) SemanticID
  • func New(namespace string, collection string) (SemanticID, error)
  • func NewDefault() (SemanticID, error)
  • func NewWithCollection(collection string) (SemanticID, error)
  • func NewWithNamespace(namespace string) (SemanticID, error)
  • func (sID SemanticID) IsNil() bool
  • func (sid SemanticID) MarshalJSON() ([]byte, error)
  • func (sID SemanticID) String() string
  • func (sid *SemanticID) UnmarshalJSON(b []byte) error

Variables

var DefaultCollection = "collection"

DefaultCollection is the collection that will be used if no collection is specified when creating a SemanticID.

var DefaultNamespace = "namespace"

DefaultNamespace is the namespace that will be used if no namespace is specified when creating a SemanticID.

var Separator = "."

Separator that will be used for all SemanticIDs. You should set this once and never change it for your application - Once you change it, SemanticIDs created before that point can't be parsed anymore. By default, this is set to `.` since this makes SemanticIDs entirely URL-safe.

Types

type BSONSemanticIDCodec

type BSONSemanticIDCodec struct{}

BSONSemanticIDCodec is a mongodb ValueCodec for encoding and decoding SemanticIDs to and from BSON.

func (*BSONSemanticIDCodec) DecodeValue

func (*BSONSemanticIDCodec) DecodeValue(
	dc bsoncodec.DecodeContext,
	vr bsonrw.ValueReader,
	val reflect.Value,
) error

DecodeValue implements the ValueDecoder interface.

func (*BSONSemanticIDCodec) EncodeValue

func (*BSONSemanticIDCodec) EncodeValue(
	ec bsoncodec.EncodeContext,
	vw bsonrw.ValueWriter,
	val reflect.Value,
) error

EncodeValue implements the ValueEncoder interface.

type BSONSemanticIDPointerCodec

type BSONSemanticIDPointerCodec struct{}

BSONSemanticIDCodec is a mongodb ValueCodec for encoding and decoding SemanticIDs to and from BSON.

func (*BSONSemanticIDPointerCodec) DecodeValue

func (*BSONSemanticIDPointerCodec) DecodeValue(
	dc bsoncodec.DecodeContext,
	vr bsonrw.ValueReader,
	val reflect.Value,
) error

DecodeValue implements the ValueDecoder interface.

func (*BSONSemanticIDPointerCodec) EncodeValue

func (*BSONSemanticIDPointerCodec) EncodeValue(
	ec bsoncodec.EncodeContext,
	vw bsonrw.ValueWriter,
	val reflect.Value,
) error

EncodeValue implements the ValueEncoder interface.

type SemanticID

type SemanticID struct {
	Namespace  string
	Collection string
	UUID       string
}

A SemanticID is a unique identifier for an entity that consists of a namespace, a collection and a UUID.

func FromString

func FromString(s string) (SemanticID, error)

FromString attempts to parse a given string into a SemanticID.

func Must

func Must(sID SemanticID, err error) SemanticID

Must is a convenience function that converts errors into panics on functions that create or parse a SemanticID.

func New

func New(namespace string, collection string) (SemanticID, error)

New creates a unique SemanticID with the given namespace, collection and the global separator (`.` by default).

func NewDefault

func NewDefault() (SemanticID, error)

NewDefault creates a unique SemanticID with the default namespace and collection.

func NewWithCollection

func NewWithCollection(collection string) (SemanticID, error)

NewWithCollection creates a unique SemanticID with the given collection and the default namespace.

func NewWithNamespace

func NewWithNamespace(namespace string) (SemanticID, error)

NewWithNamespace creates a unique SemanticID with the given namespace and the default collection.

func (SemanticID) IsNil

func (sID SemanticID) IsNil() bool

IsNil checks whether or not the SemanticID has any of its part set to a non-null string.

func (SemanticID) MarshalJSON

func (sid SemanticID) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for SemanticID

func (SemanticID) String

func (sID SemanticID) String() string

String outputs a string representation of the SemanticID

func (*SemanticID) UnmarshalJSON

func (sid *SemanticID) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for SemanticID