Skip to content

Commit 6264013

Browse files
committed
Edit: Result coercion no data loss
This edits the "result coercion" section of the scalar types to make it clear that data loss is to be avoided and suggests that internal values of the correct type are the ideal scenario. Fixes #312
1 parent 4cd6824 commit 6264013

File tree

1 file changed

+35
-24
lines changed

1 file changed

+35
-24
lines changed

spec/Section 3 -- Type System.md

Lines changed: 35 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -327,17 +327,14 @@ the built-in scalar types should be omitted for brevity.
327327
**Result Coercion**
328328

329329
A 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

342339
Since this coercion behavior is not observable to clients of the GraphQL server,
343340
the 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

Comments
 (0)