GraphQL schema design - context dependent fields

Question

I've been stuggling to find the correct way to model a 'context dependent' field in GraphQL. Here's an example of the data structure for a workflow system. Documents move through different steps in the workflow:

workflow {
  steps {
    name
  },
  documents {
    type,
    step {
      name,
      actionToComplete
    }
  }
}

Most of it is straight forward. A Workflow has multiple Steps. Within a Workflow there are multiple Documents. Each Document is in a certain Step. To move to the next Step, an action needs to be completed by the User.

The thing I'm struggling with is the actionToComplete field. The value of the field is determined by the Context in which it is queried. So depending on the logged in User, his Role in the system and the Document (its type, does it contain sensitive info, attachments, etc), the actionToComplete is determined. The actionToComplete field is only relevant when querying the Step within a Document context. It's not relevant when just querying all the Workflow's steps, as it would not contain any meaningful data.

The issues I'm struggling with:

• The 'actionToComplete' field's value can only be determined when the Step is queried from a Document. When querying a Workflow's Steps we can not provide this field because we are missing the Document context.
• You could argue that the 'actionToComplete' field should be moved to the Document itself. This seems to create a disconnect with how people perceive this though. The natural question to ask seems to be “which action do I need to take to complete the Step the Document is in?” as opposed to “Which action do I need to complete on the Document?“. The data structure would also become less structured when more fields would be pushed up to the Document.
• Should we create a context specific version of the Step? The Document's step field could then return a context specific DocumentStep type which contains the 'actionToComplete' field. The Workflow's steps field would return a list of regular Step types. This doesn't feel right because the Step and DocumentStep types are exactly the same, just viewed from a different context

Does anybody have any advice on how to model something like this?

Answer 1

I personally don't see anything wrong with moving the field to the Document type -- you may be overthinking things. The field is still related to the document, even if conceptually it also relates to the step. It'd be different if you had multiple steps per document but that's not the case here. I also don't really see the data being flatter as a major concern.

That said, this is a good use case for explicitly creating two separate types. It's perfectly fine to have different types that represent the same domain model, particularly if you need to expose different fields depending on the parent field. We have a tendency to avoid duplication in our schemas, but in this case it makes perfect sense.