Skip to content

Start Input Union RFC document #584

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jun 20, 2019
Merged

Start Input Union RFC document #584

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
719c699
Start Input Union RFC document
binaryseed May 15, 2019
5b94058
adopt common example types
binaryseed May 17, 2019
5d04f83
add order based solution; clean-up formatting
binaryseed May 17, 2019
843851b
add tagged union
binaryseed May 22, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 119 additions & 0 deletions rfcs/InputUnion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
RFC: GraphQL Input Union
----------

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we include an explanation of the use cases/requirements/anti-requirements for input unions? They're currently scattered across lots of Github issue/PR comments which makes it hard to ensure we're all trying to solve the same problem.

## Possible Solutions
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "problems" section for each solution is great. Would it make sense to also add a pros/cons section for each possible solution?


### Value-based Discriminator field

These options rely the _value_ of a particular input field to determine the concrete type.

#### Single `__typename` field; value is the `type`

```graphql
input SummaryMetric {
min: Integer
max: Integer
}
input CounterMetric {
count: Integer
}
input HistogramMetric {
percentiles: [Integer]
}

inputUnion MetricInputUnion = SummaryMetric | CounterMetric | HistogramMetric

{__typename: "SummaryMetric", min: 123, max: 456}
{__typename: "CounterMetric", count: 789}
{__typename: "HistogramMetric", percentiles: [12, 34, 56, 78, 90]}
```

#### Single user-chosen field; value is the `type`

```graphql
input SummaryMetric {
metricType: <MetricInputUnion>
min: Integer
max: Integer
}
input CounterMetric {
metricType: <MetricInputUnion>
count: Integer
}
input HistogramMetric {
metricType: <MetricInputUnion>
percentiles: [Integer]
}

inputUnion MetricInputUnion = SummaryMetric | CounterMetric | HistogramMetric

{metricType: "SummaryMetric", min: 123, max: 456}
{metricType: "CounterMetric", count: 789}
{metricType: "HistogramMetric", percentiles: [12, 34, 56, 78, 90]}
```

#### Single user-chosen field; value is a literal

```graphql
enum MetricType {
SUMMARY
COUNTER
HISTOGRAM
}
input SummaryMetric {
metricType: MetricType::SUMMARY
min: Integer
max: Integer
}
input CounterMetric {
metricType: MetricType::COUNTER
count: Integer
}
input HistogramMetric {
metricType: MetricType::HISTOGRAM
percentiles: [Integer]
}

inputUnion MetricInputUnion = SummaryMetric | CounterMetric | HistogramMetric

{metricType: SUMMARY, min: 123, max: 456}
{metricType: COUNTER, count: 789}
{metricType: HISTOGRAM, percentiles: [12, 34, 56, 78, 90]}
```

### Structural Discrimination

These options rely on the _structure_ of the input to determine the concrete type.

#### Unique structure
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This solution only considers the set of required fields. There's a further generalization that also considers the type of each field and can discriminate fields that have the same name but non-overlapping value domains. For example you could have the following if you wanted to define a filtering API:

input StringFilter {
  propertyID: ID!
  value: String!
}

input IntegerFilter {
  propertyID: ID!
  value: Integer!
}

input union Filter = StringFilter | IntegerFilter

This could probably also be considered a further generalization of the "Single user-chosen field; value is a literal" listed earlier.

Note: I think this approach can get complicated with coercion and nested types so I'm not advocating for it but if we're trying to catalog possible solutions, it's probably worth adding to the list.


Schema Rule: Each type in the union must have a unique set of required fields

```graphql
input SummaryMetric {
name: String!
min: Float!
max: Float!
count: Integer
}
input CounterMetric {
name: String!
count: Integer!
}
input HistogramMetric {
name: String!
percentiles: [Integer]!
width: Integer
}

inputUnion MetricInputUnion = SummaryMetric | CounterMetric | HistogramMetric

{name: "my.metric", min: 123.4, max: 456.7, count: 89}
{name: "my.metric", count: 789}
{name: "my.metric", percentiles: [12, 34, 56, 78, 90]}
```

Problems:

* Optional fields could prevent determining a unique type