Name edges (or references or links) properly

[simon-wacker]

In GitLab by @simon-wacker on Apr 8, 2020, 17:35

For example name basicStakeholder and roles properly: What is called a role is actually a reference to a person or institution by specifying its id and this reference is implicitly tagged by a role through its sub-schema name (this is true for all roles except author which is actually a person). What is called basicStakeholder is neither a person nor an institution, it is just a reference by id to something by specifying its id and in the description it says that this identifier must be an identifier of a person or institution. The naming is misleading.

I suggest the following naming (open for discussion of course): person is a person; institution is an institution; a new sub-schema stakeholder should be oneOf person or institution; basicStakeholder should be named stakeholderEdge (in graph jargon) or stakeholderReference (in OOP jargon) or stakeholderLink (in WWW jargon); for author we also need personEdge (and for completeness maybe also institutionEdge); I don't have a better name for role right now.

We should add a sub-schema edge and, for other edges with meta information that occur in the schema, use a name with the suffix Edge, make it reference the sub-schema edge, and at meta information.

For the part of the schema that's going to be modeled with GraphQL, we will adhere to the Relay Connection Specificationn (see also Pagination). For the part that's going to be inside JSON BLOBS, I suggest using similar naming, in particular edge, but we don't need connections and meta information regarding pagination. For some background information and an easier introduction to connections see Explaining GraphQL Connections. And for a high-level introduction to GraphQL see GraphQL Concepts Visualized.

[simon-wacker]

While the concrete example of stakeholders and stakeholder edges elaborated above is obsolete after the remodeling done in #111, the general principle still applies and still needs to be applied in other cases.

[christoph-maurer]

We create first the GraphQL schema. Then, we update the JSON schemas.