2019-07-03.md

GraphQL Working Group Meeting 2019-07-03

Agenda

Action Items

• GraphQL.org Website Planning / (@tanaypratap)
  • @tanaypratap: Schedule 10-15m meeting to discuss where graphql.org is today and brainstorm action items
  • Unclaimed: Create Q&A on most important details (contents, etc.)
  • @leebyron: Write up vision for code page
• Acceptance Criteria for Editorial Changes / (@IvanGoncharov)
  • @IvanGoncharov: Check maintainers of repository
• DateTime RFC / (@andimarek)
  • Unclaimed: RFC for introspection field for spec information

Notes

Previous Action Items

https://github.com/graphql/graphql-wg/blob/master/notes/2019-06-06.md#action-items

• Lee: Little progress on the last action item (maybe we should link or enumerate on those?)
  • Talked to Chris about metrics, still open to figuring out the details
  • Call for maintainers will be talked about again, vision docs are to be created, discussion should be continued
  • Separate working group meeting for graphql.org will still be opened
  • Interface inheritance will be talked about by Mike
  • @oneField directive is unchecked, not much additional progress on input unions although ideas were collected
  • F.A.Q. repository already created, PRs are collected and merged, waiting for a certain content threshold to create a page from it
• Ivan: RFC about input unions was created
• Lee: Great news, topic was discussed at GraphQL Conf last week. Action items and tracking of those is very helpful, translating action items into GitHub issues in the graphql-wg repository is worth trying

GraphQL.org Website Planning / (@tanaypratap)

• Tanay: Last time we discussed to move to Gatsby, vision document didn’t get a lot of progress, we can continue with the work once document is ready, designers and additional people can be pulled in easily
  • Action Item: Schedule 10-15m meeting to discuss where graphql.org is today and brainstorm action items - Tanay
• Lee: This sounds great, lines up well with graphql.org working group for people wanting to take action, if you (Tanay) want to lead the task of collecting available people that would be helpful, I’ll work on vision document but it should be useful to tease most important things in a Q&A, code page would need most work
  • Action Item: Create Q&A on most important details (contents, etc.)
• Gatsby can be implemented separately from other changes. Mostly a technical change.
• Tanay: Should we change the theme as well?
• Lee: This could be an option, but I think the content of the code page is furthest behind, “Learn” pages are pretty decent and should only need few iterations, front page is also very good but Code page is very bad
• Tanay: I can lead the working group but I don’t have much community reach, so I’d appreciate some help there to get the word out.
• Lee: I’m happy to do that
• Robert: GraphQL and TypeScript. Many people use GraphQL and TypeScript. Having a resource on graphql.org would be useful to expose more information.
• Tanay: I feel that having a place for people to submit collaborative content would also help it, we should tackle this workflow as well
• Lee: Part of the reason why the code section is poorly meeting its goals, the site has a wide variety of information. It can be overwhelming to those new to GraphQL. Each piece should have a place on the site but could be better organized. Having a designer think of this problem and come up with some solutions would be useful.
• Tanay: We need a vision document around it, I can then pull in designers
• Lee: To speed that up... I’ve been thinking of this vision document as something covering all of graphql.org, but could write up something specific to the code page to give to the designer.
  • Action Item: Write up vision for code page - Lee
• Tanay: That would be helpful, let’s do that
• Lee: Who else would like to contribute?
  • Tanay, Ivan, Robert, Bruno

Interface Inheritance RFC / (@mike-marcacci)

Notes from last WG meeting: https://github.com/graphql/graphql-wg/blob/master/notes/2019-06-06.md#interface-inheritance--michael-staib-michaelstaib--chillicream

• Mike: Reviving this topic from a while ago. The spec has changed since then and the RFC implementation. Would be great to get some more review on the implementation PR now that the merge conflicts are resolved. None of the concepts have changed. There’s a PR against graphql-js to implement this. Would love one or two people to commit to a review.
  • Matthew M: I’ll review those PRs.
• Mike: Arbitrary spreads and how that relates to the RFC?
• Matt: This is not a mandatory feature, but we might find a way to restrict interface to interface spreads on specific chains, but that’s an extended feature which might break existing queries
• Lee: As long as we’re careful around those specific cases, we should be good. If I recall correctly, when talking about handling breaking additions for strictness, I remember watching JavaScript adding the “use strict” feature, but I agree to Matt and we should decouple this functionality into a separate opt-in tool
• Matt: Ivan pointed out a specific (link) example
• Ivan via chat: https://github.com/graphql/graphql-js/pull/1497/files#diff-325ff93247e6e817d761b030604b95c0R200

• Ivan: We already have some problems with inheritance, even without talking about multiple layers. I’m actually for this proposal but I think we should really test the changes on graphql-js since it’s hard to test them in the spec. We should try to write as many tests as possible for different edge cases. What if you cast from interfaces and what happens if you use named fragments, etc.? If we enable multi-layer inheritance, it would be more popular and make more sense for most users, which is why we should think about those issues
  • Michael: Wouldn’t that fall under the rule of merging things? We maybe could just merge it.
  • Ivan: What if you merge it up and down? We prevent inline fragments but can’t deny using named fragments on queries, even if it’s passed down and not up. So it’s a bunch of technical details, main point being that we need to figure out this issue or at least consider it, write as many tests as possible. Not only like best implementation but cover various examples. Please also review it then so we can find more edge cases.
  • Mike: This PR, and edge case, is this allowing the query to become valid or is it currently valid?
  • Ivan: It’s currently invalid and in theory it should be valid but we stopped talking about this validation rule because it’s very complex. The main concern was validation performance when talking about it, it’s just an example for a potential feature, in theory interface inheritance is cool but we should encourage everybody to think about edge cases because we don’t talk about it things might break
  • Mike: Sounds good. I’ll keep that in mind.
  • Matt: We could also reduce the RFC to, say, only allow extending unions, where you can’t end up with three chains of inheritance in that case, but maybe that’s an offline discussion
  • Mike: I’d be willing to chat offline regarding the scope of the RFC.
  • Lee: It sounds like we have great next steps, this is clearly a draft and since it’s pretty well-written I’ll adjust the label. We just need to finish it up, implement it to the reference implementation, Matt will be amazing at helping out with validation. Running it through Facebook’s schema would be a great test case for this. We should coordinate some timeframe for this to move it to the next stages
  • Matt M and Mike to chat offline
  • James: Question regarding draft proposal, especially those which can have breaking changes. What’s a good rollout strategy for new features like this? Should we formalize around an experiment phase?
  • Lee: I think, to clarify a bit more about what I said earlier, this should only make it from draft to finished if we can prove no breaking changes. In phase two, opportunities to use interface inheritance to tighten up validation rules might be used later on, but split from the current proposal. If we want to take weird queries and prevent them from being valid, this might be a separate feature which in turn helps us. Through the course of the conversation, we saw that some queries are currently not expressible but can be expressed using inheritance, but if there’s any queries that now become invalid, this would block the proposal.
  • James: Curious about the update mechanism
  • Lee: We should avoid breaking changes completely, I think we’ll have to deal with this problem at one point. This might be a good segway into the next point

DateTime RFC / (@andimarek)

• Andi: sharing screen with notes
• Andi: Refresher on the RFC and what has happened since I presented last time. Value statement: Because it will improve the overall GraphQL experience. DataTime is very widely utilized in GraphQL schemas. Not represented in the spec currently so you need to represent it yourself. Standardizing will allow for tooling around date/time.
• Andi: Many scalars that could be used, like URL, but few have the complexity of date/time. Not straightforward to represent.
• Andi: Ran a survey on how people use date/time scalars and what they think about adding support in the spec.
• Andi: Survey results: What is the type used for date/time values? Most are using a custom type called DateTime.
• Andi: Survey results: How is this type formatted? Most are using RFC 3339
• Andi: Survey results: How should GraphQL handle date/time types? The majority would love GraphQL to handle it somehow and not leaving it to implementers.
• Andi: About scalars
• A scalar is an input and output type. It can’t be restricted to either one. The built-in scalars (string, int, boolean, float, id) need to be implemented exactly as specified)
• RFC 3339 Format - specific point in time expressed as date and time with an offset
• yyyy-MM-dd’T’HH:mm:ss.SSSZ
• 2011-12-03T10:15:30.123+01:00
• Reminder: offset is not a full time zone. A timezone is more complex than an offset. Contains rules for daylight savings time. Represented as a name, e.g. “Europe/Berlin”
• Andi: What happens if you already have a DateTime scalar? Adding a standard DateTime scalar means a breaking change for some existing clients.
• Mike: On the survey, it didn’t contain a subset of people using other names than DateTime, for example using Timestamps, etc. We might end up with fewer breaking changes when asking broader questions
• Lee: We can look at individual entries, so we can filter it down just to people who call their type DateTime and then check on how the type is formatted.
• Evan: We’re also using DateTime using ISO8601, we could maybe just migrate without breaking things but technically it’s another spec
• Andi: The ISO spec defines more conditions. Depends on what part of ISO you’re using for how compatible it might be to RFC 3339.
• Ivan: One question, I just looked at GitHub’s GraphQL API, it doesn’t use an offest, is it required?
• Michael: You can also supply a z as the offset (zulu time), that means it’s +0
• Andi: You can add this as a shortcut, yes
• Ivan: To really solve the problem, we should go over the potential benefits. As I understand, the core idea is when I use Java’s DateTime standard, I can simply return a DateTime response and it’s automatically formatted. Is this the main benefit of this proposal, so more machine-level or what’s the main advantage?
• Michael: You can easily use moment.js for instance, so we implemented it like Andi proposed it. If you define it as specified in the RFC, most tools should be compatible
• Ivan: When the main advantage comes for tools, can we reserve a special prefix (__???) for standard types, we might get the same problems for Int64 which we can’t universally support
• Lee: The primary value of built-in types is ease of use, adding a prefix might lead to them feeling more awkward to use
• Ivan: By prefix I meant that we could implement a mechanism to import a specific DateTime it might suggest using a specific DateTime implementation
• Michael:
• Evan: We need to figure out a way for clients to determine what to expect
• Ivan: If we put the same mechanism into introspection, the clients could be able to see whether it’s just named DateTime or actually is the standard type
• Michael: Problem with most tools is that they don’t check for standards
• Ivan: Agreed, right now tools don’t know about this but in the future we might be able to check for it
• Michael: This would mean that we have multiple tiers of scalars, right? It feels inconsistent
• Andi: I wanted to avoid second-class scalars, the whole benefit of having a built-in version is ease of use. You don’t have to discuss which library to use for a custom scalar. A client tool can validate and check the built in scalar if it’s spec-compliant. This is the core value statement of it all. What are we going to do with servers already using custom scalars?
• Matt: I am in favor of having this DateTime scalar called DateTime. Facebook also uses a non-scalar DateTime type used in several hundred places. Despite that, I’d still like to migrate using a special pattern, for a brief moment we’d be able to rename the non-scalar DateTime, for old clients this is fine because they only error out due to an incorrect type name, but not more. All old fields that returned the old type will have to return the renamed type because they will never be able to support the new format the same way.
• Lee: So you wouldn’t replace the object with a scalar but rename the existing type to avoid conflicts.
• Matt: Exactly, old clients with hardcoded statements on the type name might be a problem but that’s very rare for DateTime usage.
• Lee: Things like fragments might break
• Matt: Luckily our DateTime doesn’t implement much additional logic. What will end up happening is us being stuck in a client-server deadlock because the server can’t ship a new schema and the client can’t be upgraded without it, but we’ll figure it out.
• Lee: I think that we’ve made it clear that renaming an object type may introduce conflicts, does this apply for scalars as well?
• Matt: Yes, for example if your old parser can’t get upgraded, it might cause conflicts
• James: We also ran some internal polls with teams, most call it Date and include some handy functionality fo clients
• Lee: I think that’s very reasonable. If you have a type called DateTime, it’d have to follow those rules.
• James: Other companies might be using object structures as well.
• Evan: We talked a lot about adding a scalar, but there are other breaking changes in the pipeline, do we want to discuss now or add an item to next months agenda on whether and how to ship breaking changes
• Erik: We need to be able to deal with breaking changes eventually
• Andi: I agree that DateTime is currently a placeholder for dealing with those things in the future
• Lee: I think in cases where benefits outweigh the drawbacks, we might go on and if we find a path that helps us to deal with breaking changes in a generic way it might be great but sometimes we’d have to build migration tooling, etc. for breaking changes
• Evan: There are generic solutions like semantic versioning, etc. but most might be overkill for now. My other concern are companies maintaining a much-used public schema and ways to migrate it
• Matt: There are specific things we can do for date/time. For example, with a server implementing a non-compliant format, it’s reasonable to let the server handle migration patterns.
• Lee: That’s one possible migration path, we might provide cases where we allow people to exit spec compliance and provide guidance on dealing with the situation but we should have reliances tools can leverage. Having any place that tells people to opt-in, any time we do that it will make people lose the guarantee of GraphQL
• Evan: if the spec is going to evolve, we need to talk about revisions and companies like Shopify are compliant with the spec right now but with those changes we might no longer be. Having a revision or date would make it unambiguous
• Michael: There are some spec versions though, so you can’t really be compliant to all future versions of the spec
• Lee: That’s true, it’s the reason we started versioning the spec. We don’t expect people to be up-to-date with the draft at any point, because there might be features that break this premise, in cases where those conflicts happen we should find a way
• Mike: I don’t think there’s any spec introspection on the server
• Lee: I mean we could do this but it shouldn’t solve any problem
• Evan: It might be helpful. The spec is versioned but I don’t think it’s represented elsewhere.
• Lee: In practice, if we lose consistency between versions, that will be a problem. Ultimately, while there are year-based cuts of the spec, in practice the servers adopt some features of the next versions but not all, which is why it might not be accurate. Claiming that a server complies to a specific version, doesn’t really help. Breaking changes do have different outcomes, introducing a new validation rule breaks differently from introducing a new scalar.
• Michael: For tooling it should be an opt-in for two-phase introspection where the tools should search for available features and work upon this.
• Andi: With the addition of subscriptions, we added fallback introspection checks for unsupported versions
• Lee: That’s a great example for breaking changes. If we change how introspection works, we might create a two-phase introspection as the right phase. Technically those are future-breaking changes. In the past we introduced validation changes where existing queries remained valid but future queries broke. Coming back to DateTime, we didn’t make clear decisions in the past because we had open questions about potentially breaking changes. This is why we ran the survey and while a majority use it this way, some people and notably Facebook itself uses this differently. Do we want to set a precedent for expanding things like adding more widely-used types? There is value being left on the table so making types like DateTime a separate best practice, you could stay spec-compliant by ignoring the recommendation. We need a decision between value and cost.
• Lee: What do we want generally to be the way that we handle scalars?
• James: To be clear on the ultimate goal. Aside from ID, all other built in scalars aren’t as high-level. What would be the long-term goal for this feature? Deciding to add this as a best practice might not lead to major adoption whereas adding it to the spec will help that. Is DateTime for creating a universal understanding of this system?
• Michael: Ivan’s suggestion in the beginning for prefixing built-in types worked with this, we might need to ask the server whether a DateTime type is spec-compliant which would end up with two classes of scalars.
• Lee: Both to reduce confusion for beginners, but mostly to enforce validation systems and code gen tooling for things like Apollo codegen.
• Evan: We definitely see the possible confusion there
• Andi: The main point was to enable a huge set of tooling, which could only be done by introducing a built-in scalar for people to be able to build tooling around this.
• Matt: Does every server have to include DateTime or when it includes it, does it have to stay compliant?
• Andi: Every DateTime scalar should behave the same way.
• Evan: It would be nice to have additional scalars like DateTime in the mix, but the value of introducing this shouldn’t be worth breaking the spec
• Lee: I agree to this statement, here are some possible paths
• Codifying classes of scalars in introspection (built-in and custom scalars) to differentiate between those two
• We could also say that built-ins should only represent low-level but never high-level data types, the path in the spec for gaining the value might be that
• Matt: If we were to go with the “sister spec” system, the default version of a GraphQL server might use all of those types.
• Lee: With Relay, we had the exact same discussions for functionality like Pagination with connections. We opted for introducing it only in the library instead of making it a built-in feature but I think it wasn’t the best solution. All date implementations are slightly different right now.
• Robert: What if we said that the reference implementation doesn’t have to implement any of the types, what if the introspection offered a “handshake”-like system for asking for features?
• Matt: For modular use cases, it would be great. Given how I’ve seen the ecosystem so far, I don’t think it’s a common way of working with GraphQL. We should encourage new tooling to start off with all of the possibilities, not with forcing extensions.
• James: We built Apollo server with features like uploads, we ran into some issues as well. The next move should be going to a modular server. For people getting started it might be great.
• Robert: I was about to talk about Apollo as the all-in-one solution
• James: Yeah but I think in doing so, we might have chosen the wrong path. We definitely want to do this in a opt-in fashion, offering a progressive understanding
• Robert: Let me give an example. Starting with the server offering a standard DateTime scalar, supporting subscriptions and the pagination spec. What’s the problem with telling a client those details?
• Matt: There shouldn’t be a problem with this. My argument is that a sister-spec should be so good that we would include it in GraphQL’s core.
• Robert: What happens with conflicting functionality in some edge cases? Taking systems like babel presets into account, we’d want to avoid this situation. The module system should be a way of continuing with this. If you introduce two mutually-exclusive features, the server doesn’t handle it now.
• Lee: Babel comparison is a good one. What remains difficult is how these proposals interact with each other. The overlap between sister specifications can be ambiguous.
• James: We already have two classes of scalars, we’re really using out on safety aspects and I think this should be present in the spec, what to do with conflicts. We should evaluate breaking changes incrementally. Adding this to codegen tools might show how effective it is.
• Robert: Consensus is against turning the spec into a modular system.
• Andi: I personally am on the receiving end of the people using apollo file upload, because this is not part of the spec it’s not really a good experience. The whole ecosystem relies on clearly-defined rules, which is a core value of GraphQL. We are losing a lot of value there. If I maintain a public GraphQL API and I can’t change it without creating breaking changes, it doesn’t sound great. Personally I’m really torn between this.
• Michael: The main issue with the file-uploads and other community additions is that they are not co-located with the core spec. If we went down the route of sister specs, they might be more successful, because they are more official.
• James: That’s a great point. We’ve had an intense time with adding more features, because it’s a common entrypoint for the ecosystem. This becomes a burden for other community members, having a predefined level might help developers to decide between choosing which features to implement
• Lee: This is generally a hard problem, going back to Rob’s question, I think it’s a path to consider (modular), the observability of the spec, etc. I don’t want to be quick in deciding this. Beyond arbitrary extensions, the problem we’re trying to solve is about scalars. How do we introduce new scalars, how can we expand it so we don’t have to have this long of a discussion for every feature. There has to be some tooling for this, we can obviously not fulfill every demand with one concept but we need some way to describe interoperability with new scalars. If a scalar introspection had an additional property to link to the describing spec might help as well. Applying arbitrary changes with a modular spec sounds dangerous but going in this direction could be feasible.
• Evan: Adding an introspection field to the spec was some idea I had as well, it seems like a simple plan to add new features without breaking existing implementations
• Lee: What do others think about this idea? This might be a path to take on the route to a modular design. This isn’t necessarily what we’d want to write down but imagine two scalars containing a nullable field called spec/specification, it might be a URL pointing to a document including the rules for this scalar. If there’s a popular set of these, there might be a tool to add additional validation or transformation functionality solely based on this field. It accepts the complexity of not having a machine-readable scalars but it doesn’t exclude any features.
• Michael: What if we just add another level, where we could serialize to some values determined by the spec. Only the spec could introduce those serialization formats. There could be some number scalar serializing to a long, etc.
• Lee: This bases on the assumption that we have a descriptive annotation. We formerly decided that a type only serializes to a specific type.
• Lee: Protobuf for example only supports low-level base types
• Andi: In order to keep it non-breaking we would have to add a way to deal with the DateTime scalar without breaking changes. Exchanges different proposals sounds like an exciting idea.
• Lee: What do you mean by second-class scalars?
• Andi: The DateTime scalar from the spec could collide with other custom (second-class) scalars.
• Lee: It matches reality that GraphQL Ruby includes a date type since Ruby offers a low-level date type.
• Evan: We could add some appendix with commonly used formats
• Lee: Concern of adding scalars to the spec, not so much concern in adding scalars to implementations. Question of whether implementations should provide built-in scalars out of the box that aren’t in the spec. That’s probably fine and implementations across languages are likely to include different scalars right away.
• Andi: Might be a step backwards from the original RFC.
• Lee: Avoiding the breaking change, as the primary concern
• Andi:
• Lee: How many scalars do we end up representing in the spec? Might not be a real problem. There might be just a few added scalars that are widely used in the core spec, and we have a migration plan that’s backwards compatible. Curious of what other people think of that.
• James: I think that could work well.
• Ivan: Unsure of whether we should add a DateTime scalar to the spec.
• If we add a field that says this type is implemented in this way, I don’t think it’s enough. To really bring the value of tooling, we need to provide more than just linking to the RFC.
• Michael: Back to what was discussed earlier, we could ask the server what sister specs the server supports.
• Ivan: We could link to the sister spec, not just to RFCs.
• Robert: Slight difference in directive between URL linking and the module approach.
• Robert: It’s not the content negotiation that is valuable. We have this directive or some other mechanism that this type is in accordance with some spec. How do you disambiguate the conflicts between these possible specs. I don’t think this problem has gone away.
• Lee: I’m not sure that that problem exists when limited to defining how scalars work. We don’t need a GraphQL DateTime type in the specification. We could link the type to the RFC 3339. If we pursue Evan’s suggestion that we include this link, we would need examples. One example could be DateTime, when describing custom scalars. It should link to RFC 3339. For URL, it should also link to the appropriate URL spec (RFC 1738). Provide a mechanism for opting out and backwards compatibility.
• Robert: For linking out to spec URLs, we should have a way of pinning to specific versions, rather than a landing page of some head version.
• Lee: These URLs should point to fixed content
• Robert: Should these URLs always link to human-readable content.
• Lee: Yes. If your tool sees this URL, then that should mean something specific. The tools should know about the URLs and what they mean.
• Ivan: Action Item: RFC for introspection field for spec information
• Robert: We should check in with Andi to get his thoughts
• Andi: I like the general idea about the introspection field but I think it falls a bit short related to complex types, like DateTime. I think it’s a good step in the direction, but it falls short in providing real value for DateTime usage.
• Evan: I’m not sure what you mean about falling short.
• Andi: RFC 3339 is not enough.
• Andi: It’s not clear whether RFC 3339 is just guidance. Whether you can comply with the spec partially. Doesn’t specify the size of milliseconds. Etc.
• Michael: I agree. The general idea of pointing to a spec is enough, but with DateTime specifically, we should figure out how to serialize the data.
• Andi: Serialization guidance is needed for practical implementations
• Dan: I think we need to give more guidance on how these values would be serialized. I’m a bit hesitant to reinvent some of these RFCs.
• Andi: I also don’t want to reinvent RFC 3339. Really about adding more guidance and documentation on how to best implement these types.
• Michael: It’s basically what we do with floats. IEEE-754. This spec states conversion rules.
• Andi: I just want to make sure that this is inside the scope of the working group, that if you have a problem implementing date time, you can go back to the spec and figure it out.
• Lee: There might be a difference between specific rules. RFC 3339 covers everything but we should provide more guidance, adding non-normative notes in the specification.
• Dan: This is the spec, and it’s authoritative, but here is some guidance on how to best implement it within your servers.
• Lee: If there are additional rules, my sense is that we probably don’t, but it could add some friction moving forward.
• Andi: For example, there could be different input/output rules.
• Lee: That’s a good point. Inputs might be more flexible than outputs.
• Evan: Should we have two different RFCs, one for the new introspection field and another for the DateTime guidance.
• Lee: I think we need to address this as one unit.
• Andi: I agree, it would be good to address both at the same time.
• Lee: Evan and Andi will take this further

Acceptance Criteria for Editorial Changes / (@IvanGoncharov)

• Lee: If an editorial change is truly editorial, spelling or grammar, or adding minor clarification, then anyone who has commit access to the repo can review and merge in.
• If there’s ambiguity, we should follow the same RFC process.
• Action Item: Check maintainers of repository
• Tanay: Happy to help out with review
• Lee: Also feel free to ping me. Dan is also happy to help.
• Ivan: I didn’t see the video recordings added to notes from previous meetings
• Lee: I’ll check on the video recordings and add them to the notes.