Add 'implementation' to the Glossary

[martinbonnin]

No description provided.

[benjie]

Following on from this thread in the GraphQL discord #wg channel...

🤔 Does an implementation have to be used to build a service? graphql-js implements the parsing section of the GraphQL spec, and that can be used for building developer tooling, without ever being used to build a GraphQL service. I don't think this feels quite right yet...

[benjie]

Maybe this captures the intent more precisely?

[martinbonnin]

I'm a slow writer but I wanted to say this:

I simplified and left "optional features" out on purpose for now cause I'm still not 100% clear about it.

GraphQL implementations that support the type system definition language
should provide the @specifiedBy directive if representing custom scalar definitions.

I'd love the spec to be more detailed about what an implementation is and what "support the type system definition language" means in this context. Is this for schema-first libraries? If yes, what should code-first libraries do? Or is this something else? What does "provide" mean? Expose them in introspection? Allow validation of the incoming SDL? Or maybe both?

[benjie]

I'd love the spec to be more detailed about what an implementation is and what "support the type system definition language" means in this context.

I'd say an implementation is anything that implements the GraphQL spec: a service, some tooling, etc

Is this for schema-first libraries?

Yes, but for all other SDL-writing use cases; client-side schema extensions; tools that take introspection data and represent it as SDL (e.g. so it can be used by tooling such as graphql-schema-generator); services that allow extensions via SDL even if the original service is not SDL-first; etc.

If yes, what should code-first libraries do?

In GraphQL.js you'd do new GraphQLScalarType({name: "...", specifiedByURL: "...", ...}) (note it does not use a directive because it's not SDL).

What does "provide" mean?

It means make it so that the directive can be used; e.g. for this document to be valid:

scalar MyScalar @specifiedBy(url: "...")

the implementation must provide the @specifiedBy directive. Otherwise you'd get an unknown directive error.

[calvincestari]

If we go back to the beginning - why is a distinction necessary? How does it change interpretation or conformance rules of the spec?

[martinbonnin]

If we go back to the beginning - why is a distinction necessary? How does it change interpretation or conformance rules of the spec?

Wondering about this too. If we're saying "service" == "implementation" everything would be much simpler.

The spec has language specific to implementations though:

GraphQL implementations that support the type system definition language should provide
the @specifiedBy directive if representing custom scalar definitions.

That doesn't make any sense to someone that just wants to have a conforming server.

IMO the spec adresses 2 use different cases:

Service

function executeRequest(request: GraphQLRequest): GraphQLResponse { ... }

Implementation

function buildSchema(sdl: String, resolvers: Resolvers) GraphQLSchema { ... }
// potentially more (parseAst, validateOperation, etc...)

A GraphQLSchema should have an execute() function so is technically a service.
I'd say an "implementation" may be thought as a super set of a "service"...

The important thing is that we don't want service to have to conform to all the "implementation" language. At least this is my current understanding of it but it's way different from what it was yesterday so it might still change 😅 ...

[calvincestari]

The spec has language specific to implementations though

Is this intentional though, or has it simply been used as the spec evolved without a common language?

[benjie]

An implementation is something that implements the GraphQL spec. An implementation does not have to be able to execute requests - for example it might be limited to parsing the document syntax and constructing a schema from it, which it can then use for codegen, or docgen, or linting, or for validating your persisted documents, or some other purpose.

A service does have to be able to execute requests, as written in the spec:

A GraphQL service generates a response from a request via execution.
-- https://spec.graphql.org/draft/#sec-Execution

So "service" describes an implementation that can execute GraphQL requests.

"Implementation" is a broader term, all services are implementations (or contain/wrap implementations and thus, from the point of view of someone issuing a GraphQL request, have the same perceived result and thus are implementations), but not all implementations are (or even can be) services.

I'd say an "implementation" may be thought as a super set of a "service"...

I'm not sure this is the most intuitive or unambiguous way of putting it. The set of "all services" is indeed a subset of the broader set of "all implementations" - it is the subset that requires the ability to execute requests. That said, when looking at individuals, an implementation may support fewer (or different) GraphQL features than a service, so it's not true to say that an implementation must support everything that a service must support (an alternative interpretation of the quoted phrase).

The important thing is that we don't want service to have to conform to all the "implementation" language.

What language in the GraphQL spec do we want a service to not have to conform to? Please pay close attention to RFC2119 when coming up with examples, quite a lot of the GraphQL specification is written in a way where if the use case is not relevant to your implementation, you don't need to implement it - for example, if you're not writing a GraphQL service then you don't need to be able to execute a GraphQL request.

[benjie]

I think the definition in the spec is quite clear, let's use that?

Suggested change

	**Definition**: anything capable of executing a GraphQL request and returning
	a GraphQL response conforming to the specification.
	**Definition**: A GraphQL service generates a [response](https://spec.graphql.org/draft/#sec-Response) from a [request](https://spec.graphql.org/draft/#request) via [execution](https://spec.graphql.org/draft/#sec-Execution).