Prisma1: Make custom additions to the SDL part of the generated schema

[marktani]

Feature Request

This feature requests acts as a central place to discuss making custom additions to the SDL part of the generated schema. There have been various discussions about this before.

Please add your use cases in a new comment below, so I can add them to this list.

What feature are you missing?

When working with Prisma, it's desired or beneficial In several situations to be able to modify the _generated schema_ by making additions to the _datamodel_. Here are a couple of examples:

Descriptions / Comments

This is how it could work:

# The `Post` type is awesome
type Post {
  id: ID! @unique
  # the `title` is mysterious
  title: String!
}

"""
This is a multi-line comment before a type.
"""
type Item {
  id: ID! @unique
  """
  multi-line comments work for fields as well.
  """
  string: String!
}

Directives

This is how it could work:

type Post @taggedType {
  id: ID! @unique
  title: String! @mycustomdirective @anotherone
}

Care has to be taken so custom and out-of-the-box directives from Prisma don't overlap. This might also introduce potential problems for forward compatibility - think of a directive that you add to your schema now, but that is then introduced in a later point in Prisma.

Interfaces

This is how it could work:

type Post implements MyInterface {
  id: ID! @unique
  title: String
  int: Int! # I propose to require types to specify all fields of interfaces they implement
}

interface MyInterface {
  int: Int!
}

The suggestion here is to make adding interfaces to the SDL of the datamodel possible, and to add that information to the generated schema.

If you are interested in adding more powerful query capabilities when defining interfaces, please join the discussion in #83 instead.

How could this feature look like in detail? Tradeoffs?

It's not entirely clear to me, _how_ the added information would end up in the generated schema in the end.

In the above examples, based on the Post type in the datamodel, several types are generated in the generated schema:

• Post, PostConnection, PostEdge
• PostWhereUniqueInput, PostCreateInput
• ...

I'd be curious to hear your input, whether you think that _only adjusting the Post type_ would suffice.

[yuguangmao]

Use Case: if add a comment for a field of data model , the auto-generated prisma.graphql also include it . thanks

[jhalborg]

For comments/documentation of the data model,

only adjusting the Post type would suffice

Also, this seems like a discussion that includes more and larger issues. It seems to me that the ability to just document the data model would be fairly trivial to implement, whereas directives and interfaces are more complex. Perhaps these issues should be separated, as they are quite different?

[viztor]

in the latest GraphQL specification, only string literal is supported as a description field.

[Hitabis]

Could you please add the comments in the generated model?

We are working with prisma-binding and yoga. In yoga we reuse the types and we would like to generate a documentation for the resulting schema (graphdoc).

In general we just import the types from the generated version into the new schema.
# import User from '../generated/prisma.graphql'

Or is there any workaround besides rewriting all the types for the yoga schema?

[lastmjs]

I would like to be able to add custom directives as described here: https://medium.com/@lastmjs/advanced-graphql-directive-permissions-with-prisma-fdee6f846044

Right now I have to manually merge schema types to achieve this because the generated model strips them out. This adds boilerplate for creating custom directive functionality (like directive permissions).

[alan345]

What would be the best practise to add a comment in the playground? Rewrite all types in schema and write comments here?

It would be so much convenient to write comments in the datamodel, then get created in the generated file and finally used one the final schema..

[joshhopkins]

This is very much needed.

[lstwn]

Hey guys,

any progress on the comment topic?
It would dramatically help to have the comment/description feature ready in the datamodel.prisma file itself. Combine this with e. g. graphql-voyager and you have a scalable solution to design and document a database scheme! :)

Please consider splitting this issue because as @jhalborg correctly pointed out, the comments feature is relatively easy to implement and provides big value for many people. Whereas the other features are very relevant, too, but require much more work regarding design, implementation and so on.

For reference, the official spec: https://facebook.github.io/graphql/draft/#Description

Moreover, a quick workaround is not possible right now, since the generated .graphql file is overwritten every time one changes the datamodel.prisma and the comments/descriptions included there are gone... Or does anybody have a great idea?

[FluorescentHallucinogen]

@lstwn PTAL https://github.com/prisma/prisma/issues/1228#issuecomment-371925718 and https://medium.com/@lastmjs/advanced-graphql-directive-permissions-with-prisma-fdee6f846044 for the workaround.

[gabrieltong]

+1

[anton6]

where can I currently find any form of documentation on making "comments" inside the datamodel.graphql file?

[lastmjs]

So I started digging into the Prisma source code to see if it would be possible to add the user-defined directives from datamodel.prisma into the generated schema...unfortunately, it would take more of a fundamental infrastructure change than I was hoping. Here's how it seems to work, in version 1.28.2: datamodel.prisma is converted from a string into an AST. That AST is then traversed and used to build up a GraphQL schema object, the kind defined in the graphql-js library. The problem is that the GraphQLObjectType from graphql-js does not allow directives...thus during the conversion all of the directives are lost. See here for why this is: https://github.com/graphql/graphql-js/issues/1262

So, if anyone is curious, you can go look at the prisma-generate-schema package: https://www.npmjs.com/package/prisma-generate-schema It's not too hard to grasp, I've looked at it for probably an hour or so. My analysis is that the prisma generation would need to be rewritten to work on ASTs more than graphql-js schema objects.

I'm going to probably write some simple AST manipulation functions to add my directives from datamodel.prisma to the generated schema after it is generated, and also allow for some prisma-specific but pretty awesome authorization directives for mutations.