Skip to content

Commit 29bcc26

Browse files
authored
Editorial: Refine design principles (#839)
Updates design principles to use more generalized language, and slightly reorders to put product-centric first.
1 parent 567e05c commit 29bcc26

File tree

1 file changed

+16
-16
lines changed

1 file changed

+16
-16
lines changed

spec/Section 1 -- Overview.md

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -36,35 +36,35 @@ platform for tool-building.
3636

3737
GraphQL has a number of design principles:
3838

39-
* **Hierarchical**: Most product development today involves the creation and
40-
manipulation of view hierarchies. To achieve congruence with the structure
41-
of these applications, a GraphQL query itself is structured hierarchically.
42-
The query is shaped just like the data it returns. It is a natural
43-
way for clients to describe data requirements.
44-
4539
* **Product-centric**: GraphQL is unapologetically driven by the requirements
4640
of views and the front-end engineers that write them. GraphQL starts with
4741
their way of thinking and requirements and builds the language and runtime
4842
necessary to enable that.
4943

44+
* **Hierarchical**: Most product development today involves the creation and
45+
manipulation of view hierarchies. To achieve congruence with the structure
46+
of these applications, a GraphQL request itself is structured hierarchically.
47+
The request is shaped just like the data in its response. It is a natural way
48+
for clients to describe data requirements.
49+
5050
* **Strong-typing**: Every GraphQL service defines an application-specific
51-
type system. Queries are executed within the context of that type system.
52-
Given a query, tools can ensure that the query is both syntactically
53-
correct and valid within the GraphQL type system before execution, i.e. at
51+
type system. Requests are executed within the context of that type system.
52+
Given a GraphQL operation, tools can ensure that it is both syntactically
53+
correct and valid within that type system before execution, i.e. at
5454
development time, and the service can make certain guarantees about the shape
5555
and nature of the response.
5656

57-
* **Client-specified queries**: Through its type system, a GraphQL service
57+
* **Client-specified response**: Through its type system, a GraphQL service
5858
publishes the capabilities that its clients are allowed to consume. It is
5959
the client that is responsible for specifying exactly how it will consume
60-
those published capabilities. These queries are specified at field-level
61-
granularity. In the majority of client-server applications written
62-
without GraphQL, the service determines the data returned in its various
63-
scripted endpoints. A GraphQL query, on the other hand, returns exactly what
64-
a client asks for and no more.
60+
those published capabilities. These requests are specified at field-level
61+
granularity. In the majority of client-server applications written without
62+
GraphQL, the service determines the shape of data returned from its various
63+
endpoints. A GraphQL response, on the other hand, contains exactly what a
64+
client asks for and no more.
6565

6666
* **Introspective**: GraphQL is introspective. A GraphQL service's type system
67-
must be queryable by the GraphQL language itself, as will be described in this
67+
can be queryable by the GraphQL language itself, as will be described in this
6868
specification. GraphQL introspection serves as a powerful platform for
6969
building common tools and client software libraries.
7070

0 commit comments

Comments
 (0)