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
MetadataFieldName
The canonical field name for the metadata object (see MetadataField(AuditEvent)).
public const string MetadataFieldName = "metadata"
Field Value
TimestampFieldName
The canonical field name for the timestamp (per-sink typed/placed; see TimestampField(AuditEvent)).
public const string TimestampFieldName = "timestamp"
Field Value
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
auditEventAuditEventThe audit event.
Returns
- IReadOnlyDictionary<string, string>
The metadata, or null when none is present.
Exceptions
- ArgumentNullException
Thrown when
auditEventis 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
auditEventAuditEventThe 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
auditEventis 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
auditEventAuditEventThe audit event.
Returns
Exceptions
- ArgumentNullException
Thrown when
auditEventis null.