REPO-SYNCED SPEC DOC

ADR-002: GraphQL-Style Input Objects for Updates

Date: 2026-01-16

Support documentAccepted

Source: spec/docs/adr/ADR-002-graphql-style-input.md

Open Source MarkdownBrowse Full Spec Reference

On this page

Jump to a section

Use the outline to move through longer pages without losing your place.

  1. Context
  2. Decision
  3. Consequences
  4. Positive
  5. Negative
  6. Specification Impact
  7. References

Status: Accepted Date: 2026-01-16

Context

Update operations require a mechanism to specify which fields should be modified. Several approaches exist:

  1. Flat parameters: All updateable fields at the same level as identifiers
  2. Patch operations: JSON Patch-style { op, path, value } arrays
  3. Field-specific operations: Separate operations like set_description, set_metadata
  4. Full replacement: Send complete resource data, overwriting everything
  5. Nested input objects: GraphQL-style separation of identifiers from updateable fields

Flat parameters create ambiguity about which fields are identifiers versus updateable values:

{
  operation: "edit_element",
  params: {
    element_name: "MyPersona",  // Identifier
    element_type: "persona",     // Identifier
    description: "new desc",     // Updateable?
    triggers: ["new"]            // Updateable?
  }
}

Decision

MCP-AQL adopts GraphQL-aligned nested input objects for update operations.

Update operations MUST use a nested input object to contain all updateable fields:

{
  operation: "edit_element",
  element_type: "persona",
  params: {
    element_name: "MyPersona",
    input: {
      description: "new desc",
      metadata: {
        triggers: ["new", "triggers"]
      }
    }
  }
}

Implementations MUST:

  1. Clearly separate identifier parameters from updateable fields
  2. Deep-merge input contents with existing resource state
  3. Only modify fields explicitly present in input
  4. Preserve fields not mentioned in input

Consequences

Positive

  • Clear separation: Identifiers and updateable fields are unambiguous
  • Deep merging: Nested structures merge cleanly without explicit field selection
  • Partial updates: Only specified fields change; others remain untouched
  • Familiar pattern: Aligns with GraphQL mutation conventions
  • Extensibility: New updateable fields can be added without breaking changes

Negative

  • Increased nesting: Requests are more deeply nested
  • Learning curve: Users unfamiliar with GraphQL may find pattern unusual
  • Payload size: Slight increase in request size due to input wrapper

Specification Impact

This ADR is codified in the normative specification:

Implementations MUST follow the normative specification. This ADR provides design rationale only.

References