Glossary: add 'implementation'

[martinbonnin]

Adding implementation to the Glossary. Feedbacks welcome!

[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.

[martinbonnin]

all services are implementations

I can lean into that but I'd say it's not the intuitive mental model. My personal anecdotal mental models is "the GitHub API is a service", "graphql-js is an implementation". The spec also mentions "service implementation" a couple of times which hints at different things.

an implementation may support fewer (or different) GraphQL features than a service

I never realized that. TBH, I always thought of an implementation as something that has the same feature set as graphql-js. As a user, I'd be quite suprised to come into a partial GraphQL implementation.

From your last comment, I understand a simple GraphQL lexer is technically a compliant GraphQL implementation? I would expect an implementation to support at least parsing + validation + execution to claim the "implementation" status.

What language in the GraphQL spec do we want a service to not have to conform to?

The bone I'm currently chewing on is here:

GraphQL implementations should provide the @skip and @include directives.

GraphQL implementations that support the type system definition language must provide the @deprecated
directive if representing deprecated portions of the schema.

[...]

When introspecting a GraphQL service all provided directives, including any built-in directive, 
must be included in the set of returned directives.

(sorry clicked enter too fast, the text below is an edit)

This blends a bit the service vs implementation line. Took me a lot of time to understand the implementation mentioned in the first 2 sentences is the same as the service in the last one. And technically speaking, nothing mandates having @deprecated in introspection results for a service that doesn't support the type system definition language?

[calvincestari]

TBH, I always thought of an implementation as something that has the same feature set as graphql-js.

As the reference implementation graphql-js is not representative of any implementation that can claim to be spec compliant. In graphql-js-world there is no should or may in the spec, everything is must.

As a user, I'd be quite suprised to come into a partial GraphQL implementation.

A partial implementation is only one that ignores the must (required) features no?

[martinbonnin]

As the reference implementation graphql-js is not representative of any implementation that can claim to be spec compliant.

This is what I'm questioning. I think from a wider community point of view, it's a reasonnable expectation that implementation == graphql-js like. graphql-java is very similar to graphql-js. I want to say Hot Chocolate too, etc... If I want to do GraphQL in language X, I expect a library that has the same features as the reference implementation, it's a relatively established pattern.

If now we're saying a GraphQL client or lexer is a GraphQL implementation, it might be the technical appropriate spec term but also a confusing one for the newcomer.