git:20261012.1301a3d to git:20261013.d89a1b7

---

name: cratis-fundamentals-concept-go

description: Define named Go domain values with Fundamentals.Go concepts, explicit UUID text and JSON codecs, and scalar recognition. Use when an identity or scalar must not be interchangeable with its primitive. Do not use for C# ConceptAs types, event migration or dependency-injection setup.

license: MIT

---

<!-- Copyright (c) Cratis. All rights reserved. -->

<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->

# Typed domain values in Go

Use a defined type for each domain value, not a type alias that remains

interchangeable with every UUID/string. Plain constructors are enough; adopting

concepts does not require a dependency-injection container.

## Verified product sources

The root module is standard-library-only and requires Go 1.26.

## Define and encode an identity

This complete package defines an author identity and its codecs:

```go

// Copyright (c) Cratis. All rights reserved.

// Licensed under the MIT license. See LICENSE file in the project root for full license information.

package domain

import "github.com/cratis/fundamentals.go/concepts"

// AuthorID identifies an author in the domain.

type AuthorID concepts.UUID

var _ concepts.Concept[concepts.UUID] = AuthorID{}

// ConceptValue exposes the declared scalar representation.

func (id AuthorID) ConceptValue() concepts.UUID { return concepts.UUID(id) }

// MarshalText encodes canonical dashed UUID text.

func (id AuthorID) MarshalText() ([]byte, error) {

return concepts.UUID(id).MarshalText()

}

// MarshalJSON encodes a UUID string, not a byte array.

func (id AuthorID) MarshalJSON() ([]byte, error) {

return concepts.UUID(id).MarshalJSON()

}

// UnmarshalText decodes UUID text without changing id on failure.

func (id *AuthorID) UnmarshalText(data []byte) error {

return (*concepts.UUID)(id).UnmarshalText(data)

}

// UnmarshalJSON decodes a UUID string without changing id on failure.

func (id *AuthorID) UnmarshalJSON(data []byte) error {

return (*concepts.UUID)(id).UnmarshalJSON(data)

}

// ParseAuthorID reads an identity in dashed UUID notation.

func ParseAuthorID(text string) (AuthorID, error) {

id, err := concepts.ParseUUID(text)

return AuthorID(id), err

}

```

Defined types do **not** inherit methods. Without these forwarding codecs, a

UUID-derived value can serialize as an array. Value encoding receivers also work

for unaddressable map entries; decoding needs a pointer receiver. Test text,

JSON, map-key and invalid-input round trips, not just the marker assertion.

`ParseUUID` accepts dashed 8-4-4-4-12 notation, including uppercase hex, and emits

lowercase dashed text. UUID bytes are RFC/network order, not .NET

`Guid.ToByteArray` order. Zero is `Guid.Empty`; UUID JSON decoding rejects `null`.

Use an explicit nullable representation when absence is part of the contract.

`NewUUID` returns a cryptographically random v4 UUID **and an error**.

## Recognition is not business validation

`Concept[T]` declares `ConceptValue() T`. A recognized declaration also needs

value text/JSON encoders and pointer decoders representing that scalar. Supported

representations are the built-in string/bool/numeric types and Fundamentals'

`UUID`, `DateOnly`, `TimeOnly`, `TimeSpan`; arbitrary defined replacements are not

accepted as scalar representations.

`Underlying` checks declaration metadata without running application code.

`CheckJSON` checks encoded scalar shape, not business invariants or equality to

`ConceptValue`. Put domain rules in your constructor/validation boundary and test

them; do not assume implementing a marker validates input everywhere.

`ParseDotNetGUID` is an opt-in compatibility parser for broader .NET forms. It

does not change `ParseUUID` or text/JSON/SQL codecs. Limit untrusted input and use

it only when importing that compatibility contract, not for canonical admission.

## Verify

- Compile and round-trip the named value against the pinned module without local replacements.

- Verify canonical wire bytes, zero/null policy and failure-atomic decoders.

- Check domain invariants separately from scalar recognition.