📘 API Reference: static class – JsonConstants

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

---

📖 Summary

Provides internal JSON field name constants used during serialization and deserialization of IResult and ErrorInfo types.

JsonConstants ensure consistency, compactness, and forward compatibility in transport-agnostic serialization across HTTP, gRPC, and messaging layers.

---

💡 Design Philosophy / Rationale

The Zentient Framework uses System.Text.Json (and optionally Newtonsoft.Json) to serialize result types across multiple protocols and observability layers. JsonConstants:

• 🔒 Ensure string consistency in field names across all serializers.
• 🧩 Enable protocol interoperability with external clients that rely on specific contract shapes (e.g., OpenAPI).
• ⚙️ Facilitate unit test stability by avoiding magic strings in serialization snapshots.
• 🧼 Prevent typo-prone literals in adapters and filters.

These constants serve as a single point of truth for serializers, de/serializers, and custom converters.

---

🔖 Type Signature

internal static class JsonConstants

---

📂 Members

🔸 JsonConstants.ErrorInfo

Field Name	Constant Value	Description
Category	"category"	Category of the error (e.g., Validation, Exception).
Code	"code"	Machine-readable code (e.g., VALIDATION_ERROR, INTERNAL_SERVER_ERROR).
Message	"message"	Human-readable message.
Detail	"detail"	Extended detail or explanation. Optional.
Metadata	"metadata"	Dictionary of metadata for diagnostics.
Extensions	"extensions"	Arbitrary consumer extensions (optional, dynamic).
InnerErrors	"innererrors"	Nested error list for composite failures.

🔹 JsonConstants.Result

Field Name	Constant Value	Description
Value	"value"	Serialized value (only present in generic results).
Status	"status"	Semantic status string or code (e.g., ValidationFailed, 404).
Messages	"messages"	Diagnostic trace messages, hints, or logs.
Errors	"errors"	List of structured ErrorInfo objects.
IsSuccess	"isSuccess"	Boolean flag indicating a successful result.
IsFailure	"isFailure"	Boolean flag indicating a failed result.
ErrorMessage	"errorMessage"	Shortcut to the primary error’s Message, often for display/logging purposes.

---

🧪 Usage Examples

// Custom System.Text.Json contract resolver or property naming policy
var property = JsonConstants.Result.Errors; // yields "errors"
var errorField = JsonConstants.ErrorInfo.Code; // yields "code"

// Manually constructing a serialized result (e.g., for ProblemDetails fallback)
var json = new Dictionary<string, object?>
{
    [JsonConstants.Result.IsSuccess] = false,
    [JsonConstants.Result.Errors] = errorList,
    [JsonConstants.Result.Status] = "ValidationFailed",
    [JsonConstants.Result.Messages] = new[] { "Input is invalid." }
};

---

⚠️ Remarks

• This class is marked internal by design—intended only for serialization infrastructure within the Zentient Framework.
• Consumers should not depend on these constants unless implementing low-level serializers or adapters.
• All field names are lowerCamelCase to align with common JSON conventions and OpenAPI/GraphQL expectations.
• Any public wrapper (e.g., in Zentient.Endpoints.Http) may re-export these names for API contracts or filters.

---

🧩 Integration and Interoperability

Module / Layer	Role
System.Text.Json	Main consumer for serialization of Result<T> and ErrorInfo.
Zentient.Endpoints.Http	Serializes results into ProblemDetails-compatible JSON.
Zentient.Telemetry	Captures and parses serialized trace fields.
GrpcResultAdapter	Uses constants to map JSON fields into binary metadata.

---

📚 See Also

• ErrorInfo
• IResult
• Result<T>
• MetadataKeys
• ErrorCodes

---

🏷️ Tags

#API #Constants #Serialization #SystemTextJson #Internal #TransportContracts #ZentientCore

---

Last Updated: 2025-06-22 Version: 0.4.0