Web Analytics Made Easy - Statcounter
Skip to content

Identifiers#

Many SAMSON objects are identified by a Universally Unique Identifier (UUID), especially extensions and classes exposed through the SDK.

Use this page when you need to understand why a class registration macro asks for a UUID, when you must generate a new one, and why changing an existing UUID is usually a breaking change.

Key class#

SAMSON represents UUIDs with SBUUID.

A UUID is a 36-character identifier made of 32 hexadecimal digits and 4 hyphens, for example:

D5A1BA95-9CD4-3424-9713-06B979F5C0D9

Why UUIDs matter in SAMSON#

UUIDs are used to identify things that must remain distinguishable across builds, extensions, and runtime discovery mechanisms.

Typical cases include:

  • an extension package
  • an exposed class registered through introspection
  • objects that need stable identity across serialization and dynamic lookup workflows

For example, class registration macros such as SB_REGISTER_TYPE take a UUID so SAMSON can recognize that class reliably.

When to generate a new UUID#

Generate a new UUID when you introduce a new exposed type or another new entity that requires its own stable identity.

Do not generate a new UUID for an existing class just because you changed its implementation. Replacing a UUID means "this is a different type", which can break discovery, compatibility, or serialized data expectations.

Tooling#

The Extension Generator creates UUIDs for the classes it scaffolds.

When you later add new exposed classes manually, use the UUID Generator extension rather than inventing identifiers by hand.

UUID Generator in SAMSON

Practical advice#

  • Treat UUIDs as stable identifiers, not as version numbers.
  • Generate once, then keep them unchanged unless you intentionally introduce a new type.
  • Be especially careful with UUIDs used in class registration and serialized content.