Annotation GraphQL types

schema.graphql

# Custom scalars and enums
scalar Date
scalar Language
scalar URI

enum MIMEType {
    TEXT_PLAIN
    TEXT_HTML
}

enum FeatureType {
    WORD
    FULL_FORM
    HDWD
    PART
    NUMBER
    CASE
    GRMCASE
    DECLENSION
    GENDER
    TYPE
    CLASS
    GRMCLASS
    CONJUGATION
    COMPARISON
    TENSE
    VOICE
    MOOD
    PERSON
    FREQUENCY
    MEANING
    SOURCE
    FOOTNOTE
    DIALECT
    NOTE
    PRONUNCIATION
    AGE
    AREA
    GEO
    KIND
    DERIVTYPE
    STEMTYPE
    MORPH
    VAR
    RADICAL
    KAYLO
    STATE
}

# Output types
type FeatureValue {
    value: String!
}

type Feature {
    id: ID!
    schema: String!
    type: FeatureType!
    value: [FeatureValue!]!
}

type User {
    id: ID!
    nickname: String
}

type ResourceProvider {
    uri: URI!,
    description: String!,
    right: String!
}

type Comment {
    id: ID!
    text: String!
    language: Language!
    dateTime: Date!
    author: User!
    replies: [Comment!]
}

type Assertion {
    id: ID!
    confidence: Int!
    dateTime: Date!
    author: User!
}

type Negation {
    id: ID!
    confidence: Int!
    dateTime: Date!
    author: User!
}

type Definition {
    id: ID!
    text: String!
    language: Language!
    format: MIMEType!
    lemma: Lemma! # The lemma this is defined by the definition text
    comments: [Comment!]
}

type DefinitionConnection {
    id: ID!
    definitions: [Definition!]
    assertions: [Assertion!]
    negations: [Negation!]
    comments: [Comment!]
}

type DefinitionSet {
    id: ID!
    lemmaWord: String!
    language: Language!
    shortDefs: [DefinitionConnection!]
    fullDefs: [DefinitionConnection!]
}

type Inflection {
    id: ID!
    language: Language!
    stem: String
    prefix: String
    suffix: String
    features: [String!]
    example: String
    comments: [Comment!]
}

type Lemma {
    id: ID!
    word: String!
    language: Language!
    prinicipalParts: [String!]
    variants: [Lemma!] # Alternative versions of the lemma
    partOfSpeech: Feature!
    features: [Feature!] # Part of speech will not be included into the features list
    comments: [Comment!]
}

type Lexeme {
    id: ID!
    lemma: Lemma!
    inflections: [Inflection!]
    meaning: DefinitionSet! # If there are no definitiions, the DefinitionSet will be empty
    comments: [Comment!]
}

type Word {
    id: ID!
    targetWord: String!
    lexemes: [Lexeme!]
}

# Input types
input AssertionInput {
    confidence: Int!
    dateTime: Date!
    authorID: ID!
}

input NegationInput {
    confidence: Int!
    dateTime: Date!
    authorID: ID!
}

input CommentInput {
    text: String!
    language: Language!
    dateTime: Date!
    authorID: ID!
}

input CommentReplyInput {
    commentID: ID!
    comment: CommentInput
}

input LexemeCommentInput {
    lexemeID: ID!
    comment: CommentInput
}

input DefinitionCommentInput {
    definitionID: ID!
    comment: CommentInput
}

input DefinitionConnectionCommentInput {
    definitionConnectionID: ID!
    comment: CommentInput
}

input DefinitionAssertionInput {
    definitionConnectionID: ID!
    assertion: AssertionInput
}

input DefinitionNegationInput {
    definitionConnectionID: ID!
    negation: NegationInput
}

# Mutations
type Mutation {
    # Creates a new comment and attaches it to the specified lexeme
    commentOnLexeme(input: LexemeCommentInput) : Comment

    # Creates a new assertion and attaches it to the specified definitionConnection
    assertDefinitionConnection(input: DefinitionAssertionInput) : Assertion

    # Creates a new negation and attaches it to the specified definitionConnection
    negateDefinitionConnection(input: DefinitionNegationInput) : Negation

    # Creates a new comment and attaches it to the specified definitionConnection
    commentOnDefinitionConnection(input: DefinitionConnectionCommentInput) : Comment

    # Creates a new comment and attaches it to the specified definition
    commentOnDefinition(input: DefinitionCommentInput) : Comment

    # Creates a new reply to the existing comment
    replyToComment(input: CommentReplyInput) : Comment
}

Thanks.

I think we still should make sortOder on Feature optional.

Regarding the mutations, I understand the recommendation from the cited article (https://www.apollographql.com/blog/designing-graphql-mutations-e09de826ed97/) (and others I've read) to suggest that mutations should have single, nested inputs and outputs, as in

commentOnLexeme(input:
  {
    lexemeID: ID!
    comment: CommentInput!
  }) {
    comment: Comment!
  }  

I think we still should make sortOder on Feature optional.

I removed it from the Feature, but left within the FeatureValue. Should I remove it from there too? Would we not need it there tool? What do you think?

Regarding the mutations, I understand the recommendation from the cited article (https://www.apollographql.com/blog/designing-graphql-mutations-e09de826ed97/) (and others I've read) to suggest that mutations should have single, nested inputs and outputs

That's correct, but I was not sure whether to follow it or not. It seemed a little too radical to me. It felt subversive to the language ideas behind the SDL where it allows multiple input parameters. I agree that it's good to keep the number of parameters at the minimum, but I'm not sure if we always should use the only one: creating a wrapper around several variables in order to present it as a single argument seemed like a way to create an extra verbosity. I also do not see any benefits for the versioning, because for that we can create a new mutation. Some other guides I've seen are using several mutation parameters: https://www.apollographql.com/docs/apollo-server/schema/schema/#designing-mutations. GitLab GraphQL API style guide also uses multiple arguments: https://docs.gitlab.com/ee/development/api_graphql_styleguide.html#arguments. So it seems not a clear-cut solution. I don't have a strong opinion on this, neither I have sufficient experience with GraphQL, so I try to keep my mind open. What do you think? Would it be better for us to always use a single input variable?

I removed it from the Feature, but left within the FeatureValue. Should I remove it from there too? Would we not need it there tool? What do you think?

the thing about sortOrder is that it doesn't make sense in the context of a single feature. It belongs to the display domain rather than the data. It's presence in the morphology service output is really a legacy thing.

Regarding the mutations, I understand the recommendation from the cited article (https://www.apollographql.com/blog/designing-graphql-mutations-e09de826ed97/) (and others I've read) to suggest that mutations should have single, nested inputs and outputs

That's correct, but I was not sure whether to follow it or not. It seemed a little too radical to me. It felt subversive to the language ideas behind the SDL where it allows multiple input parameters. I agree that it's good to keep the number of parameters at the minimum, but I'm not sure if we always should use the only one: creating a wrapper around several variables in order to present it as a single argument seemed like a way to create an extra verbosity. I also do not see any benefits for the versioning, because for that we can create a new mutation. Some other guides I've seen are using several mutation parameters: https://www.apollographql.com/docs/apollo-server/schema/schema/#designing-mutations. GitLab GraphQL API style guide also uses multiple arguments: https://docs.gitlab.com/ee/development/api_graphql_styleguide.html#arguments. So it seems not a clear-cut solution. I don't have a strong opinion on this, neither I have sufficient experience with GraphQL, so I try to keep my mind open. What do you think? Would it be better for us to always use a single input variable?

I have read a number of things which support the nesting concept. But as with everything, there are always multiple perspectives. I think we'll see what works best for us as we go.

I have read a number of things which support the nesting concept. But as with everything, there are always multiple perspectives. I think we'll see what works best for us as we go.

I think then we'd better to use the nested input. If it won't work for us, we can switch to using multiple variables.

I've also removed the sortOrder field.