Skip to content

Commit 858d409

Browse files
committed
Add more clarifying text
1 parent 69cab2a commit 858d409

File tree

1 file changed

+22
-13
lines changed

1 file changed

+22
-13
lines changed

spec/Section 3 -- Type System.md

Lines changed: 22 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -328,11 +328,13 @@ scalar string returns either null or a singular string.
328328
A GraphQL schema may describe that a field represents a list of another type;
329329
the `List` type is provided for this reason, and wraps another type.
330330

331-
Similarly, the `Non-Null` type wraps another type, and denotes that the
332-
resulting value will never be {null} (and that a _field error_ cannot result in
333-
a {null} value).
331+
Similarly, both the `Non-Null` type and the `Semantic-Non-Null` type wrap
332+
another type, the former denotes that the resulting value will never be {null}
333+
(and that a _field error_ cannot result in a {null} value), whereas the latter
334+
denotes that the resulting value will never be {null} _unless_ there is a
335+
matching _field error_.
334336

335-
These two types are referred to as "wrapping types"; non-wrapping types are
337+
These three types are referred to as "wrapping types"; non-wrapping types are
336338
referred to as "named types". A wrapping type has an underlying named type,
337339
found by continually unwrapping the type until a named type is found.
338340

@@ -345,10 +347,13 @@ like Scalar and Enum types, can be used as both input types and output types;
345347
other kinds of types can only be used in one or the other. Input Object types
346348
can only be used as input types. Object, Interface, and Union types can only be
347349
used as output types. Lists and Non-Null types may be used as input types or
348-
output types depending on how the wrapped type may be used.
350+
output types depending on how the wrapped type may be used. Semantic-Non-Null
351+
types may only be used as output types.
349352

350353
IsInputType(type) :
351354

355+
- If {type} is a Semantic-Non-Null type:
356+
- Return {false}
352357
- If {type} is a List type or Non-Null type:
353358
- Let {unwrappedType} be the unwrapped type of {type}.
354359
- Return IsInputType({unwrappedType})
@@ -358,7 +363,7 @@ IsInputType(type) :
358363

359364
IsOutputType(type) :
360365

361-
- If {type} is a List type or Non-Null type:
366+
- If {type} is a List type, Non-Null type, or Semantic-Non-Null type:
362367
- Let {unwrappedType} be the unwrapped type of {type}.
363368
- Return IsOutputType({unwrappedType})
364369
- If {type} is a Scalar, Object, Interface, Union, or Enum type:
@@ -1902,20 +1907,24 @@ Following are examples of result coercion with various types and values:
19021907

19031908
## Semantic-Non-Null
19041909

1905-
The GraphQL Semantic-Non-Null type is an alternative to the GraphQL Non-Null
1906-
type to disallow null unless accompanied by a field error. This type wraps an
1907-
underlying type, and this type acts identically to that wrapped type, with the
1908-
exception that {null} will result in a field error being raised. A leading
1909-
exclamation mark is used to denote a field that uses a Semantic-Non-Null type
1910-
like this: `name: !String`.
1910+
The Semantic-Non-Null type is an alternative to the Non-Null type, used to
1911+
indicate that a field is _semantically_ non-nullable (the data will never
1912+
represent a {null}) whilst still allowing the position to act as an error
1913+
boundary, preventing error propagation. Essentially it acts to disallow {null}
1914+
_unless_ accompanied by a _field error_.
1915+
1916+
The Semantic-Non-Null type wraps an underlying type, and this type acts
1917+
identically to that wrapped type, with the exception that {null} will result in
1918+
a field error being raised. A leading exclamation mark is used to denote a
1919+
field that uses a Semantic-Non-Null type like this: `name: !String`.
19111920

19121921
Semantic-Non-Null types are only valid for use as an _output type_; they must
19131922
not be used as an _input type_.
19141923

19151924
**Nullable vs. Optional**
19161925

19171926
Fields that return Semantic-Non-Null types will never return the value {null} if
1918-
queried _unless_ an error has been logged for that field.
1927+
queried _unless_ a _field error_ is associated with that field.
19191928

19201929
**Result Coercion**
19211930

0 commit comments

Comments
 (0)