Scalars are the leaf types in a GraphQL schema. They represent concrete values like strings, numbers, and dates. Unlike object types, scalars cannot be decomposed further. They are where the query ends and actual data is returned.

Every scalar defines how values convert between the GraphQL wire format (JSON) and the .NET runtime representation. The GraphQL specification specifies five core scalars (String, Int, Float, Boolean, and ID), which form the foundation of every GraphQL server.

Hot Chocolate comes with many more scalars than the GraphQL core scalars, mapping to common .NET primitive types and structs.

Note: Hot Chocolate only exposes scalars that your schema uses. Unused scalars do not appear in the generated schema.

ID

The GraphQL ID scalar is not automatically mapped to a .NET type because it is a semantic type representing a unique identifier. You must annotate fields explicitly to use ID.

ID values are always serialized as strings in responses, but clients can provide int or string values as variables or GraphQL literals. On the server side, you can use string, int, or Guid as the runtime type for ID fields.

public sealed class Product
{
    [ID]
    public int Id { get; set; }
}

[QueryType]
public static partial class ProductQueries
{
    public static Product GetProduct([ID] int id)
    {
        // Omitted code for brevity
    }
}

DateTime Scalars

You can use HotChocolate.Types.DateTimeOptions to configure the built-in BCL-backed DateTime, LocalDateTime, and LocalTime scalars. With these options, you can:

• Set how many fractional second digits are accepted during parsing (InputPrecision, up to 9)
• Control how many fractional second digits are written during serialization (OutputPrecision, up to 7)
• Require input to match the expected scalar format before parsing (ValidateInputFormat)
• Always emit fractional seconds in serialized output (when OutputPrecision > 0), padded with trailing zeros up to OutputPrecision (AlwaysOutputFractionalSeconds)

Although the built-in scalars can parse up to 9 fractional second digits, the underlying BCL types only preserve up to 7 digits (100-nanosecond precision), so additional digits are rounded during parsing.

By default, trailing zeros are stripped from the fractional component and the fractional component is omitted entirely when zero (for example, 2023-12-24T15:30:00.5000000Z is emitted as 2023-12-24T15:30:00.5Z). Set AlwaysOutputFractionalSeconds = true to keep a fixed-width representation regardless of value. The option has no effect when OutputPrecision is 0, since there are no fractional second digits to emit.

To customize the built-in scalars, register configured scalar instances explicitly:

builder
    .AddGraphQL()
    .AddType(new DateTimeType(new DateTimeOptions
    {
        OutputPrecision = 3,
        AlwaysOutputFractionalSeconds = true
    }))
    .AddType(new LocalDateTimeType(new DateTimeOptions
    {
        OutputPrecision = 3,
        AlwaysOutputFractionalSeconds = true
    }))
    .AddType(new LocalTimeType(new DateTimeOptions
    {
        OutputPrecision = 3,
        AlwaysOutputFractionalSeconds = true
    }));

UUID Format

The UUID scalar supports multiple serialization formats:

The UuidType always returns values in the specified format. When parsing input, it tries the specified format first, then falls back to other formats.

To change the default format:

builder
    .AddGraphQL()
    .AddType(new UuidType('N'));

Any Scalar

The Any scalar is comparable to object in C#. It accepts any literal and can return any output type.

type Query {
  metadata(filter: Any): Any
}

All of the following queries are valid against an Any argument:

{
  a: metadata(filter: 1)
  b: metadata(filter: [1, 2, 3])
  c: metadata(filter: "text")
  d: metadata(filter: true)
  e: metadata(filter: { key: "value", nested: { count: 1 } })
}

Runtime type

The Any scalar uses System.Text.Json.JsonElement as its .NET runtime type. Fields annotated with Any expect resolvers to return a JsonElement.

To access an argument dynamically:

JsonElement value = context.ArgumentValue<JsonElement>("filter");

if (value.ValueKind == JsonValueKind.Object)
{
    string? name = value.GetProperty("name").GetString();
}

To deserialize into a strongly typed model:

MyFilter filter = context.ArgumentValue<MyFilter>("filter");

You can also inspect the value kind to determine how the argument was provided:

ValueKind kind = context.ArgumentKind("filter");

The ValueKind enum tells you which kind of literal represents the argument:

public enum ValueKind
{
    String,
    Integer,
    Float,
    Boolean,
    Enum,
    Object,
    Null
}

An integer literal can contain a long value, and a float literal can be a decimal or a float.

Returning dictionaries and arbitrary .NET types

By default, Any expects a JsonElement. To return common .NET types such as Dictionary<string, object> or ExpandoObject, register the JSON type converter:

builder
    .AddGraphQL()
    .AddJsonTypeConverter();

With the converter registered, resolvers can return dictionaries or any JSON-serializable object:

[GraphQLType<AnyType>]
public object GetData() => new Dictionary<string, object>
{
    { "name", "John" },
    { "age", 30 }
};

Custom type serialization

For custom reference types, register a dedicated converter to control serialization. For example, to serialize TimeZoneInfo as its string ID instead of a full JSON object:

builder
    .AddGraphQL()
    .AddTypeConverter<TimeZoneInfo, JsonElement>(
        value => JsonSerializer.SerializeToElement(value.Id));

The resolver can then return the type directly:

[GraphQLType<AnyType>]
public TimeZoneInfo GetTimezone() => TimeZoneInfo.Utc; // serializes as "UTC"

Additional Scalars Package

For more specific use cases, install the HotChocolate.Types.Scalars package:

dotnet add package HotChocolate.Types.Scalars

Many of these scalars are built on native .NET types. An email address, for example, is represented as a string, but returning a string from your resolver causes Hot Chocolate to interpret it as a StringType. You need to specify the scalar type explicitly:

[GraphQLType<EmailAddressType>]
public string GetEmail() => "[email protected]";

Learn more about explicit types

NodaTime Scalars

For NodaTime types, install the dedicated package:

dotnet add package HotChocolate.Types.NodaTime

HotChocolate.Types.NodaTime provides alternative implementations of the same five built-in date and time scalars defined by the specifications on scalars.graphql.org:

Note: The Duration scalar uses NodaTime.Duration as its runtime type. Calling AddNodaTime() does not automatically bind System.TimeSpan to DurationType or register TimeSpan↔NodaTime.Duration converters, as the runtime types are not compatible.

These NodaTime scalars expose the same @specifiedBy URLs and implement the same GraphQL scalar specifications as the built-in versions, but they use NodaTime runtime types and may differ subtly in behavior. For example, the NodaTime implementations support up to 9 fractional second digits (nanosecond precision), whereas the equivalent BCL types only support up to 7 fractional second digits (100-nanosecond precision).

Register them with AddNodaTime():

builder
    .AddGraphQL()
    .AddNodaTime();

AddNodaTime() registers the five scalar types above and configures the related CLR bindings and converters automatically.

If you prefer, you can still register individual scalar types explicitly. For example:

using NodaTimeDurationType = HotChocolate.Types.NodaTime.DurationType;

builder
    .AddGraphQL()
    .AddType<NodaTimeDurationType>();

NodaTime scalar options

HotChocolate.Types.NodaTime.DateTimeOptions configures the NodaTime-backed DateTime, LocalDateTime, and LocalTime scalars:

• InputPrecision controls how many fractional second digits are accepted during parsing, up to 9.
• OutputPrecision controls how many fractional second digits are written during serialization, up to 9.
• AlwaysOutputFractionalSeconds always emits fractional seconds in serialized output when OutputPrecision > 0, padded with trailing zeros up to OutputPrecision. By default, trailing zeros are stripped and the fractional component is omitted entirely when zero. The option has no effect when OutputPrecision is 0.

Unlike the built-in BCL-backed scalars, the NodaTime implementations preserve up to 9 fractional second digits (nanosecond precision).

If you need non-default NodaTime precision settings, register those scalar types individually instead of using AddNodaTime():

using NodaTimeDateTimeOptions = HotChocolate.Types.NodaTime.DateTimeOptions;
using NodaTimeDateTimeType = HotChocolate.Types.NodaTime.DateTimeType;
using NodaTimeLocalDateTimeType = HotChocolate.Types.NodaTime.LocalDateTimeType;
using NodaTimeLocalTimeType = HotChocolate.Types.NodaTime.LocalTimeType;

builder
    .AddGraphQL()
    .AddType(new NodaTimeDateTimeType(new NodaTimeDateTimeOptions
    {
        OutputPrecision = 3,
        AlwaysOutputFractionalSeconds = true
    }))
    .AddType(new NodaTimeLocalDateTimeType(new NodaTimeDateTimeOptions
    {
        OutputPrecision = 3,
        AlwaysOutputFractionalSeconds = true
    }))
    .AddType(new NodaTimeLocalTimeType(new NodaTimeDateTimeOptions
    {
        OutputPrecision = 3,
        AlwaysOutputFractionalSeconds = true
    }));

Binding Behavior

You can override the default .NET-to-scalar mappings by specifying type bindings explicitly:

builder
    .AddGraphQL()
    .BindRuntimeType<string, StringType>();

You can also bind scalars to arrays or complex types:

builder
    .AddGraphQL()
    .BindRuntimeType<byte[], Base64StringType>();

Custom Converters

You can reuse existing scalar types with different runtime types by registering converters. For example, to map NodaTime's OffsetDateTime to the existing DateTimeType:

public sealed class ScheduleQueries
{
    public OffsetDateTime GetDateTime(OffsetDateTime offsetDateTime)
    {
        return offsetDateTime;
    }
}

builder
    .AddGraphQL()
    .AddQueryType<ScheduleQueries>()
    .BindRuntimeType<OffsetDateTime, DateTimeType>()
    .AddTypeConverter<OffsetDateTime, DateTimeOffset>(
        x => x.ToDateTimeOffset())
    .AddTypeConverter<DateTimeOffset, OffsetDateTime>(
        x => OffsetDateTime.FromDateTimeOffset(x));

Custom Scalars

A custom scalar converts values between the GraphQL wire format and a .NET runtime type. Each custom scalar handles four conversion scenarios:

Extend ScalarType<TRuntimeType, TLiteral> to create a custom scalar:

public sealed class CreditCardNumberType : ScalarType<string, StringValueNode>
{
    private readonly ICreditCardValidator _validator;

    // You can inject services registered with the DI container
    public CreditCardNumberType(ICreditCardValidator validator)
        : base("CreditCardNumber")
    {
        _validator = validator;
        Description = "Represents a credit card number";
    }

    protected override string OnCoerceInputLiteral(StringValueNode valueLiteral)
    {
        AssertCreditCardNumberFormat(valueLiteral.Value);
        return valueLiteral.Value;
    }

    protected override string OnCoerceInputValue(
        JsonElement inputValue,
        IFeatureProvider context)
    {
        var value = inputValue.GetString()!;
        AssertCreditCardNumberFormat(value);
        return value;
    }

    protected override void OnCoerceOutputValue(
        string runtimeValue,
        ResultElement resultValue)
    {
        AssertCreditCardNumberFormat(runtimeValue);
        resultValue.SetStringValue(runtimeValue);
    }

    protected override StringValueNode OnValueToLiteral(string runtimeValue)
    {
        AssertCreditCardNumberFormat(runtimeValue);
        return new StringValueNode(runtimeValue);
    }

    private void AssertCreditCardNumberFormat(string value)
    {
        if (!_validator.ValidateCreditCard(value))
        {
            throw new LeafCoercionException(
                "The specified value is not a valid credit card number.",
                this);
        }
    }
}

Specialized Base Classes

Hot Chocolate provides specialized base classes for common scalar patterns.

Integer scalars

Use IntegerTypeBase<T> for numeric scalars with min/max constraints. The base class handles parsing, validation, and range checking automatically.

public sealed class TcpPortType : IntegerTypeBase<int>
{
    public TcpPortType()
        : base("TcpPort", min: 1, max: 65535)
    {
        Description = "A valid TCP port number (1-65535)";
    }

    protected override int OnCoerceInputLiteral(IntValueNode valueLiteral)
        => valueLiteral.ToInt32();

    protected override int OnCoerceInputValue(JsonElement inputValue)
        => inputValue.GetInt32();

    protected override void OnCoerceOutputValue(int runtimeValue, ResultElement resultValue)
        => resultValue.SetNumberValue(runtimeValue);

    protected override IValueNode OnValueToLiteral(int runtimeValue)
        => new IntValueNode(runtimeValue);
}

IntegerTypeBase validates that values fall within the specified range and throws a LeafCoercionException if they do not. To customize the error message, override FormatError:

protected override LeafCoercionException FormatError(int runtimeValue)
    => new LeafCoercionException(
        $"The value '{runtimeValue}' is not a valid TCP port. Must be between 1 and 65535.",
        this);

Hot Chocolate also provides FloatTypeBase<T> for floating-point scalars (float, double, decimal) that need min/max range validation.

Regex-based scalars

Use RegexType for string scalars that must match a specific pattern. This works well for formats like phone numbers, postal codes, or identifiers.

public sealed class HexColorType : RegexType
{
    public HexColorType()
        : base(
            "HexColor",
            "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
            "A hex color code, e.g. #FF5733 or #F53")
    {
    }
}

You can also instantiate RegexType directly when registering scalars:

builder
    .AddGraphQL()
    .AddType(new RegexType(
        "PostalCode",
        @"^\d{5}(-\d{4})?$",
        "US postal code in format 12345 or 12345-6789"));

To customize the error message for pattern validation failures, override FormatException:

protected override LeafCoercionException FormatException(string runtimeValue)
    => new LeafCoercionException(
        $"'{runtimeValue}' is not a valid hex color. Expected format: #RGB or #RRGGBB.",
        this);

Next Steps

• Need to define object types? See Object Types.
• Need to accept complex inputs? See Input Object Types.
• Need to define enums? See Enums.
• Need to add custom validation logic? See Directives.