Hi @timward60 ... thanks a lot for your interest.

Let me try to give some context and my thinking behind the normalized stuff, because this has never been properly documented so far:

Originally the ENF was introduced mainly for the Nadel project https://github.com/atlassian-labs/nadel because it allows for a much more simpler and efficient way of rewriting/transforming requests. But over time it proved to be useful in other cases too: for example it is used inside the DataFetchingEnvironment to look ahead or used to calculate query complexity in certain cases.

The main "problem" with ENF is that it requires variables as input (hence it is called ExecutableNormalized and not just normalized).
This means it can't be reused/cached across requests with the same document/operation, but with different variables.

If you want to make it independent of variables you have to account for the different variations of skip/include which could lead to vastly different queries. In case of ENF it is very simple: you just have to evaluate skip/include and then either ignore the fields or include them.

This challenge around skip/include and the fact that ENFs proved good enough (at least so far) meant I never got around implement a Normalized version until recently.

This NormalizedDocument and related classed indeed aims to be a full working normalized document/operation/field that can be cached.

To note: I decided to solve the skip/include problem by providing NormalizedOperations for each possible combination of variables, which are used in skip/include. See https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/normalized/nf/NormalizedDocument.java#L28

Otherwise a NormalizedField is very similar to a ENF, expect the arguments can't be fully resolved, because they can reference variables.

I am happy with that solution in general and believe that this NFs can be the normalized structure I talked about a while ago.

The three "challenges" I can foresee around NFs are:

• I assume that the number of skip/include variables is very low, but this could be wrong in real life. The number of possible combination obviously explodes very quickly and hence this solution will not work in these cases.

• Sensitive to schema changes: NFs are the most aggressive normalized structure I could come up with, which means they are as simple as possible, but the downside is that it depends heavily on the shape of the Schema when it was normalized. For example if you introduce a new Object implementing an existing Interface (e.g. Bird was added that implements the Pet interface) every normalized document which was created from a document referencing the interface (Pet in this example) is outdated and would need to be invalidated.

• custom operation directives and semantics associated with it: this is not a really a NF problem, but also an ENF one. Custom operation directives are rare and tricky. The semantics of them are not clear when you normalize:.

For example what does this mean:

{
  foo @cache(maxAge: 100)
  foo @cache(maxAge: 200)
}

There is no way of knowing how to merge these two fields together because the semantics are not clear.
Even worse are custom operation directives on fragment spreads like this:

{ 
  ... @foo {
    ... @bar {
       hello
    }
  }

What does this mean?

I see two approaches here: retain simply the custom operation directives inside the NormalizedOperation as additional metadata as much as possible
or provide hooks/callbacks during the creation of NFs to implement custom semantics.

Coming back to your question: I hope this answered your first question at least partially. Happy to share more details.

Is this something we should look at it if we want to contribute changes to support caching of the executable document?

Yes please. Maybe you could share more details what exactly you use ENFs for and what you look into it.

Do you have a rough timeline of when you expect to move this to mainstream support?

As soon as we have some more real life validation that it is useful we can mark them public instead of experimental. Experimental is simply a way (in this case at least) to iterate faster as we can brake the contract as needed.