personal data (Classification(Personal.X))

Summary#

A field that holds personal data says so once, on the property: [Classification(Personal.Contact)] string Email;. Personal is a core enum, always in scope, with five levels — Contact, Identity, Financial, Content and Special (GDPR Art. 9 data). A classification says what a field is; why it is kept and for how long is a privacy category's job (the Osysharp.Privacy kit).

Signature#

public enum Personal { Contact, Identity, Financial, Content, Special }   // core — no `using` needed

[Classification(Personal.Contact)] string Email;

Description#

What the platform does with the declaration, with no further code:

• The audit trail never records the value. A change to a Personal field reaches AuditEntry.Changes as the redaction marker on both sides, whatever app.Audit.Redact lists — the trail records that the email changed, never to what. So erasing a person never has to rewrite the trail, which is append-only. Values recorded before a field was classified are rewritten once, by the app's next audit sweep, which leaves a PersonalScrub record in the trail saying how many rows it reached. The export Values a warehouse sink receives are not redacted by this: the sink is the tenant's own processor.
• Its entity can be restricted. Every type of a hierarchy holding a Personal field carries the restriction stamp, so Restriction.Restrict(row, …) can keep a row for a stated purpose (see restricted rows and purpose reads (Restriction, [PurposeRead])). An entity holding no personal data cannot be restricted, and the compiler says so.
• Who may read it is the ordinary classification clearance: list the level in app.Classifications with the roles that may see it (data classifications (app.Classifications)).

⚠ A level YOUR app classifies its own field with and does not map is masked for everyone — that is how every classification works, fail-closed. Map the Personal levels your own fields use, or such a field reads as empty for staff too (and memory derived through a secured read sees it empty as well).

A kit's personal levels#

A kit classifies its own fields (Osysharp.Conversations' messages, Osysharp.Mail's outbox addresses) and announces the levels it uses in its package.osy, one line each — personal Contact;, personal Content; — so you can see what personal data a kit brings before you read a line of it. A kit field whose level its manifest does not announce is refused wherever the compile holds both (PERSONAL_LEVEL_UNDECLARED), so the announcement stays true.

You need say nothing about a kit's levels. A kit's personal level your app does not map is read through each row's own security {} — exactly Open (below): a customer reads their own message, the desk the conversations it works. It stays personal for privacy all the same. Where you do say something, it is one of two things:

• Your mapping of the core level covers the kit's too. new Classification(Personal.Contact) { Roles = [Staff] } narrows your own contact fields and every kit's.
• A kit's level onto a classification of your own — Includes = [Osysharp.Conversations.Personal.Content] on one of your classifications — so a kit's notion of "content" never has to be yours: in a clinic, a customer's messages may be your Personal.Special, read by clinicians alone. A package's level is included once; one the package does not announce, or a package the app does not use, is refused (PERSONAL_LEVEL_MAPPING).

⚠ A role mapping that reaches a kit's field must include the role your sign-in runs as (app.AuthBootstrap's Role). A kit's sign-in reads those fields as that role — Accounts reads the code it mailed through the Mail kit's outbox — so a list that leaves it out would read them as empty and nobody could sign in. It is refused (CLASSIFICATION_SIGN_IN_ROLE), naming the fields and the one word to add; the sign-in principal reads only the rows your own grants already let it read.

Open — personal for privacy, read by whoever may read the row#

Role clearance is the wrong answer for data a person reads about themselves: a customer reading their own message in a chat widget holds no role, so a level mapped to the desk's roles masks their own words from them. Map such a level Open = true — new Classification(Personal.Content) { Open = true } — and it stays personal for every PRIVACY purpose (never recorded in the audit trail, its rows restrictable, memory following its text), while who may read it is simply whoever the row's own security {} admits. Open widens a level, never a filter: it cannot make a row readable, and a role-mapped level beside it stays masked. It is only for the core Personal levels, and it replaces Roles rather than joining it — both are refused with the reason.

Examples#

[Role] enum Role { Staff }
[Principal] entity User { [Unique, MaxLength(200)] string Email; }
[RoleGrant] entity RoleGrant { [Required] User Member; [Required] Role Level; }  // who holds which role

entity Customer {
  [Required, MaxLength(40)] string Number;
  [Classification(Personal.Contact), MaxLength(200)] string? Email;
  [Classification(Personal.Content), MaxLength(2000)] string? Notes;
  int Visits;
  security { allow read, create, update when IsAuthenticated || IsAnonymous; }
}

app = new() {
  Name = "Desk",
  Classifications = [ new Classification(Personal.Contact) { Roles = [Role.Staff] } ],
};

[Role] enum DeskRole { Agent }
[Principal] entity User { [Unique, MaxLength(200)] string Email; }
[RoleGrant] entity RoleGrant { [Required] User Member; [Required] DeskRole Role; }  // who holds which role
entity Message {
  [Classification(Personal.Content), MaxLength(2000)] string Text;
  [Classification(Personal.Contact), MaxLength(200)] string? ReplyTo;
  security { allow read, create when IsAuthenticated || IsAnonymous; }
}
app = new() {
  Name = "Chat",
  Classifications = [
    new Classification(Personal.Content) { Open = true },              // the writer reads their own words
    new Classification(Personal.Contact) { Roles = [DeskRole.Agent] }, // an address: the desk's alone
  ],
};

[Role] enum ClinicRole { Authenticator, Clinician, Reception }
app = new() {
  Classifications = [
    // The Conversations kit's `Personal.Content` (a patient's messages) is health data here.
    new Classification(Personal.Special) { Roles = [ClinicRole.Clinician, ClinicRole.Authenticator],
                                           Includes = [Osysharp.Conversations.Personal.Content] },
  ],
};
// Every other level the kits announce — addresses, names — is read through each row's own security.

See also#

• data classifications (app.Classifications) — mapping a level to the roles that may read it
• Declared personal data — say whose a row is, and the platform answers for it — saying whose data a row is, and the platform writes its privacy holder
• audit read access (app.Audit) — the audit trail and its own redaction list
• restricted rows and purpose reads (Restriction, [PurposeRead]) — keeping a row only for a stated purpose