The specs from apollographql

(nullability) Allow @catch directive to apply all usages of interface field in an operation

Can we consider extending the nullability spec to allow applying the @catch to an interface type, and have it apply to all fields in that operation which implement that interface? Maybe using schema extensions if that's a better fit.

Here's an example of what our schema looks like:

interface PageRow {
  entitiesConnection: RowEntitiesConnection
}

interface RowEntitiesConnection {
  edges: RowEntitiesEdge 
}

interface RowEntitiesEdge {
  index: Int
  node: RowEntity # this is also an interface
}

type VideoRow implements PageRow {
  entitiesConnection: VideoRowEntitiesConnection
  edges: VideoRowEntitiesEdge
}

type VideoRowEntitiesEdge implements RowEntitiesEdge {
  index: Int
  node: VideoEntity
}

## Imagine similar types for, say, `GamesRow`, `GamesRowEntitiesEdge` and `GameEntity`.

And then in our operations, we use spreads to

fragment RowData on PageRow {
  ...GenericRow
  ...VideoRow
  ...GameRow
}

fragment GenericRow on PageRow {
  ## fetch `index` via the connection -> edge
}

fragment VideoRow on PageRow {
  ## fetch video entities
}

fragment GameRow on PageRow {
  ## fetch game entities 
}

Currently, if I want to @catch something at an entity level, I would need to end up adding the @catch at every single usage of the PageRow, which can be over 20-25 rows for a given operation.

As a result, I think we could add a @catch for, say, RowEntitiesEdge, and allow it to "apply" to all the concrete field usages, I think it would allow us to use that directive in a more straightforward and clean way.

Migrate Specs deployments to Netlify

This not only moves us to Netlify to be aligned with the site deployment pattern employed by our other repositories in the Apollo organization and remove this outlier, but it fixes our trailing slash problem in #3.

Steps

Follow-up

Transfer all repositories in this organization to apollographql
Rename apollo-specs.github.io to just specs
Re-link the GitHub repositories in Netlify for each:
Consider / plan a conversion to Gatsby (with specs-md as a plugin, most likely)
Opened issue #7

Support wildcard imports?

Would be nice to allow wildcard imports, like in Java and Kotlin:

extend schema @link(
  url: "https://specs.apollo.dev/nullability/v0.1", 
  import: "*"
)

Thanks to list input coercion, the "*" would be coerced to ["*"]

Another option would be to treat "" as a special case for the as parameter and not add the __ in that case:

extend schema @link(
  url: "https://specs.apollo.dev/nullability/v0.1", 
  as: ""
)

Delete the apollo-specs GitHub organization

Follows-up on #6:

My intention is to delete the apollo-specs GitHub organization, now that it is empty. If there are no objections, I'll do that next week.

Missing spec for join v0.4

apollographql/federation#2907 added support for https://specs.apollo.dev/join/v0.4 but that URL is a 404 error as of this writing, and that version is not listed on https://specs.apollo.dev/.

What changed in this version? See also apollographql/federation-next#233

Consider / plan a conversion to Gatsby (with `spec-md` as a plugin?)

Follows-up on #6

Netlify and Gatsby is the predominant way we build sites at Apollo. While it has some shortcomings, our team is familiar with it and we should build on that (and have them fix the short-comings). That said, I find spec-md to be pretty great for what we're trying to represent here.

Strawdog/needs-full-plan: I think rather than generating the spec-md HTML via CLI, we could instead use its API's html method, perhaps coupled with a Gatsby source plugin like, but maybe not gatsby-source-plugin and a subsequent transformer.

Change `@semanticNonNull.level` and `@catch.level` default to be `0`?

Follow up from comment from @captbaritone on discord.
The current description of @semanticNonNull states that:

"""
...
If `level` is null, all levels are semantically non null.
...
"""
directive @semanticNonNull(field: String = null, level: Int = null) repeatable on FIELD_DEFINITION | OBJECT

One advantage is that it's more compact in list cases. Compare:

type User {
  # make all levels nullable with a single directive
  friends: [Users] @semanticNonNull
}

to

type User {
  # making all levels nullable requires several directives
  friends: [Users] @semanticNonNull(level: 0) @semanticNonNull(level: 1)
}

A drawback is that it makes the directive definition more complex (level is now nullable, this is surprising).

Another drawback is that it opens the door to ambiguous behaviour:

type User {
  # should that be an error? a warning?
  friends: [Users!] @semanticNonNull
}

Since @semanticNonNull applies to all levels above, it's also applying to User!, should that be an error?

There's a tradeoff of compactness vs explicitness. Since @semanticNonNull is itself verbose already maybe the extra verbosity is worth it if it makes things more explicit.

Enable Specs URLs to Return JSON

It would be nice if we could return a JSON blob of the directives and their definition specific to a federation version; for example: https://specs.apollo.dev/federation/v2.0?format=json
would return something like:

{
    "@key":"directive @key(fields: _FieldSet!, resolvable: Boolean) repeatable on OBJECT | INTERFACE",
    "@link":"directive @link(import: [link_Import!], url: String!) repeatable on SCHEMA\nscalar link_Import",
    "@shareable":"directive @shareable on OBJECT | FIELD_DEFINITION"
}

As we continue to iterate on Federation 2 with new versions and had to update definitions (as we did with @key from a single arg to two from Fed1->2), it would be a lot easier for devs to programmatically support new versions as well as being more definitive on what those definitions should be.

Additionally, we should evaluate if we should dictate whether the directive is handled at the gateway/router level, or subgraph; if we want to fully support new directives, we should include information whether there is implementation details that the third party needs to adjust- for example, @key requires work by the library to implement entities and entity resolvers to support fully.

@link spec vs implementation considerations

This is to note some inconsistencies between the @link spec text and the existing implementations (in particular, in @apollo/federation).

I'm not proposing immediate action, but I think it will be a helpful reference to have these differences explicitly written down.

URL-ness -- according to the spec, @link(url:) can be a string that is not a valid URL:

If url: is not a valid RFC 3986 url, then it MUST be treated as an opaque identifier for the foreign schema. Such non-URL inputs to url: SHOULD NOT have name and version information extracted from them—both are {null}.

@apollo/federation does not accept non-URL values.
Optional name and version -- the spec says a name and version MAY be provided in @link(url:). @apollo/federation requires both.
Name syntax -- the spec says a spec name in @link(url:) MUST be a valid GraphQL name (if it exists). @apollo/federation does not enforce this, and happily parses invalid names. In practice this doesn't affect the behaviour much, as users cannot write definitions for namespaced elements where the namespace is invalid, so it just means that everything has to be explicitly imported or aliased.

apollographql / specs Goto Github PK

specs's People

Contributors

Stargazers

Watchers

Forkers

specs's Issues

Steps

Follow-up

Recommend Projects

Recommend Topics

Recommend Org

Jobs