Skip to content

Commit

Permalink
Add conformance section (#363)
Browse files Browse the repository at this point in the history
* In anticipation of potentially moving to some license that references "normative", "non-normative", and "conformance" - I think it's helpful to define these concepts relative to the rest of this spec, and clarify some of the details of what technically qualifies as GraphQL, and how to interpret some of the document (like notes and examples) for any future cautious reader.

I'm referencing [RFC 2119](https://tools.ietf.org/html/rfc2119) since we've already done a good job of using these terms throughout the spec. Most of this conformance definition is highly inspired by W3C and ECMA documents that contain similar language. No need to reinvent the wheel here.

A preview of this content rendered: https://out-xlhkhmymsm.now.sh/

* Add conformance section

In anticipation of potentially moving to some license that references "normative", "non-normative", and "conformance" - I think it's helpful to define these concepts relative to the rest of this spec, and clarify some of the details of what technically qualifies as GraphQL, and how to interpret some of the document (like notes and examples) for any future cautious reader.

I'm referencing [RFC 2119](https://tools.ietf.org/html/rfc2119) since we've already done a good job of using these terms throughout the spec. Most of this conformance definition is highly inspired by W3C and ECMA documents that contain similar language. No need to reinvent the wheel here.

A preview of this content rendered: https://out-xlhkhmymsm.now.sh/

* remove confusing phrase

* Minor phrasing
  • Loading branch information
leebyron authored Sep 25, 2017
1 parent e80bbfa commit e29a233
Showing 1 changed file with 61 additions and 0 deletions.
61 changes: 61 additions & 0 deletions spec/GraphQL.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,67 @@ ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


**Conformance**

A conforming implementation of GraphQL must fulfill all normative requirements.
Conformance requirements are described in this document via both
descriptive assertions and key words with clearly defined meanings.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative portions of
this document are to be interpreted as described in [IETF RFC 2119](https://tools.ietf.org/html/rfc2119).
These key words may appear in lowercase and still retain their meaning unless
explicitly declared as non-normative.

A conforming implementation of GraphQL may provide additional functionality,
but must not where explicitly disallowed or would otherwise result
in non-conformance.


**Conforming Algorithms**

Algorithm steps phrased in imperative grammar (e.g. "Return the result of
calling resolver") are to be interpreted with the same level of requirement as
the algorithm it is contained within. Any algorithm referenced within an
algorithm step (e.g. "Let completedResult be the result of calling
CompleteValue()") is to be interpreted as having at least the same level of
requirement as the algorithm containing that step.

Conformance requirements expressed as algorithms can be fulfilled by an
implementation of this specification in any way as long as the perceived result
is equivalent. Algorithms described in this document are written to be easy to
understand. Implementers are encouraged to include equivalent but
optimized implementations.


**Non-Normative Portions**

All contents of this document are normative except portions explicitly
declared as non-normative.

Examples in this document are non-normative, and are presented to aid
understanding of introduced concepts and the behavior of normative portions of
the specification. Examples are either introduced explicitly in prose
(e.g. "for example") or are set apart in example or counter-example blocks,
like this:

```example
This is an example of a non-normative example.
```

```counter-example
This is an example of a non-normative counter-example.
```

Notes in this document are non-normative, and are presented to clarify intent,
draw attention to potential edge-cases and pit-falls, and answer common
questions that arise during implementation. Notes are either introduced
explicitly in prose (e.g. "Note: ") or are set apart in a note block, like this:

Note: This is an example of a non-normative note.


# [Overview](Section 1 -- Overview.md)

# [Language](Section 2 -- Language.md)
Expand Down

0 comments on commit e29a233

Please sign in to comment.