Table of Contents

Class CanonicalAuditProjection

Namespace
Excalibur.Compliance
Assembly
Excalibur.Compliance.Abstractions.dll

Single source of truth for the canonical audit-field names, order, and selection that every audit sink emits — so adding or renaming a canonical field is one edit here, not one silent edit per sink.

public static class CanonicalAuditProjection
Inheritance
CanonicalAuditProjection
Inherited Members

Remarks

This owns the canonical field schema for the wire representation (what sinks serialize). It deliberately does not own value rendering beyond the shared culture-invariant string form: a sink applies its own backend formatting on top (e.g. an object field vs a string field, or a backend-specific field name) where it genuinely differs.

Hash independence. The tamper-evidence hash input is owned separately by AuditEventCanonicalizer (in Excalibur.AuditLogging) and is not derived from this projection — the hashed field set, order, and rendering (integer enum casts, unix-millisecond timestamp) are frozen there and are intentionally distinct from the wire rendering. Changing this wire projection never perturbs the hash.

Per-sink fields. Three fields are intentionally not in the shared core because sinks treat them differently, and are exposed via dedicated members instead:

  • TimestampField(AuditEvent) — sinks emit the timestamp with backend-specific typing and placement (a typed DateTimeOffset, an ISO-8601 string, a HEC epoch, a log-entry timestamp).
  • ApplicationName — an Elasticsearch/OpenSearch index-tag sink-option (application_name); the other sinks do not expose it. Owned here so the omission is explicit and cannot silently re-drift, but emitted only by those sinks.
  • Metadata — a variable-length dictionary, emitted as a nested object/field set by each sink (see MetadataField(AuditEvent)).

Fields

ApplicationNameFieldName

The canonical field name for the Elasticsearch/OpenSearch application-name index tag.

public const string ApplicationNameFieldName = "application_name"

Field Value

string

MetadataFieldName

The canonical field name for the metadata object (see MetadataField(AuditEvent)).

public const string MetadataFieldName = "metadata"

Field Value

string

TimestampFieldName

The canonical field name for the timestamp (per-sink typed/placed; see TimestampField(AuditEvent)).

public const string TimestampFieldName = "timestamp"

Field Value

string

Methods

MetadataField(AuditEvent)

Gets the per-event metadata as the canonical metadata field, or null when the event carries no metadata. Every sink emits per-event metadata (the omission of it on any sink is accidental drift, not a supported variation).

public static IReadOnlyDictionary<string, string>? MetadataField(AuditEvent auditEvent)

Parameters

auditEvent AuditEvent

The audit event.

Returns

IReadOnlyDictionary<string, string>

The metadata, or null when none is present.

Exceptions

ArgumentNullException

Thrown when auditEvent is null.

ProjectCore(AuditEvent)

Projects the shared, ordered core canonical fields common to every sink — the string-valued fields whose name, order, and rendering are identical across backends. Timestamp, application name, and metadata are handled per-sink (see the type remarks).

public static IReadOnlyList<(string Name, string? Value)> ProjectCore(AuditEvent auditEvent)

Parameters

auditEvent AuditEvent

The audit event to project.

Returns

IReadOnlyList<(string Name, string Value)>

The ordered core canonical fields (name, culture-invariant string value or null).

Exceptions

ArgumentNullException

Thrown when auditEvent is null.

TimestampField(AuditEvent)

Gets the timestamp field rendered as an ISO-8601 round-trip ("O") string, for sinks that serialize the timestamp as a string field. Sinks emitting a typed timestamp use Timestamp directly.

public static (string Name, string? Value) TimestampField(AuditEvent auditEvent)

Parameters

auditEvent AuditEvent

The audit event.

Returns

(string Name, string Value)

The timestamp field.

Exceptions

ArgumentNullException

Thrown when auditEvent is null.