@@ -327,17 +327,14 @@ the built-in scalar types should be omitted for brevity.
327327** Result Coercion**
328328
329329A GraphQL server, when preparing a field of a given scalar type, must uphold the
330- contract the scalar type describes, either by coercing the value or
331- producing a field error.
332-
333- For example, a GraphQL server could be preparing a field with the scalar type
334- ` Int ` and encounter a floating-point number. Since the server must not break the
335- contract by yielding a non-integer, the server should truncate the fractional
336- value and only yield the integer value. If the server encountered a boolean
337- ` true ` value, it should return ` 1 ` . If the server encountered a string, it may
338- attempt to parse the string for a base-10 integer value. If the server
339- encounters some value that cannot be reasonably coerced to an ` Int ` , then it
340- must raise a field error.
330+ contract the scalar type describes, either by coercing the value or producing a
331+ field error if a value cannot be coerced or if coercion may result in data loss.
332+
333+ A GraphQL service may decide to allow coercing different internal types to the
334+ expected return type. For example when coercing a field of type ` Int ` a boolean
335+ ` true ` value may produce ` 1 ` or a string value ` "123" ` may be parsed as base-10
336+ ` 123 ` . However if internal type coercion cannot be reasonably performed without
337+ losing information, then it must raise a field error.
341338
342339Since this coercion behavior is not observable to clients of the GraphQL server,
343340the precise rules of coercion are left to the implementation. The only
@@ -377,9 +374,15 @@ that type to represent this scalar.
377374
378375** Result Coercion**
379376
380- GraphQL servers should coerce non-int raw values to Int when possible
381- otherwise they must raise a field error. Examples of this may include returning
382- ` 1 ` for the floating-point number ` 1.0 ` , or ` 2 ` for the string ` "2" ` .
377+ Fields returning the type ` Int ` expect to encounter 32-bit integer
378+ internal values.
379+
380+ GraphQL servers may coerce non-integer internal values to integers when
381+ reasonable without losing information, otherwise they must raise a field error.
382+ Examples of this may include returning ` 1 ` for the floating-point number ` 1.0 ` ,
383+ or returning ` 123 ` for the string ` "123" ` . In scenarios where coercion may lose
384+ data, raising a field error is more appropriate. For example, a floating-point
385+ number ` 1.2 ` should raise a field error instead of being truncated to ` 1 ` .
383386
384387** Input Coercion**
385388
@@ -403,9 +406,13 @@ should use that type to represent this scalar.
403406
404407** Result Coercion**
405408
406- GraphQL servers should coerce non-floating-point raw values to Float when
407- possible otherwise they must raise a field error. Examples of this may include
408- returning ` 1.0 ` for the integer number ` 1 ` , or ` 2.0 ` for the string ` "2" ` .
409+ Fields returning the type ` Float ` expect to encounter double-precision
410+ floating-point internal values.
411+
412+ GraphQL servers may coerce non-floating-point internal values to ` Float ` when
413+ reasonable without losing information, otherwise they must raise a field error.
414+ Examples of this may include returning ` 1.0 ` for the integer number ` 1 ` , or
415+ ` 123.0 ` for the string ` "123" ` .
409416
410417** Input Coercion**
411418
@@ -426,10 +433,12 @@ and that representation must be used here.
426433
427434** Result Coercion**
428435
429- GraphQL servers should coerce non-string raw values to String when possible
430- otherwise they must raise a field error. Examples of this may include returning
431- the string ` "true" ` for a boolean true value, or the string ` "1" ` for the
432- integer ` 1 ` .
436+ Fields returning the type ` String ` expect to encounter UTF-8 string internal values.
437+
438+ GraphQL servers may coerce non-string raw values to ` String ` when reasonable
439+ without losing information, otherwise they must raise a field error. Examples of
440+ this may include returning the string ` "true" ` for a boolean true value, or the
441+ string ` "1" ` for the integer ` 1 ` .
433442
434443** Input Coercion**
435444
@@ -446,9 +455,11 @@ representation of the integers `1` and `0`.
446455
447456** Result Coercion**
448457
449- GraphQL servers should coerce non-boolean raw values to Boolean when possible
450- otherwise they must raise a field error. Examples of this may include returning
451- ` true ` for any non-zero number.
458+ Fields returning the type ` Boolean ` expect to encounter boolean internal values.
459+
460+ GraphQL servers may coerce non-boolean raw values to ` Boolean ` when reasonable
461+ without losing information, otherwise they must raise a field error. Examples of
462+ this may include returning ` true ` for non-zero numbers.
452463
453464** Input Coercion**
454465
0 commit comments