📘 API Reference: static class – MetadataKeys

Namespace: Zentient.Results.Constants Assembly: Zentient.Results.dll Available since: v0.1.0

---

📖 Summary

Defines reserved string keys used for populating the Metadata dictionary within ErrorInfo, enabling enhanced diagnostics, exception propagation, and protocol metadata injection.

MetadataKeys standardize the structure of diagnostic metadata in error models, making it easier to parse, trace, and display extended error context in structured logs, UI messages, and observability tools.

---

💡 Design Philosophy / Rationale

The purpose of MetadataKeys is to:

• 🧩 Enable extensibility of ErrorInfo via a common metadata structure.
• 📐 Promote semantic clarity by avoiding ad-hoc key names in the Metadata dictionary.
• 🧪 Facilitate structured exception handling by preserving exception details as metadata.
• 🔍 Support advanced use cases like telemetry enrichment, request auditing, and CQRS observability.

This allows internal consumers and adaptors (HTTP, gRPC, logging) to operate consistently across multiple error contexts while still supporting freeform metadata injection by external consumers.

---

🔖 Type Signature

public static class MetadataKeys

---

📂 Members

Key Name	Value String	Description
ExceptionMessage	"exceptionMessage"	Captures the raw exception message string.
ExceptionStackTrace	"exceptionStackTrace"	Full stack trace associated with the exception (if available).
ExceptionSource	"exceptionSource"	The originating source (e.g., namespace or assembly) of the exception.
ExceptionType	"exceptionType"	Fully qualified CLR type name of the exception (e.g., System.ArgumentNullException).
ValidationErrors	"validationErrors"	Collection of validation failure objects (typically as serialized array).
OriginalRequestUri	"originalRequestUri"	URI of the HTTP/gRPC request that triggered the error (for traceability).

---

🧪 Usage Examples

var error = new ErrorInfo(
    category: ErrorCategory.Exception,
    code: ErrorCodes.Exception,
    message: "An unexpected error occurred.",
    metadata: new Dictionary<string, string?>
    {
        [MetadataKeys.ExceptionMessage] = exception.Message,
        [MetadataKeys.ExceptionType] = exception.GetType().FullName,
        [MetadataKeys.ExceptionStackTrace] = exception.StackTrace
    }
);

var validationError = new ErrorInfo(
    category: ErrorCategory.Validation,
    code: ErrorCodes.Validation,
    message: "One or more fields are invalid.",
    metadata: new Dictionary<string, string?>
    {
        [MetadataKeys.ValidationErrors] = JsonSerializer.Serialize(validationFailures)
    }
);

---

⚠️ Remarks

• Keys are intentionally short and lowercase camelCase for consistent serialization in JSON (e.g., for ProblemDetails).
• Consumers should avoid redefining these constants manually. Always use MetadataKeys to avoid typos and mismatches.
• Metadata values are always string or null; consumers must parse/deserialize structured content where needed.
• Optional by design—absence of a key does not indicate an invalid error structure.

---

🧩 Integration and Interoperability

Consumer Layer	Usage
ErrorInfo	Main consumer of keys within the Metadata dictionary.
HttpResultAdapter	Injects OriginalRequestUri during response transformation.
GrpcResultAdapter	Serializes structured metadata into trailers or binary headers.
TelemetryEnricher	Uses exception-related metadata for log enrichment and correlation.
FluentValidation	Writes serialized validation failures using ValidationErrors.

---

📚 See Also

• ErrorInfo
• ErrorCodes
• IResult
• JsonConstants
• Error Modeling Architecture

---

🏷️ Tags

#API #ErrorModel #Metadata #Diagnostics #Immutable #ZentientCore #StructuredErrors

---

Last Updated: 2025-06-22 Version: 0.4.0