Applying PII to ConceptAs types

The most robust way to declare that a value is personally identifiable is to mark the ConceptAs<T> type itself with [PII]. Doing so means the declaration lives exactly once — on the type — and every event property that uses that type is automatically encrypted, regardless of where or how many times it appears across your event model.

Client coverage

This page is specifically about ConceptAs<T>, a C# strongly-typed value-wrapper pattern. Kotlin and Elixir have no equivalent typed-wrapper convention in this corpus, so there’s no idiomatic way to port a “concept-level” PII declaration to them — mark the property directly instead (see PII Attribute). TypeScript already has partial coverage here since a plain wrapper class works without needing to inherit from anything.

Tip

For background on the ConceptAs<T> pattern, see Fundamentals.Concepts.

Why concept-level declaration is preferred

When you mark a property directly with [PII], you must remember to repeat the attribute on every event or read model that carries that value. If a new event is added months later and the developer forgets the annotation, a plaintext value is written to the event log with no warning.

A concept type solves this by making the protection part of the type’s identity. You cannot use PersonName without the encryption — the two are inseparable.

C#

using Cratis.Chronicle.Compliance.GDPR;
using Cratis.Chronicle.Events;

// ❌ Property-level: requires repetition across every event
[EventType]
public record PiiConceptsComparisonEmployeeRegistered([PII] string Name, string Department);

[EventType]
public record PiiConceptsComparisonEmployeeNameChanged([PII] string NewName);  // must remember [PII] again

// ✅ Concept-level: declare once, apply everywhere automatically
[PII]
public record PiiConceptsComparisonPersonName(string Value) : ConceptAs<string>(Value)
{
    public static readonly PiiConceptsComparisonPersonName NotSet = new(string.Empty);
    public static implicit operator string(PiiConceptsComparisonPersonName name) => name.Value;
    public static implicit operator PiiConceptsComparisonPersonName(string value) => new(value);
}

[EventType]
public record PiiConceptsComparisonEmployeeRegisteredGood(PiiConceptsComparisonPersonName Name, string Department);  // Name is encrypted

[EventType]
public record PiiConceptsComparisonEmployeeNameChangedGood(PiiConceptsComparisonPersonName NewName);  // also encrypted, no extra annotation needed

Defining a PII concept type

Follow the standard ConceptAs<T> pattern and add [PII] to the record declaration:

C#

using Cratis.Chronicle.Compliance.GDPR;

[PII]
public record PiiConceptsPersonName(string Value) : ConceptAs<string>(Value)
{
    public static readonly PiiConceptsPersonName NotSet = new(string.Empty);

    public static implicit operator string(PiiConceptsPersonName name) => name.Value;
    public static implicit operator PiiConceptsPersonName(string value) => new(value);
}

TypeScript

import { pii } from '@cratis/chronicle';
import { ConceptAs } from '@cratis/fundamentals';

@pii()
class PiiConceptsPersonName extends ConceptAs<string> {
    constructor(value: string) {
        super(value);
    }
}

Another example, documenting why the value is sensitive with the optional details parameter:

C#

using Cratis.Chronicle.Compliance.GDPR;

[PII("National ID number — sensitive personal identifier")]
public record PiiConceptsNationalIdNumber(string Value) : ConceptAs<string>(Value)
{
    public static readonly PiiConceptsNationalIdNumber NotSet = new(string.Empty);

    public static implicit operator string(PiiConceptsNationalIdNumber id) => id.Value;
    public static implicit operator PiiConceptsNationalIdNumber(string value) => new(value);
}

TypeScript

import { pii } from '@cratis/chronicle';
import { ConceptAs } from '@cratis/fundamentals';

@pii('National ID number — sensitive personal identifier')
class PiiConceptsNationalIdNumber extends ConceptAs<string> {
    constructor(value: string) {
        super(value);
    }
}

Placement

Concept types belong in the feature folder they are primarily associated with, or at the feature root if they are shared across slices. Do not create a separate Concepts/ folder — keep concepts co-located with the code that uses them.

Features/
├── Employees/
│   ├── PersonName.cs          ← shared across Registration and Updates slices
│   ├── Registration/
│   │   ├── Registration.cs    ← uses PersonName
│   └── Updates/
│       ├── Updates.cs         ← also uses PersonName — encryption is automatic

Combining with details

Use the optional details parameter on [PII] to document the legal basis or purpose of the PII classification. This is stored in the event schema and can be surfaced by compliance tooling.

C#

using Cratis.Chronicle.Compliance.GDPR;

[PII("Collected under GDPR Art. 6(1)(b) — necessary for contract performance. Retention: contract duration + 7 years.")]
public record PiiConceptsLegalName(string Value) : ConceptAs<string>(Value)
{
    public static readonly PiiConceptsLegalName NotSet = new(string.Empty);

    public static implicit operator string(PiiConceptsLegalName name) => name.Value;
    public static implicit operator PiiConceptsLegalName(string value) => new(value);
}

TypeScript

import { pii } from '@cratis/chronicle';
import { ConceptAs } from '@cratis/fundamentals';

@pii('Collected under GDPR Art. 6(1)(b) — necessary for contract performance. Retention: contract duration + 7 years.')
class PiiConceptsLegalName extends ConceptAs<string> {
    constructor(value: string) {
        super(value);
    }
}

What cannot be marked PII

EventSourceId types

Any type inheriting from EventSourceId or EventSourceId<T> cannot be marked with [PII]. Chronicle throws PIINotSupportedOnEventSourceId if you attempt this.

C#

using Cratis.Chronicle.Compliance.GDPR;
using Cratis.Chronicle.Events;

// ❌ Throws PIINotSupportedOnEventSourceId
[PII]
public record PiiConceptsEmployeeId(Guid Value) : EventSourceId<Guid>(Value);

Use a non-sensitive surrogate key as the event source identifier and store sensitive identity values in a separate event property:

C#

using Cratis.Chronicle.Events;

// ✅ Surrogate key as event source identifier
public record PiiConceptsSurrogateEmployeeId(Guid Value) : EventSourceId<Guid>(Value)
{
    public static PiiConceptsSurrogateEmployeeId New() => new(Guid.NewGuid());
}

// ✅ Sensitive value stored in a PII-marked concept type
[EventType]
public record PiiConceptsSurrogateEmployeeRegistered(PiiConceptsNationalIdNumber NationalId, PiiConceptsPersonName Name);