Skip to content

Update migration guide: Any / Json scalar changes #9331

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
michaelstaib merged 2 commits into from
Mar 9, 2026
Merged

Update migration guide: Any / Json scalar changes #9331

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
be69530
Update migration guide: `Any` input changes and `OperationRequestBuil…
N-Olbert Mar 8, 2026
2e0f023
Merge branch 'main' into AnyJsonChange
michaelstaib Mar 9, 2026
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
57 changes: 57 additions & 0 deletions website/src/docs/hotchocolate/v16/migrating/migrate-from-15-to-16.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -438,6 +438,61 @@ builder.Services
value => JsonSerializer.SerializeToElement(value.Id));
```

### Any input fields now deserialize complex types as `JsonElement`

Previously, complex input values for `Any`-typed input variables were deserialized as `IDictionary<string, object?>`.
Copy link
Copy Markdown
Member

@michaelstaib michaelstaib Mar 9, 2026

Choose a reason for hiding this comment

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

while this is true ... you can add the old behavior by adding AddJsonTypeCoverter

services
    .AddGraphQLServer()
    .AddJsonTypeConverter()

Copy link
Copy Markdown
Member

@michaelstaib michaelstaib Mar 9, 2026

Choose a reason for hiding this comment

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

I mean in the example below you still get the JsonElement but with the JsonTypeConverter you can support other types.

They are now deserialized as `JsonElement`, aligning input behavior with arbitrary output types.

```csharp
public string Foo([GraphQLType<AnyType>]object? input) => input?.GetType().Name;
```

```graphql
query {
foo(input: { key: "value" })
# Now returns: "JsonElement"
# Previously (v15): "Dictionary`2"
}
```

### Runtime objects passed as variables to OperationRequestBuilder are now serialized as JSON

Passing CLR objects via `OperationRequestBuilder.SetVariableValues(Dictionary<string, object?>)` now serializes the values as JSON.

You may prefer providing variables directly as JSON:

```csharp
var requestBuilder = new OperationRequestBuilder();
requestBuilder.SetVariableValues("""{ "id": 42 }""");
```

Note that this can lead to errors if the emitted JSON for a type is not valid for the corresponding GraphQL scalar, f. e. du to format restrictions.
For example, a `DateTime` value can no longer be used to fill a `Date` scalar since the JSON format does not match the expected yyyy-MM-dd format.

You can also bypass this by annotating your types with custom JsonConverters.

If you need to pass an Upload scalar value, you can do the following:
```csharp
var requestBuilder = new OperationRequestBuilder();
requestBuilder.SetVariableValues("""{ "file" : "yourKey" }""");
requestBuilder.Features.Set<IFileLookup>(fileLookup);

public class FileLookup : IFileLookup
{
public bool TryGetFile(string name, [NotNullWhen(true)] out IFile? file)
{
if (name == "yourKey")
{
file = new StreamFile("Foo.txt", () => new MemoryStream());
return true;
}

file = null;
return false;
}
}
```

## `Byte` and `SignedByte` types renamed

- The GraphQL type `Byte` has been renamed to `UnsignedByte` (CLR type: `byte`).
Expand Down Expand Up @@ -615,6 +670,8 @@ builder.Services
new HttpResponseFormatterOptions { /* ... */ },
incrementalDeliveryFormat: IncrementalDeliveryFormat.Version_0_1);
```
## `OperationRequestBuilder.AddVariableValues` renamed to `SetVariableValues`
`OperationRequestBuilder.AddVariableValues` has been renamed to `SetVariableValues`.

# Deprecations

Expand Down