Marking data as PII

Marking a value [PII] tells Chronicle it holds personally identifiable information under GDPR — a C# attribute, a Kotlin/Java @Pii annotation, a TypeScript @pii() decorator, or an Elixir pii macro, depending on the client. When Chronicle sees the marker on an event property or a type, it encrypts the value automatically when the event is written to the event log and decrypts it transparently on read.

Personal data rarely sits in a flat list of properties. A date of birth arrives wrapped in a VerifiedDateOfBirth value object alongside who verified it; a diagnosis carries the condition and the clinician together. Chronicle follows the marker down through that structure: whether you mark a concept nested inside a value object, or the value object type itself, encryption lands on the individual values at the bottom. The document keeps its shape, each value stays independently encrypted, and the release on read mirrors the encryption on write.

C#

using Cratis.Chronicle.Compliance.GDPR;

Kotlin

import io.cratis.chronicle.compliance.Pii

Java

import io.cratis.chronicle.compliance.Pii;

Elixir

# No explicit import is required. `pii/1,2` becomes available automatically
# from `use Chronicle.Events.EventType` or `use Chronicle.ReadModels.ReadModel`,
# and `pii/0,1` becomes available automatically from `use Chronicle.Concept`.

TypeScript

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

Client coverage

Chronicle resolves [PII] on a property through four paths, checked in this order: a marker on the property itself, a marker on the type that declares the property, a marker on the property’s own type (the concept case), and a marker on a matching constructor parameter. C#‘s PIIMetadataProvider implements all four.

Path	C#	Kotlin/Java	TypeScript	Elixir
Property	yes	yes	yes	yes
Declaring type	yes	yes	yes	no
Property type (concept)	yes	yes	yes	yes
Constructor parameter	yes	yes	no	n/a

Every client covers the property path, and every client resolves a marker on the property’s concept type — declare it once on the concept and every event and read model using that type is covered. That is the preferred approach; see Declaring PII on a concept.

Two gaps remain. Elixir has no way to mark a whole multi-field struct as PII in one declaration — a concept wraps a single value, so mark the fields you need. And the TypeScript decorator does not read a constructor parameter, which matters only for classes that take their values positionally rather than as declared properties.

Whichever path applies, the marker lands on the individual leaf values in the schema, not on the object that contains them — so a concept nested inside a value object is still encrypted, and the document keeps its shape on release.

Marker signatures

The marker, in each client:

// C#
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Property | AttributeTargets.Parameter)]
public sealed class PIIAttribute(string details = "") : Attribute

// Kotlin / Java
@Target(AnnotationTarget.FIELD, AnnotationTarget.PROPERTY, AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
annotation class Pii(val description: String = "")

// TypeScript
export function pii(details?: string): PropertyDecorator & ClassDecorator

// Elixir
defmacro pii(field, details \\ "")

The optional details parameter lets you record why the value is classified as PII — for example, the legal basis under which it is collected or the retention period. This information is stored in the event schema and can be used by compliance reporting tools.

C#

using Cratis.Chronicle.Compliance.GDPR;

[PII("Collected under GDPR Art. 6(1)(b) — necessary for contract performance")]
public record PiiAttrPersonName(string Value) : ConceptAs<string>(Value);

Kotlin

import io.cratis.chronicle.compliance.Pii
import io.cratis.chronicle.concepts.ConceptAs

@Pii(description = "Collected under GDPR Art. 6(1)(b) — necessary for contract performance")
data class PiiAttrPersonName(override val value: String) : ConceptAs<String>

Java

import io.cratis.chronicle.compliance.Pii;
import io.cratis.chronicle.concepts.ConceptAs;

@Pii(description = "Collected under GDPR Art. 6(1)(b) — necessary for contract performance")
record PiiAttrPersonName(String value) implements ConceptAs<String> {
    @Override
    public String getValue() {
        return value;
    }
}

Elixir

defmodule MyApp.Compliance.Pii.PersonNameWithDetails do
  use Chronicle.Concept, type: :string
  pii("Collected under GDPR Art. 6(1)(b) — necessary for contract performance")
end

TypeScript

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

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

Where you can mark PII

Target	Supported	Notes
ConceptAs<T> class	Yes	Preferred approach — marks the concept type itself as PII
Event property	Yes	Marks a single property of an event as PII
Value object class	Yes	Marks every value the type holds as PII, however deeply nested
Property typed as a value object	Yes	Same effect, scoped to that one property
Collection property	Yes	The collection is encrypted as a whole — see Collections are encrypted as a whole
Geospatial (Point, LineString, Polygon)	No	Never classified inside, and marking one encrypts a value that cannot be materialized back after erasure — see Geospatial values are not looked inside
Polymorphic base type or dictionary	No	Chronicle cannot classify values inside either and fails rather than store them unprotected
EventSourceId or EventSourceId<T>	No	Throws PIINotSupportedOnEventSourceId at runtime

This table describes what the C# client validates. No other client performs the same checks yet: Kotlin/Java, TypeScript, and Elixir don’t verify that a [PII]-marked type actually extends the client’s ConceptAs<T> equivalent, and none of them throws an equivalent of PIINotSupportedOnEventSourceId when you mark an event-source identifier type — the marker is silently accepted rather than rejected. Treat both restrictions as rules to follow across every client, not ones every client enforces for you today.

Applying to an event property

You can mark a single property on an event record as PII. This is useful when the property type is a primitive and you cannot or do not want to introduce a dedicated concept type.

C#

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

[EventType]
public record PiiAttrEmployeeRegistered(
    [PII] string FirstName,
    [PII] string LastName,
    string Department);

Kotlin

import io.cratis.chronicle.compliance.Pii
import io.cratis.chronicle.events.EventType

@EventType
data class PiiAttrEmployeeRegistered(
    @Pii val firstName: String,
    @Pii val lastName: String,
    val department: String
)

Java

import io.cratis.chronicle.compliance.Pii;
import io.cratis.chronicle.events.EventType;

@EventType
record PiiAttrEmployeeRegistered(
        @Pii String firstName,
        @Pii String lastName,
        String department) {
}

Elixir

defmodule MyApp.Events.PiiAttrEmployeeRegistered do
  use Chronicle.Events.EventType, id: "pii-attr-employee-registered"

  defstruct [:first_name, :last_name, :department]

  pii(:first_name)
  pii(:last_name)
end

TypeScript

import { eventType, pii } from '@cratis/chronicle';

@eventType()
class PiiAttrEmployeeRegistered {
    @pii() firstName = '';
    @pii() lastName = '';
    department = '';
}

When this event is written, FirstName and LastName are encrypted. Department is stored as plaintext.

Applying to a ConceptAs type

The preferred approach is to mark the ConceptAs<T> type itself as PII. Every property across every event that uses this type is then automatically encrypted — you declare the rule once and it applies everywhere.

C#

using Cratis.Chronicle.Compliance.GDPR;

[PII]
public record PiiAttrConceptPersonName(string Value) : ConceptAs<string>(Value)
{
    public static readonly PiiAttrConceptPersonName NotSet = new(string.Empty);
    public static implicit operator string(PiiAttrConceptPersonName name) => name.Value;
    public static implicit operator PiiAttrConceptPersonName(string value) => new(value);
}

Kotlin

import io.cratis.chronicle.compliance.Pii
import io.cratis.chronicle.concepts.ConceptAs

@Pii
data class PiiAttrConceptPersonName(override val value: String) : ConceptAs<String>

Java

import io.cratis.chronicle.compliance.Pii;
import io.cratis.chronicle.concepts.ConceptAs;

@Pii
record PiiAttrConceptPersonName(String value) implements ConceptAs<String> {
    @Override
    public String getValue() {
        return value;
    }
}

Elixir

defmodule MyApp.Compliance.Pii.PersonName do
  use Chronicle.Concept, type: :string
  pii()
end

TypeScript

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

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

Tip

Use Fundamentals.Concepts as a reference for the full ConceptAs<T> pattern. For guidance on declaring compliance on concept types, see Declaring PII on a concept.

Applying to a value object

Not every piece of personal data is a single value. When a whole value object is personal — a diagnosis, a passport, a home address — mark the type itself. Every value it holds is then treated as PII wherever that type appears, without annotating each member.

C#

using Cratis.Chronicle.Compliance.GDPR;

// Every value this type holds is personal, so mark the type once.
[PII]
public record PiiAttrDiagnosis(string Condition, string DiagnosedBy);

// Both Condition and DiagnosedBy are encrypted wherever a PiiAttrDiagnosis appears.
public record PiiAttrPatientRecord(string Name, PiiAttrDiagnosis Diagnosis);

Kotlin

import io.cratis.chronicle.compliance.Pii

// Every value this type holds is personal, so mark the type once.
@Pii
data class PiiAttrDiagnosis(val condition: String, val diagnosedBy: String)

// Both condition and diagnosedBy are encrypted wherever a PiiAttrDiagnosis appears.
data class PiiAttrPatientRecord(val name: String, val diagnosis: PiiAttrDiagnosis)

Java

import io.cratis.chronicle.compliance.Pii;

// Every value this type holds is personal, so mark the type once.
@Pii
record PiiAttrDiagnosis(String condition, String diagnosedBy) {
}

// Both condition and diagnosedBy are encrypted wherever a PiiAttrDiagnosis appears.
record PiiAttrPatientRecord(String name, PiiAttrDiagnosis diagnosis) {
}

Elixir

Elixir does not support this workflow yet.

TypeScript

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

// Every value this type holds is personal, so mark the type once.
@pii()
class PiiAttrDiagnosis {
    condition = '';
    diagnosedBy = '';
}

// Both condition and diagnosedBy are encrypted wherever a PiiAttrDiagnosis appears.
class PiiAttrPatientRecord {
    name = '';
    diagnosis: PiiAttrDiagnosis = new PiiAttrDiagnosis();
}

Chronicle pushes the marker down to the individual values rather than encrypting the object as one blob. In storage you still see a Diagnosis sub-document with a Condition and a DiagnosedBy field; both hold ciphertext. That matters for more than tidiness: the shape is what lets the read model materialize back into its value-object type, and it keeps each value separately encrypted rather than fused into a single opaque string.

The same happens when you mark a property whose type is a value object — the effect is identical, just scoped to that one property instead of to the type everywhere.

Nesting

The marker does not have to sit at the top level. A ConceptAs<T> marked [PII] is found wherever it ends up — directly on an event, one level down inside a value object, or deeper still.

C#

using Cratis.Chronicle.Compliance.GDPR;

[PII]
public record PiiAttrDateOfBirth(string Value) : ConceptAs<string>(Value)
{
    public static implicit operator PiiAttrDateOfBirth(string value) => new(value);
}

// The concept sits one level down, inside a value object.
public record PiiAttrVerifiedDateOfBirth(PiiAttrDateOfBirth DateOfBirth, string VerifiedBy);

// Chronicle still finds it: dateOfBirth.dateOfBirth is encrypted, verifiedBy is not.
public record PiiAttrExpressVerification(string Name, PiiAttrVerifiedDateOfBirth DateOfBirth);

Kotlin

import io.cratis.chronicle.compliance.Pii
import io.cratis.chronicle.concepts.ConceptAs

@Pii
data class PiiAttrDateOfBirth(override val value: String) : ConceptAs<String>

// The concept sits one level down, inside a value object.
data class PiiAttrVerifiedDateOfBirth(val dateOfBirth: PiiAttrDateOfBirth, val verifiedBy: String)

// Chronicle still finds it: dateOfBirth.dateOfBirth is encrypted, verifiedBy is not.
data class PiiAttrExpressVerification(val name: String, val dateOfBirth: PiiAttrVerifiedDateOfBirth)

Java

import io.cratis.chronicle.compliance.Pii;
import io.cratis.chronicle.concepts.ConceptAs;

@Pii
record PiiAttrDateOfBirth(String value) implements ConceptAs<String> {
    @Override
    public String getValue() {
        return value;
    }
}

// The concept sits one level down, inside a value object.
record PiiAttrVerifiedDateOfBirth(PiiAttrDateOfBirth dateOfBirth, String verifiedBy) {
}

// Chronicle still finds it: dateOfBirth.dateOfBirth is encrypted, verifiedBy is not.
record PiiAttrExpressVerification(String name, PiiAttrVerifiedDateOfBirth dateOfBirth) {
}

Elixir

defmodule MyApp.Compliance.Pii.DateOfBirth do
  use Chronicle.Concept, type: :string
  pii()
end

# The concept sits one level down, inside a plain (non-concept) value object.
defmodule MyApp.Compliance.Pii.VerifiedDateOfBirth do
  defstruct date_of_birth: %MyApp.Compliance.Pii.DateOfBirth{}, verified_by: ""
end

# Chronicle still finds it: dateOfBirth.dateOfBirth is encrypted, verifiedBy is not.
defmodule MyApp.Compliance.Pii.ExpressVerification do
  use Chronicle.Events.EventType, id: "pii-express-verification"
  defstruct name: "", date_of_birth: %MyApp.Compliance.Pii.VerifiedDateOfBirth{}
end

TypeScript

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

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

// The concept sits one level down, inside a value object.
class PiiAttrVerifiedDateOfBirth {
    dateOfBirth: PiiAttrDateOfBirth = new PiiAttrDateOfBirth('');
    verifiedBy = '';
}

// Chronicle still finds it: dateOfBirth.dateOfBirth is encrypted, verifiedBy is not.
class PiiAttrExpressVerification {
    name = '';
    dateOfBirth: PiiAttrVerifiedDateOfBirth = new PiiAttrVerifiedDateOfBirth();
}

Here only dateOfBirth.dateOfBirth is encrypted. verifiedBy sits beside it in the same value object and stays readable, because the concept carries the classification, not its container.

This is what makes concept-level [PII] worth reaching for: you declare the rule once on the type, and it holds no matter how the value is later composed into events and read models.

Constraints

EventSourceId is not supported

Applying [PII] to a type that inherits from EventSourceId or EventSourceId<T> throws PIINotSupportedOnEventSourceId at runtime:

C#

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

// ❌ This will throw PIINotSupportedOnEventSourceId
[PII]
public record PiiAttrEmployeeId(Guid Value) : EventSourceId<Guid>(Value);

Kotlin

import io.cratis.chronicle.compliance.Pii
import io.cratis.chronicle.concepts.EventSourceId

// This will throw PiiNotSupportedOnEventSourceId
@Pii
data class PiiAttrEmployeeId(override val value: String) : EventSourceId

Java

import io.cratis.chronicle.compliance.Pii;
import io.cratis.chronicle.concepts.EventSourceId;

// This will throw PiiNotSupportedOnEventSourceId
@Pii
record PiiAttrEmployeeId(String value) implements EventSourceId {
    @Override
    public String getValue() {
        return value;
    }
}

Elixir

# Raises ArgumentError at compile time — PII is not supported on a
# Chronicle.Concept declared with event_source_id: true.
#
# defmodule MyApp.Compliance.Pii.EmployeeId do
#   use Chronicle.Concept, type: :uuid, event_source_id: true
#   pii()
# end

TypeScript

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

// TypeScript has no dedicated EventSourceId<T> type - the event source identifier is always
// the conventional 'eventSourceId' property. Marking it @pii() throws
// PIINotSupportedOnEventSourceId at decoration time, for the same reason C# forbids [PII] on
// EventSourceId<T>: encrypting it would make its own decryption key unfindable.
class PiiAttrEmployeeId {
    @pii() eventSourceId = '';
}

Event source identifiers are used to look up encryption keys and group events. Encrypting them would make key lookup impossible. If the identifier itself is sensitive, use a non-sensitive surrogate (such as a random Guid) as the event source identifier and store the sensitive value in a [PII]-marked event property.

Geospatial values are not looked inside

One [PII] marker anywhere turns the compliance pass on for the whole document, so every other value in that event or read model is visited too. Most of them are ordinary properties the schema declares, and Chronicle walks straight through them looking for markers.

A geospatial value is different. Point, LineString and Polygon are objects on the wire — GeoJSON, a type and a coordinates pair — but Chronicle stores and materializes each as one typed value, so its schema is a leaf carrying only a format and those wire members belong to the type’s own converter. The compliance pass stops there and leaves the value exactly as it is: written and read back verbatim, in the clear.

That is normally what you want, because a venue sitting beside a [PII] organizer name is public data. Marking the geospatial property [PII] is not a supported alternative — see Geospatial values alongside PII for why.

Note

Two other shapes have members the schema does not declare: a polymorphic base type, kept open so a derived payload round-trips verbatim, and a dictionary, whose keys are runtime data rather than declared properties. Chronicle cannot classify values inside either — and rather than write values it was told are personal into the store unprotected, it fails: applying compliance to a document holding one raises CompliancePropertyNotFoundInSchema. Model the data as a value object with declared properties instead; the marker travels down through anything the schema declares, however deeply nested.

Collections are encrypted as a whole

A [PII] marker on a collection property behaves differently from one on a value object. The collection is encrypted as a single value rather than element by element, and its shape is restored when it is released. That keeps the data protected, but the individual elements are not separately encrypted and cannot be queried or indexed on the server.

When you need per-element encryption, model the collection as its own person-scoped read model keyed by the subject and join at the query edge, rather than nesting it inside a larger document.

Details parameter

The details parameter is a free-text description stored in the event schema. It is never used for encryption — it exists solely to record why a value is classified as PII for compliance documentation and auditing purposes.

C#

using Cratis.Chronicle.Compliance.GDPR;

[PII("Full legal name — required for contract identification")]
public record PiiAttrLegalName(string Value) : ConceptAs<string>(Value);

Kotlin

import io.cratis.chronicle.compliance.Pii
import io.cratis.chronicle.concepts.ConceptAs

@Pii(description = "Full legal name — required for contract identification")
data class PiiAttrLegalName(override val value: String) : ConceptAs<String>

Java

import io.cratis.chronicle.compliance.Pii;
import io.cratis.chronicle.concepts.ConceptAs;

@Pii(description = "Full legal name — required for contract identification")
record PiiAttrLegalName(String value) implements ConceptAs<String> {
    @Override
    public String getValue() {
        return value;
    }
}

Elixir

defmodule MyApp.Compliance.Pii.LegalName do
  use Chronicle.Concept, type: :string
  pii("Full legal name — required for contract identification")
end

TypeScript

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

@pii('Full legal name — required for contract identification')
class PiiAttrLegalName extends ConceptAs<string> {
    constructor(value: string) {
        super(value);
    }
}