docs icon indicating copy to clipboard operation
docs copied to clipboard

Improve documentation about optional/required relations

Open keerlu opened this issue 2 years ago • 0 comments

Improve the documentation for optional/required relations here and here:

  • Currently we use required/mandatory/non-optional interchangeably and should pick one
  • Figure out how to describe relations - the relation itself vs. its parts (relation field and relation scalar)

Details from @janpio below, also see Slack thread:

While talking to @jkomyno last week I realized something: Our documentation around "optional" and "mandatory/non-optional/required" relation (fields) is a bit confusing: https://www.prisma.io/docs/concepts/components/prisma-schema/relations/one-to-one-relations#required-and-optional-1-1-relation-fields

Required and optional 1-1 relation fields In a one-to-one relation, the side of the relation without a relation scalar (the field representing the foreign key in the database) must be optional: ... However, you can choose if the side of the relation with a relation scalar should be optional or mandatory. https://www.prisma.io/docs/concepts/components/prisma-schema/relations/one-to-many-relations#required-and-optional-rela[…]s-in-one-to-many-relations Required and optional relation fields in one-to-many relations The list side of a 1-n relation is always mandatory. On the other side of the relation, the annotated relation field and relation scalar can either both be optional, or both be mandatory.

Note the bold terms: Required, optional and mandatory. Note the italic terms: Relation field(s), relation scalar. So our documentation is about the field in the relation and its properties. That shows 2 challenges for me: Day to day we actually talk more about "optional relation" and "non-optional/required/mandatory relation" - instead about the "relation field". That is quite a disconnect. The terminology around option/non-optional/mandatory/required seems interchangeable. (When researching this I also realized that we are ordering the optional and mandatory relations different for 1:1 and 1:n in our docs https://github.com/prisma/docs/pull/3858/files)

keerlu avatar Oct 11 '22 12:10 keerlu