Video recording: https://www.youtube.com/watch?v=fbcTVULqm-8
Review previous meeting's action items and check progress on those
- Lee: In the future, let’s make all of these action items into GitHub issues
- Lee: [Action - Lee] Go back and make sure previous meeting’s action items are made into GitHub issues
- [Lee] Write up a draft plan for freeze and release * Still open - tentatively January
- [Lee] Add a non-normative note to explain why variables cannot be self-referential *
- [Rob Z] Move Lexer Lookaheads to stage 3 * Good to go
- [Victor] Re-frame empty composite types proposal in terms of the specific problem rather than expressing all the problems that it could potentially solve. *
- [Lee] Grant website access to Tanay and Orta * Probably done
- [Lee] Give detailed feedback on website code page * Not done
- [Mike, Ivan] Alpha version of interfaces implementing interfaces * ✅
- [James] Concrete examples of interfaces implementing interfaces implementation complexity * ✅
- [Mike] Ensure that test cases are present for interfaces implementing interfaces * ✅
- [Everyone interested in input unions] Contribute to the Input Union RFC document before the next meeting to make requirements/tradeoffs clearer * ✅
Dec example of new format Google Calendar
- Lee: Yesterday I added a handful of new things, upcoming meetings for 2020, changed the format of our agenda documents (link above)
- I went ahead and updated the December agenda to the new layout as well,
- it uses the guidelines we had at the top of our agenda and moves them to the attendees section,
- I added things we talk about every meeting to the notes as well (replace asterisks with emojis, make sure to include country codes, ask people for relevant links, make sure to add owners in agenda items).
- I’m definitely open to feedback and further improvements.
- Also created a shared Google Calendar for the meetings (Google Calendar and iCal), hopefully this is a good way for people to automatically receive meeting times
- I just want to make sure there’s an update on those things I mentioned in earlier meetings. Any questions?
- Ivan: I wanted to ask a small question. It said consider opening a new issue (optional), why is it optional? I think we should always open issues for agenda items.
- Lee: Good feedback, I can change that language for sure
- Ivan: Another thing, we discussed earlier, we should try to add items a few days before and prevent adding agenda items in the last minute
- Lee: Always a best practice to add things to the agenda a few days ahead of time
- Benedikt: I think it is relevant to list projects - not just companies - that people work for
- Lee: Do you mean mention both?
- Benedikt: Yes, both
- Lee: A lot of people work on multiple projects
- Suggest adding the project that you most identify with, e.g. Ivan has graphql-js and Lee has GraphQL Foundation.
- Consider allowing people to have an explicit priority on a certain project
- Lee: Any other thoughts on this? I’m happy to take offline conversations as well.
Facebook CLA & copyright in repos (see issue) (5m, Erik)
- Erik: Yeah hi, sorry to bring up this boring nontechnical issue, we wanted to contribute to libgraphqlparser, Lee upgraded this, removed references to CLA, I opened an issue about this in the working group repository (graphql#291), I went through all repositories of the foundation and there still are projects pointing to Facebook, I wanted to know whether there’s a way to get the CLA back, maybe as a text file. I wanted to bring this up to discuss
- Lee: We’ve been talking about it. Don’t know if the Linux Foundation has a tool to do this.
- Brian: Yes, the Linux foundation has a tool (Easy CLA), it does exactly this. One of the advantages is having multiple workflows for individual and corporate contributors to add people to a whitelist indicating that they’re covered under the company
- Erik: I think that’s what the Facebook tool did as well -> multiple workflows
- Brian: And we can also set some calls up here to your legal colleagues, if it helps
- Erik: We already checked the CLA text, the existing text from the original CLA was fine but the main problem was that it referenced Facebook.
- Brian: Yeah absolutely! This is definitely a known process, we’ve got experience with this
- Lee: I’m willing to help on this. Do we need a legal structure around textual contributions to an open-source technical body that hosts technical bodies.
- My understanding is that the legal stature is different in both of these.
- We should ensure our existing agreement makes sure that the IBM lawyers are happy. Reach out if you have lawyers who may be affected by this.
- Brian: We can definitely do that, we’re in the business of de-freaking lawyers, so those are common questions
- Erik: This is great, I have a small followup issue, Lee you actually filed an issue for libgraphqlparser, the namespace also mentions facebook and you brought up if this should change. This change could be breaking for all clients using this code. Any opinions? This might be too specific for the project and could be handled by releasing a new major version
- Lee: Yeah, that’s why I opened the issue there, to allow for discussion. I took a look at the repo and looked for references to Facebook. I noticed Facebook in the namespace but didn’t action on it because I didn’t want to affect anyone.
- Lee: [ACTION - Erik] please take the lead on this - what should the new namespace be, should we change it, etc.
- Erik: I agree, if anybody has an opinion, feel free to post comments to that issue, that should be it from my side, I’d like to have a followup with Brian
- Lee: **[ACTION - Lee] **comb through other repos in the GitHub org and do the same thing with libgraphqlparser and remove references to Facebook. Probably something I should have done earlier but better late than never!
- [No further questions/concerns on legal/CLA stuff]
- Mike: So I just want to touch briefly on interfaces touching interfaces which are now called intermediate interfaces, it’s been merged into graphql-js, I talked to James since he had some initial concerns, I also got a blog post ready and saw that
- Blog post is ready. Andy published a similar one.
- Didn't want to put pressure on Ivan to get v15 out.
- Just wanted to give everybody a chance to express concerns, so yeah that’s basically it.
- Lee: This blog post mentions version 15 of Graphql.js. Ivan, what’s the release plan for that?
- Ivan: Yes so I released alpha0 and I want to release alpha1, the idea is to reach feature freeze, I want to continue to start the actual TypeScript conversion where Mike wanted to help, we want to achieve a feature freeze and the TypeScript conversion to release 15.0.0
- Michael: Is the plan for TS conversion a part of version 15 or after?
- Ivan: It’s part of 15, we promised after 14.0.0 to have stable releases, so I thought it was wasteful to have a TypeScript-specific release, I released alpha0 for deprecations and breaking changes so people could try it out, some people are probably using your PR which was opened earlier, so if somebody wants to try out intermediate interfaces right now, get the latest alpha-tagged version of the package. I still need to do some cleanup work and will gladly accept help, I acknowledge that this is necessary for GraphQL changes in 2020
- Michael: Cool! I don’t particularly care when I publish the blog post. I just want to make sure I don’t publish it too early. It seems like it is okay to do it now so I guess I’ll just go for it?
- Ivan: Yeah!
- Lee: The reason I was asking was to make sure that people can actually check out graphql to test the new features.
- Michael: That sounds good, I’ll release the post alongside 15
- Lee: Ivan does it make sense to release 15 earlier and have 16 with the TypeScript changes, do you think there’s a way to release 15 earlier anyhow?
- Ivan: Actually, one of the things we need to consider is that we need to do breaking changes. There are potential conflicts with different versions of Node (involving dependencies). You are probably right, we can release version 15 and ask one last time everyone to try it, all different teams and get feedback. I added ten different breaking changes (mostly corner cases) but I think you are right. If we release in January, the TS conversion will be a good target.
- Lee: I agree, glad we managed to talk about this, I definitely agree to the release candidate to make sure the folks from the relay and apollo team can check it out and verify nothing breaks, I think pushing out everything for TypeScript in January to set the path for GraphQL 2020 makes sense as well
- Michael: Hopefully this puts the brakes on some classical inheritance patterns
- Lee: I’m glad you managed to resolve all concerns with the Apollo team as well
- [Action - Lee]: Final review of the spec text to move to RFC3
Custom Scalar Specification RFC (10m, Evan)
- Evan: Yeah hi. So Andy and I have been working on an RFC for a couple months to basically to allow users to attach a URI to custom scalar definitions to be used to hold a definition what the scalar conforms too (currently people are trying to cram it entirely into the description field), but it also will serve as a key for tooling like graphiql to be used as some kind of identifier, graphiql could for example check for specific URIs and treat types the same based on those. I don’t expect too much pushback on the general approach, I’m open to feedback in general and we can see about the grammar changes since we haven’t got a clear winner on how to put the URI into the schema,
- I'm less confident in changes around the grammar changes - how do we put the URL into the SDL schema definition? How do we define what the URL is in the schema? Do we add the URL schema definition from RFC3986, or just reference it? Is it just a string?
- Lee: This is exciting. If anyone has feedback... I will shut up and let other people talk about it.
- Michael: Have you already decided how the introspection changes for this?
- Evan: Yeah, the changes to introspection will not be complicated because it is just adding an additional field.
- Michael: So basically it brings this field to any type? Because the introspection doesn’t really make a distinction between scalars right?
- Evan: It just adds a specification URI field to the type type in introspection
- Benedikt: It is like extending the description -> addition the specification URI
- Michael: This is a specific URI field to be used just for the link to be used for machine interpretation for example, so because you have description at the moment which isn’t easily parseable, or what was the idea?
- Andi: To give some more context, I started the discussion a while back around DateTime and having a general way to define scalar implementations. This is an important change because it provides a more detailed description and can also be identified by external tools so that they know a particular type implements a specific specification. This is a good change. You can build tooling around it. And I am pretty happy with how it turned out to be honest because it overall solves the problem of extending scalars. This GraphQL WG could define a new spec for URLs, an official URL pattern, but you don’t need to implement it. If you have a legacy implementation and you can simply just add a different reference.
- Ivan: One thing, it’s like a pretty basic feature to attach a URL to the type, as Michael said you distinguish between different types, it’s not difficult to do that, for example in the connection spec, a couple of tools detect types pretty difficult, I’d prefer to get the type and match the URL instead of using other metadata which complicates things. If we do it as a directive, it will be applicable to any type
- Evan: That’s a really interesting thing, we should think about this
- Andi: There’s nothing in the SDL that says what a scalar is, right?
- Michael: You could also have a description on the scalar in introspection since it doesn’t matter, you’d be able to add some kind of specification document to any type. We also get this feature on other types as well and I think everybody was in agreement last time that this is not that bad
- Evan: Yeah, every field on the Type type is already limited to a subset of types so there’s the Field field for object and input objects but if we wanted to make types more generalized, it seems weird to start with the spec field
- Michael: The type always has field, even for scalar it has this property
- Lee: We could have made this a union, Nick Schrock talked me out of it since it would be too hard to encounter as the first thing you see, so in this case I kind of agree that it’s the right thing to start small and so we can add this only to the scalar for now
- Benedikt: Ivan, I remember discussing with you adding extensions to introspection and this could be a way to solve the problem in a generalized way, adding structured metadata that is basically a map attached to any type. One attribute in this map could be a URL.
- Ivan: I think going through my previous point, I think Lee and Andi are right, we shouldn’t have features for other features we didn’t discuss. I agree, I was carried away, we should restrict ourselves, when we have extensions we could discuss allowing to specify URLs as part of types for that, if possible we could have this in mind, it’s not a hard requirement and I don’t see any blockers in the current case and if we need this mechanism in other proposals we can think about this again
- Michael: Should the URL be a string or do we introduce a new URI type? In my opinion, we should keep it a string to limit the number of scalars.
- Evan:
- Lee: I posted a comment on your RFC with some details, one idea for the SDL grammar is rather than adding it to the grammar is adding directives like the deprecated directive, this also means the grammar change wouldn’t be breaking
- Lee: We can spec this as a "well known directive" and come up with rules where it could apply
- Benedikt: I don’t know why we would want to restrict the URI to just scalars. I think we should consider allowing it on any type.
- Lee: That’s usually counter to what we’d advise, it’s always better to start with the most specific change, we’re almost always bad about predicting the future, so it’s usually the reason why we start small and expand outward so if next month we realize this is useful for unions we might expand it if it’s particularly useful.
- Michael: I think this could be good for things like the connections pattern (Relay pagination).
- Andi: I would encourage to stay with the original idea
- Michael: I’d actually stick to Benedikt since we’d get benefits for free, for example describing high level types
- Michael: It would be useful for tagging a Relay connection for example - then we don't have to do name matching to see if it's a connection we can just look at the description URL. (Relating to building a client automatically from a GraphQL schema.)
- Lee: I definitely hear that, I agree with Andi hear to keep this focused for now, I’d love, the reason why it makes me a bit nervous is that I want to make sure that we have an order starting with problems to work toward a list of solutions rather than finding a solution and then problems to fix with this solution, it’s easy to find other problems to a solution and that’s why I want to be particulary careful. I’d love to have a separate discussion for this to find tools where it might be used in and if it arrives on the same solution then it’s beautiful, otherwise a different solution might be better
- Stephen: Would be useful - to be a part of the RFC - to document some of the use cases that potentially fall within the scope of the problem like Relay pagination? It gives a place to say we thought of this but decided not to handle it for now
- Michael: We could start by creating a RFC document to put all things together
- Evan: Sure, I don’t think there’s enough different cases to apply this
- Lee: It’s certainly great to have a single document which captures different cases, I agree that it would be useful to collect which things are clearly out of scope. Cool, Evan anything else?
- Evan: I don’t think so. I was going to ask a review of the spec edits.
- Evan: Okay, one thing: Andy has kindly written a short version of the first spec to use this feature a DateTime spec and it should be separate from this RFC and separate from the GraphQL spec itself but it should live somewhere so it would be nice to find it a home.
- Lee: This is going to be an interesting discussion, this leads up to a great discussion about graphql http.
- Lee: first I totally agree - we need the ability for everything to scale up to support more than one spec.
- Lee: not every spec needs to be a GraphQL foundation spec - one of the things I love about this RFC is that everyone can come up with their own custom scalars and host it themselves and other people can use it should they wish - I think that's awesome; the real superpower behind this proposal.
- Lee: If we all agree that "this is the one right one" for a particular spec, then we should definitely have a place to host this final file.
- Rob: If we’re going to have a place to host the specs it might be a useful place to add common custom scalar implementations as well for servers and clients of a library, I doubt that most users will click through the spec and implement a solution, how do people here think about adding those details to the spec itself?
- Michael: I had the same thought. It would be a great idea. People starting a new project will be able to see how other people implement these types.
- Rob: Yeah exactly
- Lee: I think it matches really well to how we introduced both the spec and the accompanying reference implementation, we should keep a high bar when it comes to the quality of said content
- Andi: To come back to the idea of having or promoting a specific version of a scalar should be the decision we can do, this proposal definitely allows you to come up with anything you want, the question would be whether we want to promote consistency in implementations, then it could be a good time to put it up on graphql.org
- Benedikt: I think the proposal will lift those scalars to a level close to what the built-in scalars are. However, if you don’t want to have them, you are still allowed to do whatever you want with a scalar named DateTime.
- Michael: Which is good, if you need those extra scalars you can add them but you wouldn’t have to. (it's like an onion specification - a core spec that's required and other optional specs)
- Lee: I think that was the nail in the coffin for the DateTime-specific proposal. There was no great name to represent the scalar since people used DateTime to represent all kinds of formats and we couldn’t just decide over that. If we were to put those up the implementations should be official
- Rob: Speaking of official scalars… apologies if it is mentioned in the RFC... but are we going to carve out an official URI scalar type?
- Lee: This is a good open question. Maybe we should add a note that these URIs will be treated as unique opaque identifiers. An anti pattern would be referencing a spec that describes two different types, leading to ambiguity.
- Evan: once a spec is published it shouldn't changed.
- Evan: I don't feel strongly about the multiple scalars referencing the same spec.
- Lee: there's already spec text that says if you have a type named String then it has to behave in this way, so we don't need "specified by" URL for it.
- [Someone] URIs for the existing scalar types have not been stable.
- Lee: the draft is not stable, but the previous links are stable.
- Lee: we can link to the IETF specs - it does not need to be a custom written spec, especially for scalars.
- Michael: with the DateTime example you've specified what's allowed and what is not allowed, but that's not the same as the IETF RFC for date time (it's a subset of it), so we don't want to encourage people to implement the full RFC perhaps.
- Evan: ...and that is why we are doing it in the first place IETF which supports an enormous number of formatting options
- Michael: there are other specs, such as the IEEE spec for floating point numbers, which are extremely well specified and can be used directly.
- Andi: That is exactly our intention: you can point to an official specification and if you need to be a little more specific then you will need to provide a short specification but you can also define a full specification if you need complete control.
- Lee: For the sake of the future of this proposal, I would like to be isolated. I think it is reasonable for people to pick up RFC 3339 and I wouldn’t want to hold it up because the motivating subset of DateTime is not ready yet. I would like to keep them separated.
- Lee: my expectation if such a spec becomes a GraphQL Foundation official spec hosted somewhere that it would be its own repo but the path to go from here to there we can figure it out as we go along.
- Benjie: I have a question about more complex types like file uploads. Currently, there are a number of GraphQL APIs that support upload of files with a variety of methods like JSON using base64 encoding for example with MIME headers. How do we feel about data that is encoded in a different format?
- Michael:
- Lee: <Notes that Facebook have an input type called "File" that when it is present the query has to be handled in a specific way>
- Lee: Mentioning opaque is important because an alternative approach is to allow for machine readable rules like a serialization format like it matches a regex and it has constraints
GraphQL over HTTP specification (see issue) (15m, Ivan)
- Ivan: About GraphQL of HTTP, we discussed a few times in the past, a year ago and a 1.5 years ago. The motivation is a while ago, our company implemented our own GraphQL server and when they had some problems and I had problems troubleshooting because I could not connect to the GraphQL server because they implemented it different. They did not use the proper name for a fields. The spec deliberately does not specify the transport layer.
- Evan: The GraphQL-over-HTTP spec is already hosted at https://graphql.org/learn/serving-over-http/ isn’t it?
- Michael: people coming to the spec read it which is great but then transport is the next big problem; having a good spec for it would be really good for new people getting started writing a GraphQL server over HTTP
- Sam: specifying how to do error codes, etc is really important - we have all this stuff, but it's just not documented
- Lee: I'm really excited about this, we've been discussing it for a long time.
- Lee: we need to make sure it's implemented in the right way in all the servers - express-graphql, graphql-java, etc.
- Lee: it could be more strict, crisper, e.g. whether it takes JSON in HTTP bodies, etc.
- Lee: I'd like to see a working group discuss it - what changes do we need to make to popular clients, what do frameworks need to know, etc.
- Lee: happy to host this as part of the spec working group.
- Lee: need volunteers for 1) champion for this sub-effort; 2) if there's an initial set of people willing to put in the work, I'd love to have them assemble. And let me know if I can give support.
- Gabriel: I would like some clarity as to what belongs in the GraphQL spec and what does not. Like what Sam brought up regarding status codes, we already have everything should be 200 but where should we consider other codes?
- Michael: there are many cases where there are use cases where other transports are very important
- Lee: databases is another example where HTTP isn't used as the transport layer, but GraphQL can help. HTTP is the lion's share of GraphQL usage however.
- Lee: authentication is a really important topic to include in the spec, even if it just says "this is up to you".
- Michael: we can add RFCs for "how to upload binary stuff" and explore other topics, which we cannot do currently.
- Lee: true
- Antoine: there's a part of the GraphQL spec that talks about subscriptions and potential implementations; is the intention of this spec to describe how that might be delivered over polling/websockets/etc?
- Gabriel: is the addition of this spec a reason to remove these things from the spec?
- Lee: we have non-normative notes; they're important for people to understand the spec.
- Lee: in the main GraphQL spec, where we do talk about HTTP, we can specifically reference and link to that spec [the HTTP spec].
- Sam: I’d like to be a part of the group.
- Erik: I would also like to join
- Michael CC: Me as well
- Michael M: there's a GitHub issue on Ivan's repo you can volunteer in.
- Ivan: I'm happy organising a call with GraphiQL team, etc. I'd like to move the repo into GraphQL organization, mark it as a draft, and have people contribute there.
- Ivan: it's pretty easy to write a set of tests, e.g. sending
{__typename}to ensure that the basic request works. - Ivan: also we can add other specs for query batching and other topics.
- Ivan: so using a separate repo makes sense because it allows it to evolve.
- Lee: **[ACTION - Ivan] **Here’s what I propose moving forward… Ivan, schedule a meeting. Use GitHub issues, at least open a number of them.
- Let's use Ivan's existing repo
- Lee: [ACTION - Lee] I will find out what it means to pull in the existing repo into the GraphQL org - that way we can keep the history of the project.
- Gabriel: how do we find out about the meeting.
- Ivan: **[ACTION- Ivan] **I'll create an issue in the repo, you can subscribe to it. I will be trying to ping everybody who might be interested, as it affects a lot of servers in the GraphQL ecosystem. Send the issue to anybody who you think might be interested - we can organise a date and time that works for everyone.
Review implementation complexity of Disallow non-breakable chains of circular references in Input Objects (10m, Benedikt)
- Benedikt: So this one that was discussed in the last working group meeting. It clarifies a particular edge case, circular references of non-null input object types, which might render parts of your schema unusable. There are no such things as references in GraphQL, all the spec change is it points out that fact and disallows making such schemas. We decided last time to examine the complexity of such implementations because this is just clarifying one part of the spec the implementations don’t really need to change, they just need to validate against it.
- One place has a cyclomatic complexity of 6.
- Ivan: we have cycle detection in a couple places (it's not something that initial implementers have to worry about): in the fragments, ...
- Ivan: I think Lee is going to add to the spec about not having cycles. Seems reasonable to rely on this.
- Lee: I have to look into this. B - you said this is optional, you don't have to implement, so why bother? Either it should not be in the spec at all, or it should be a requirement that if you have a cycle in input types then your schema is not valid.
- Benedikt: <>
- Lee: I see, so it’s backwards compatible
- Benedikt: Existing schemas never have to implement it - it's just one less static validation guarantee that they'll have
- Ivan: it's not a breaking change.
- Lee: right now your GraphQL server just wouldn't work properly currently
- Howard: It’s basically advertising that you don’t test
- Michael: it's not possible to use this over JSON/HTTP anyway - so adding it should not be a breaking change
- [Someone] there are other serialization format [e.g. YAML] that allow cycles
- Benedikt: Yeah, I found there are two basic assumptions, 1) GraphQL schemas must be queryable, they should used for querying and 2) GraphQL literals are first class - everything you can do in GraphQL should be expressible in pure GraphQL, features that work only when variables are used are not valid.
- Benedikt: I think the spec text is at a pretty good point. Lee, could you take a look at it for me?
- Lee:** [Action - Lee] **Review the spec text
- Lee: No need to rush on this, I'll take it offline to look into the spec changes.
Input Union RFC (30m, Vince)
- Vince: Updates on RFC:
- Open PRs:
- "add more solution criteria" graphql/graphql-spec#630
- "Add Prior Art section " graphql/graphql-spec#623
- "Criteria" section added:
- All historical Issues closed!
- Open PRs:
- Lee: RFC document is basis of conversation going forward
- Lee: Focus on the criteria, not the solutions
- Benedikt: We should next evaluation how proposed solutions match criteria
- Benjie: hold off on that - open PRs
- Lee: This is a living document. Document is the discussion. It’s fine if people show up late with more info
- Benjie: It won’t always be pass/fail for the criteria
- Lee: traffic light style works well.
- Green: fits criteria
- Red: Clearly fails criteria
- Yellow: In between, with explanation of nuances
- Vince: Shorthand way to identify a criteria, bullets for solution
- Lee: Good idea. For example, numbers for criteria, letters for solutions (or visa versa)
- Ivan: We could speed things up. Sometimes it takes a while to get things merged
- If PR is approved - go ahead and merge.
- Lee: What about dedicated repos for this kind of RFC?
- Example, Vince is championing this effort, but Vince doesn’t have commit rights.
- Vince: Is there a github feature for partial merge rights?
- Ivan: I think so.
- Trevor: I think Code Owners does that. But maybe it’s just for reviewers.
- Ivan: One problem - we want to preserve history.
- Evan Huus: One RFC repo with wide commit access?
- Stephen: Individual RFCs can fork the graphql-spec repo. This allows individual ownership, but the rfc can later be merged while preserving commit history.
- Ivan: Use Github Actions
- Lee: [Action - Lee] Add Vince as a maintainer
- Lee: Does not solve the problem for future RFCs but for now, this will work
- Lee: Vince, is there anything else you need?
- Vince: There is enough to build the next month’s solution criteria so good for now.
- Michael: One more question, do we have a date for specification 2020?
- Lee: December might be tight and January is more likely. Aim for December but promise January.
- Lee: It would be nice if main implementations are ready before spec release, but not mandatory
- Lee: [ACTION - Lee] - go back over the notes and look at the action items. We should have GitHub issues for each of them.
- [Benjie, Lee] Props to Ricky for epic work on GraphiQL