ADR 002

ADR-002: Delegate request.payload Deserialization to Developer

Status

Proposed

Context

The MaestroTaskProcess template receives its input through a structured JSON argument (Request) with a flexible schema:

{
  "version": "v1",
  "request": {
    "payload": { ... }
  }
}

While the outer structure is well-defined by schema, the inner payload is use-case-specific and varies between projects.

Decision

The template will not deserialize the request.payload internally. Instead:

• A placeholder file RequestDeserializer.cs will be included.
• Developers are expected to implement their own logic to extract and validate payload data from the raw JSON/dictionary.

This avoids hardcoding assumptions into the template and ensures that business logic remains decoupled from generic orchestration.

Rationale

Reason	Explanation
🔄 Payload is project-specific	No single deserialization logic fits all use cases
🧩 Separation of concerns	Template handles orchestration and status; developer handles business data
🚀 Supports versioning	Developers can define their own adapters per version
🧼 Avoids false abstraction	Pretending to handle payload generically would lead to brittle logic or over-engineering

Alternatives Considered

• Deserializing via JObject internally: Rejected due to complexity and low benefit.
• Schema-based validation in template: Not feasible since schema is unknown at template time.

Consequences

• Template remains schema-compliant but payload-agnostic.
• Developer onboarding must clearly explain this responsibility.
• Input schema (request-schema.v1.json) remains accurate and versionable.

Related

• See ADR-001 (Amended): “Typed Internal Models with Custom (De)Serializers”

Owner

Christian Prior-Mamulyan cprior@gmail.com