Algorithms - do we need this stuff?

[rivantsov]

This is 'operation name uniqueness check' algorithm. Which can be expressed with a simple human-readable sentence - which actually follows it in the spec:

Each named operation definition must be unique within a document when referred to by its name.

Now, do we really need this multi-step, barely readable multi-line nonsense? Would it be enough to simply have this 'humanly' statement?

Another point of view. We all know declarative vs imperative dilemma. Declarative is usually preferable, most of the time. What we do in the spec - we make IMPERATIVE to be our primary way in the spec (we list algorithm first). Then imperative code is followed by DECLARATIVE (this simple sentence). Why?!

Finally, it also feels like a personal insult. I am a server-side developer, and since these checks over schema are executed on the server, it appears its target audience is server developers, just like me. I feel I need to ask - why are you explaining this to me - how to check uniqueness of a string in a list? Your think I am that stupid? and the spec actually says - well, yeah...

Now seriously, what's the point of this and other 'algorithms'? they take space, cost a lot of effort to write and verify, while bringing ZERO value. The spec gets bloated. I doubt there is anybody who needs these, client or server dev.

Let's go DECLARATIVE, not imperative. Let's get rid of these.

[yaacovCR]

I think the algorithms bring value.

1. The spec PR process is purposefully tightly coupled with the reference implementation. This allows for a rapid and productive feedback cycle for proposed spec changes. Often, a spec change will require re-evaluating after initial implementation, which often raises issues not clear on first impression. Having algorithms within the spec further tightens this feedback cycle, by forcing a pseudo-code implementation which is helpful when planning the graphql-js pr.
2. I don’t think the algorithms are non readable for humans. They are quite readable and should be quite accurate. They are very helpful to implementors and reviewers who are usually human!
3. Some algorithms are so simple that they may seem unnecessary. But then they are pretty short! Because a dividing line between “simple” and “complex” is pretty subjective, it is safer and more practical to insist on uniformity, in my opinion.
4. The spec explicitly states that all equivalent algorithms are compliant, so the imperative portion is non-constraining. If you find them unhelpful, you can always skip them. Since they are helpful to others (even though they may be distracting to those who don’t need them) the most inclusive option is to include them (which does impinge on the readability for those who don’t want them). You can’t please everyone (at least not all of the time).

[michaelstaib]

Well, about clarifying power of implementation - only for some of us. Remember, I do NOT know js/ts enough, so for me graphql.js could as well be graphql.ancient-chinese, same clarifying power. And this is the case for many others coming from .net, java, go, ruby. So goes the clarifying power of graphql.js.

This is not true, I am also a .NET backend engineer but I can read other programming languages. When we initially started on Hot Chocolate we closely used graphql-js and the algorithms. Having these two sources helped immensely clarify things.

Our todays implementation while much more optimized still reflects in parts the spec algorithms. I personally find it paramount to have both a reference implementation and the algorithms.

However when we discuss new spec features in the working group we are making sure that at least one other non js implementation verifies a spec feature. The ChilliCream team often implements proposed features together with the graphql-js proposals. We closely look at the graphql-js PRs and even give feedback.

[michaelstaib]

Just to clarify one point above, when I wrote that the algorithm in the spec implementation has to match the reference

Its the other way around, the reference implementation needs to follow the spec algorithms.

[michaelstaib]

there no changes there! It does not mark sections as added at certain version

It does.

https://github.com/graphql/graphql-spec/blob/main/changelogs/October2021.md

have a look at the diff section.

[michaelstaib]

but I can read other programming languages

@roman do not get me wrong here. I do not mean my comment in a condescending way. I just think that we all are able to read other programming languages. In all honesty I liked the flow/js style more back in the days because it was purer js code. ts often adds more complexity.

But we all are able to inspect the algorithms in the implementation. True there are maybe constructs that are difficult to understand/js specific but most of the time this can be easily skipped. The essence that you have a debuggable GraphQL reference implementation that shows the spec algorithms in practice is something to cherish.

The first Hot Chocolate parsers was a 1:1 port of the reference implementation. After some time we rewrote it to make it faster and reduce allocations but in essence we were able to almost take the JS code and rewrite it to .NET code.

There also is one aspect about the spec algorithms that is important. The spec allows to implement or come up with better algorithms as long as the outcome is the same. But to understand what the outcome really is in my opinion you need to have the algorithms. With the algorithms integrated in the spec text its so easy to implement a GraphQL server. IMO I enjoy reading the GraphQL spec, its so much more approachable than most specification texts.

[rivantsov]

@michaelstaib
just a few comments on your comments (really appreciate it!)

(my comment) there no changes there! It does not mark sections as added at certain version. (Michael) It does. (link to changelog)

I originally commented on Yaacov's note that 'inclusion of algorithms ... really highlight(s) what has changed' - what changed, where? as if the sections in the spec are marked with 'This is change in 2021 version'. For the reader, the spec in a snapshot of standard at certain version, a complete doc, without any history or marked changes. And of course I know about changelog there. Simply there are no 'changes' in the spec for the reader, it is just a document. The changelog is byproduct of the WG process, and acknowledgement of contributions. Not part of the spec per se.

do not get me wrong here. I do not mean my comment in a condescending way.

No worries, we are all PROs, never take things personally.

I just think that we all are able to read other programming languages.

Well, to read the code of a real-world app, you need more than just a language. We code not just in the language, but in the ecosystem. Lots of other things. Language is probably 20% of what you need to learn. Especially true for javascript with its zillion npm packages. I admit, I exaggerated when I said I cannot read graphql.js - I can, to some extent. By my point is - the spec cannot assume this for everybody. And you should not have to learn a new language to learn GraphQL, if you are coming from a different platform. GraphQL is language-neutral. The only 'language' we can freely use/imply is probably JSON - here I would agree everybody knows what it is.

So we cannot rely on graphql.js for extra explanation. Like if you did not understand feature X - go check the ref implementation. You are backend guy but can read js - lucky you (no sarcasm); but do not imply it for everybody.

IMO I enjoy reading the GraphQL spec, its so much more approachable than most specification texts.

No doubt, esthetic aspect in tech is important - good code is esthetically pleasing. Although enjoyment is more personal thing. Reading the spec is more like a really hard work for me - line by line, fearing of missing something important. But when it comes to algorithms - it feels like a prank, I read this trivial stuff, trying to find a meaning, and feels like there's a hidden camera somewhere recording my stupefied face. And somebody is laughing out there.

Thank you again, I will make another post later, more general thoughts about algorithms

[rivantsov]

Hi all,

I think this thread got side-tracked into discussion about reference implementation (RefImpl), based on an early claim that somehow algorithms in spec are in some direct relation to RefImpl. We started discussing RefImpl's readability, it's role in bringing new features etc. While it is an interesting discussion on its own, I would like to come back to the original subject of algorithms in the spec.
I would like to reiterate my principal point:

The spec is a document that is self-sufficient and it must completely describe the GraphQL protocol , clearly explaining all the details, enough for successful implementation of servers or clients in any language or platform. That's how the specs work, in general. The question here and now is the use of didactic tools and approaches in the spec for the best readers' experience.

Let's look again at the original example

It has 3 parts:

1. Title, the name of the 'feature'
2. Formal Specification - as an algorithm
3. Explanatory text - plain text description of the feature.

Since the algorithm precedes the Explanatory Text, and is titled 'Formal Specification', then it is the 'official definition/description of the feature, source of truth, and something that one HAS TO READ to fully understand the feature. The third section 'Explanatory Text' is just something extra, optional explanation material that one can skip if he 'got it' from the 'Formal Specification' - which is a multi-step algorithm.

It is thi front role of the 'algorithms' that I am not happy with. What if it instead was like this:

1. Title, the name of the 'feature'
2. Plain text description of the feature, preferably short and concise. This is a formal spec of the feature and the real source of truth.
3. Optional, illustrative, imperative algorithm, but only if it is at least something not trivial and potentially helpful. The reader can skip it if all is clear.

If it was like this, honestly, I would be OK, and definitely would not start this crusade/discussion. It is the use of the elements, the order, and the role of algorithms as a formal source of truth (vs optional illustrative element) - that's what I am against and suggest to change. And of course use algorithms sparingly, at least skipping the trivial ones like the one shown above.

I suggest also to leave the Reference implementation alone, and focus on clarity and explanatory power of the spec text itself, without any implied links to the WG process, Ref implementation, change logs, or anything else.

Thank you
Roman

[yaacovCR]

the case I am talking about is a variable of Nullable type with default null

A nullable type with default of null is assigned a value of Null. The spec section you quote where it resolvers must be allowed to distinguish between cases where the argument is omitted and where it is explicitly set to null by the user is referring to a case does not include a default of null. This can be checked by following the algorithm.

3/g/i says a value is added to the map if hasValue is false and there is a default, including null. If there is no default, the value is not added to the map.
3/h describes non-nullable types, not relevant to this scenario.
3/i describes hasValue of true, such that if the value is null, it is added to the map.

So without a default, with a nullable type, there are two different outcomes if the user specifies null, 3/i says that it is added to the map, whereas if no value is provided, none of the three "action" portions of the algorithm pertains, and no item is added to the map.

Resolver code can distinguish between whether null exists in the map for the variable, or if there is no entry for the variable.

I think the ambiguity to me seems to be that you believe that the resolver should still be able to tell whether a default of null was used or not, and I don't think that's the case.

[benjie]

Indeed:

• it is irrelevant if a null originates from a defaultValue or from the user, either way it is null
• GraphQL distinguishes between a value not being present (neither provided by the user, nor by a default value) versus a value being null (either explicitly from the user, or implicitly from a default value)

[rivantsov]

ok, now I'm getting somewhere and starting to understand something. Let me spend some more time to digest these details. Thanks guys!

[rivantsov]

OK, I retract, these algorithms are correct, at least for missing values tracking. My apologies for starting this messy thread. Thank you.

PS the algorithms are correct, but are not easy to go through for particular scenarios. A few explanatory sentences (like @benjie 's comment above, and a note that coerced args/vars map count might be less than 'definition set') - would have helped a lot.

[benjie]

This is one of the reasons algorithms are core to the spec - they help to convey this kind of subtle information with minimal ambiguity. Care must be taken when interpreting the algorithms though, which is why the spec also includes explanatory text; if the explanatory text here is insufficient as you suggest then a good course of action would be to raise a PR to improve the explanation.

[leebyron]

I always welcome a spicy take, but I must say I strongly disagree with this one. I find the algorithms as one of the primary ways the spec brings value.

Do we really need this multi-step, barely readable multi-line nonsense? Would it be enough to simply have this 'humanly' statement?

English phrases are notoriously ambiguous. There may be cases where we have simple algorithms which could be stated in English. It's quite useful to have both actually. English should be easier to read and understand intent where algorithms should disambiguate and be very clear as to the explicit order of operations.

We also have algorithms which are considerably more complicated. It would be a huge problem to omit complex algorithms in favor of ambiguous English prose. Rather than having some rule where only complicated algorithms get written in full form, it's useful to describe all algorithms uniformly.

Another point of view. We all know declarative vs imperative dilemma. Declarative is usually preferable, most of the time. What we do in the spec - we make IMPERATIVE to be our primary way in the spec (we list algorithm first). Then imperative code is followed by DECLARATIVE (this simple sentence). Why?!

This is good feedback, and a case where we are not always consistent across the spec document. I like the principle that you should be able to read the spec text top to bottom linearly without encountering knowledge large gaps along the way. There are cases where we aid this by explaining a concept at a high level relative to some section if it's described in detail further below.

Algorithms appearing before prose which explains their purpose and high level behavior is in fact backwards according to that principle.

It also feels like a personal insult. I am a server-side developer, and since these checks over schema are executed on the server, it appears its target audience is server developers, just like me. I feel I need to ask - why are you explaining this to me - how to check uniqueness of a string in a list? Your think I am that stupid? and the spec actually says - well, yeah...

I think it's worth pointing out here that the purpose of the algorithms is not to tell server-side developers how to write a program. I agree with you that developers are perfectly capable of writing their own code, and in fact we encourage that in the spec.

Algos should disambiguate and explain to all developers but most importantly consumers of a GraphQL API what behavior they should expect. If a behavior is not observable to a client, then it may not be required to be described in a spec.

Now seriously, what's the point of this and other 'algorithms'? they take space, cost a lot of effort to write and verify, while bringing ZERO value.

Over time I have seen a very large number of examples where explicit algorithms have helped disambiguate and help resolve inconsistencies in the ecosystem, help guide spec discussions, discussions around building tools, and countless other cases where a lack of clarity would have resulted in real cost but clearly defined algos avoided that outcome (or we faced real cost, where writing an algorithm more clearly helped resolve it).

So I have to firmly disagree with the statement that they bring zero value. In fact I've experienced their great value first hand.

[rivantsov]

@leebyron
Thank you for your detailed response. I would be honest, I am not convinced, but that's ok. We exchanged opinions that's the main point, and I think we can now put the issue to rest. I will leave the discussion open for a few days so others can find and read your response, and then close it (wonder if its possible).
Thank you again