Feature: Schema Ownership

[kamilkisiela]

Option 1: We can use the codebase itself to parse CODEOWNERS files.

Option 2: Allow parsing the schemas with something like:

# CODEOWNERS: dotansimha
type User {
  id: ID!
}

Option 3: we can use the Hive CLI for scanning CODEOWNERS in the fs and then annotate the schema with the GraphQL comment from option 2.

This way we can introduce:

• Visibility of ownership of each type/field/service
• Build a tool for schema approvals - we can communicate it to the Reviewers of a PR back to GitHub, or even add a schema publication check and look for the owners approvals.
• Build a tool for changes visibility - when a schema adds a new reference to a GraphQL type, we can notify the owner of that type/service that the type was used.

I guess we need GH integration first, but it's a good chance to add that.

[n1ru4l]

Related: https://github.com/kamilkisiela/graphql-hive/issues/2747

[comatory]

I wanted to add some suggestions which would work good in our organization:

1. Allow multiple codeowners, e.g. #CODEOWNERS: person1, person2
2. Not sure if it's apparent but in our case the codeowner wouldn't usually be a person but a team so more like #CODEOWNERS: @team-1
3. Our setup is that usually the whole subgraph is owned by some team but in some cases, fields or types can be owned by someone else. Not sure what would be good solution here.
4. Adding codeowner to specific field would also help, I wonder if this would be possible:

# CODEOWNERS: @team-1
type User {
  id: ID!
  # CODEOWNERS: @team-2, @team-3
  posts: PostConnection!
}

I love the idea with schema approvals built into the tool. Our setup at the moment is that we have internal schema governor Github team which owns generated .graphql files in every repo, so we do that in Github. But having optional ability to approve the schema by separate group of people would work well with federated graph.

[n1ru4l]

I think we should probably solve this with schema directives, something like the following:

type User @codeOwners(teams: ["team-1"]) {
  id: ID!
  posts: PostConnection! @codeOwners(teams: ["team-2", "team-3"])
}

[n1ru4l]

Apollo Federation also supports schema ownership through directives: https://www.apollographql.com/docs/technotes/TN0036-owner-pattern/

directive @owner(team: String!) on OBJECT

[comatory]

Apollo Federation also supports schema ownership through directives: https://www.apollographql.com/docs/technotes/TN0036-owner-pattern/

directive @owner(team: String!) on OBJECT

Thanks, I see that it's only for Federation v2 though but it's definitely good to know. Do you happen to know if GraphQL Fusion spec will suport such directive?

Anyway I think we're talking about two related things here but maybe it's important to make the distinction

1. Having visibility into ownership via UI in Hive
2. Adding the ownership metadata

I think for #2, there's few more things I'd like to consider:

2a. leveraging CODEOWNERS file

Our setup often has multiple subschemas defined in single repository, they all get published separately to Hive. The "codeowners" file then contains entry like this:

src/module-1/schema.graphql @team-1

This is great because we can get triggered on code reviews when that file changes. But perhaps Hive could have a way of marking @team-1 to be owners of the whole sub-schema. I'm not sure how this would work in practice though. Adding field/type/mutation etc. annotation everywhere might make inspecting the schema messy (but I'd probably take that).

On the other hand there could be a comment on top of the file:

# CODEOWNERS: @team-1

Hive could then parse this so everything would be considered being owned by @team-1 unless overridden with a directive (ofc it should exclude federated fields). This comment could be generated by Hive CLI by looking at repository's CODEOWNERS file or maybe by passing some metadata when publishing.

2b. overriding ownership with directives

This could work regardless of top-level comment mentioned in 2a. Basically it'd be something added manually for specific parts of sub-schema. But if the top-level comment was present, the given field containing ownership directive would override that. When inspecting the schema with eyeballs, it would make it still human readable.

IDK, does it make sense to you? I'm just trying to thing of easy way to have granular ownership while still leveraging CODEOWNERS file.

[jdolle]

Using comments could cause existing tools/implementations to leak this information which may not be desirable.

CODEOWNERS seems convenient, and I love the idea of using owners for schema approvals. But I think it could tie us to github prematurely. I could see organizations wanting to use a number of integrations with ownership such as github, email, okta, pagerduty, or datadog.

I prefer directives since they don't show up in the API schema and can be applied to subsections of the schema. I think our existing metadata implementation could also be used to set an owner on the entire schema and would allow us to support non-federated schemas.

[dotansimha]

Using comments could cause existing tools/implementations to leak this information which may not be desirable.

I generally agree with that, but maybe we can consider using the comment format (# ...) instead of description here? (""" ... """). This way it should be simpler to remove/clean, as comments should probably be removed anyway? 🤔

CODEOWNERS seems convenient, and I love the idea of using owners for schema approvals. But I think it could tie us to github prematurely. I could see organizations wanting to use a number of integrations with ownership such as github, email, okta, pagerduty, or datadog.

I agree. Should we just consider depending on git for that? Meaning, the CLI can read CODEOWNER files from a directory and ship this info with check/publish? 🤔

[comatory]

Wouldn't supporting @owner directive be good for compatibility reasons?

[jdolle]

@owner isnt an official part of the federation spec. The linked docs that describe an @owner directive is an example of how you could go about doing this if you wanted to. If it were official, it'd be listed here and wouldn't require @composeDirective.

I think it's a good reference for us, but we don't necessarily need that exact implementation.

[jdolle]

I've merged support for metadata via directives, and a display in our UI. If interested, please review the two PR's referenced above. I included screenshots in them.

This should be a great foundation for any additional specialized metadata behavior. We'll likely be doing some internal testing before announcing this feature to a broader audience.

[jdolle]

With metadata now visible on the insights page, this task is complete. There will be followup issues to complete the secondary work:

Build a tool for schema approvals - we can communicate it to the Reviewers of a PR back to GitHub, or even add a schema publication check and look for the owners approvals.

Build a tool for changes visibility - when a schema adds a new reference to a GraphQL type, we can notify the owner of that type/service that the type was used.