definition.graphql

"Represents a definition ID."
scalar DefinitionId @id

"""
As its name suggests, a definition defines a lemma. A definition has a part of
speech, a description, and, optionally, some inflection tables.

A definition's description contains free-form formatted text. Paragraphs, list
items, headings and other things.
"""
type Definition implements RecentItem {
  "The globally unique ID of the definition."
  id: DefinitionId!

  """
  The term that the definition applies to. This value is equal to `lemma.term`
  and is provided here for convenience.
  """
  term: String!

  "The part of speech that the word belongs to."
  partOfSpeech: PartOfSpeech!

  "Formatted text that describes the definition."
  description: [BlockElement!]!

  "Inflection stems that belong to this definition."
  stems: [DefinitionStem!]!

  """
  Inflection tables that are used by this definiton. The values are returned in
  the order specified by the user.
  """
  inflectionTables: [DefinitionInflectionTable!]!

  "Tags associated with this definition."
  tags: [Tag!]!

  """
  Custom field values attached to this definition. This list only includes those
  fields which have been explicitly assigned a value. If a field is absent from
  this list, it counts as unset. Note that boolean fields are not strictly true
  or false, but rather set or unset: when a boolean field is absent here, it is
  treated as being false.
  """
  fields: [DefinitionFieldValue!]!

  """
  Definitions derived from inflected forms of this definition.

  Note that this list only includes inflected forms set to have lemmas derived
  automatically. To get all inflected forms of a definition, you must fetch the
  `stems` and `inflectionTables` of the definition and "manually" inflect the
  word.

  Since there may be many derived definitions, this field is paginated. If
  provided, `page.perPage` cannot exceed 200.
  """
  derivedDefinitions(page: PageParams): DerivedDefinitionConnection!

  "The lemma that the definition belongs to."
  lemma: Lemma!

  """
  The language that the definition belongs to. This value is equal to
  `lemma.language` and is provided here for convenience.
  """
  language: Language!

  "The time that the definition was created."
  timeCreated: UtcInstant!

  """
  The time of the most recent update to the definition. This time covers updates
  performed on the definition itself, or on its inflection tables, tags or
  stems.
  """
  timeUpdated: UtcInstant!
}

"""
Contains paginated results from one of the following fields:

* `Language.recentDefinitions`
* `InflectionTableLayout.usedByDefinitions`
* `PartOfSpeech.usedByDefinitions`
"""
type DefinitionConnection {
  "Pagination metadata for this batch."
  page: PageInfo!

  "The definitions in this batch."
  nodes: [Definition!]!
}

"""
An inflection stem for a single definition. Stems are used when inflecting the
word: inflected forms contain patterns like `{pl}es`, where `{pl}` is replaced
with the value of the stem named `pl`.
"""
type DefinitionStem {
  "The name of the stem."
  name: String!

  "The value of the stem."
  value: String!

  "The definition that the stem is attached to."
  definition: Definition!
}

"Represents a definition inflection table ID."
scalar DefinitionInflectionTableId @id

"""
An inflection table attached to a single definition. In addition to containing
an table, this type contains an otional caption and any number of custom forms
(chiefly for defining irregular forms).

Note that a definition can have multiple instances of the same inflection table.
Some words inflect differently depending on usage; Condict supports this.
"""
type DefinitionInflectionTable {
  "The globally unique ID of the definition inflection table."
  id: DefinitionInflectionTableId!

  "An optional formatted text that describes the table."
  caption: TableCaption

  """
  A raw JSON string equivalent of `caption`. Generally, you should avoid using
  this field; prefer `caption` whenever possible.
  """
  captionRaw: String

  """
  A list of custom inflected forms, which replace forms in the table. These are
  _generally_ irregular forms, but this is not guaranteed.

  Forms are ordered by inflected form ID.
  """
  customForms: [CustomInflectedForm!]!

  "The inflection table used by the definition."
  inflectionTable: InflectionTable!

  """
  The inflection table layout used by this definition. If the inflection table
  has changed since the definition was added, this layout may point to an older
  version of the table; see the `InflectionTableLayout.isCurrent` field.
  """
  inflectionTableLayout: InflectionTableLayout!

  "The definition that this inflection table is used in."
  definition: Definition!
}

"""
A single paragraph of formatted text, which is used as a caption for inflection
tables attached to a definition.
"""
type TableCaption {
  """
  A list of formatted text parts that make up the caption's content. Note that
  unlike a definition's description, a table caption cannot contain links.
  """
  inlines: [FormattedText!]!
}

"""
A custom inflected form, typically an irregular form. It overrides a single cell
in a definition inflection table.
"""
type CustomInflectedForm {
  "The table that the form belongs to."
  table: DefinitionInflectionTable!

  "The inflected form that this value replaces within its table."
  inflectedForm: InflectedForm!

  "The inflected word itself; the value of the table cell."
  value: String!
}

"The value of a single field as associated with a definition."
interface DefinitionFieldValue {
  "The field that the value belongs to."
  field: Field!
}

"""
For a boolean field, indicates that the field has the value `true`. Fields that
were set to `false` are omitted altogether; they will not be present in the
definition's `Definition.fields` list.
"""
type DefinitionFieldTrueValue implements DefinitionFieldValue {
  field: Field!
}

"Contains the value(s) of a list-type field."
type DefinitionFieldListValue implements DefinitionFieldValue {
  field: Field!

  """
  The selected values. The field may allow only one value to be selected, or
  multiple. This list always has at least one entry, as the empty list is not
  stored anywhere; it's equivalent to not setting the field.
  """
  values: [FieldValue!]!
}

"Contains the value of a plain text field."
type DefinitionFieldPlainTextValue implements DefinitionFieldValue {
  field: Field!

  """
  The field value. The empty string is a valid value, and is *not* equivalent
  to not setting the field.
  """
  value: String!
}

"Contains paginated results from the `Definition.derivedDefinitions` field."
type DerivedDefinitionConnection {
  "Pagination metadata for this batch."
  page: PageInfo!

  "The derived definitions in this batch."
  nodes: [DerivedDefinition!]!
}

"""
A _derived_ definition is an inflected form of a word. When a regular definition
is given an inflection table, each form whose `InflectedForm.deriveLemma` value
is true will be added as a derived definition.

This enables the dictionary to show words like this:

> **birds**
>
> 1. _plural of_ bird
"""
type DerivedDefinition {
  """
  The term that the definition applies to. This value is equal to `lemma.term`
  and is provided here for convenience.
  """
  term: String!

  "The definition that this definition was derived from."
  derivedFrom: Definition!

  "The inflected form that this definition was derived from."
  inflectedForm: InflectedForm!

  "The lemma that the definition belongs to."
  lemma: Lemma!

  """
  The language that the definition belongs to. This value is equal to
  `lemma.language` and `derivedFrom.language`, and is provided here for
  convenience.
  """
  language: Language!
}

extend type Query {
  "Finds a definition by ID."
  definition(id: DefinitionId!): Definition

  "Finds a definition inflection table by ID."
  definitionInflectionTable(
    id: DefinitionInflectionTableId!
  ): DefinitionInflectionTable
}

"Input type for adding new definitions."
input NewDefinitionInput {
  "The language that the definition will be added to."
  languageId: LanguageId!

  """
  The term that this definition defines.

  If there is no lemma for this term, it will automatically be created.
  """
  term: String!

  "The part of speech that the definition belongs to."
  partOfSpeechId: PartOfSpeechId!

  "Formatted text that describes the definition."
  description: [BlockElementInput!]!

  "Inflection stems that belong to this definition."
  stems: [StemInput!]!

  "Inflection tables that are used by this definiton."
  inflectionTables: [NewDefinitionInflectionTableInput!]!

  "Tags associated with this definition."
  tags: [String!]!

  "Custom field values."
  fields: [DefinitionFieldInput!]!
}

"Input type for editing an existing definition. The ID is a separate argument."
input EditDefinitionInput {
  "If set, updates the definition term."
  term: String

  "If set, updates the part of speech."
  partOfSpeechId: PartOfSpeechId

  "If set, updates the definition description."
  description: [BlockElementInput!]

  "If set, updates the definition's inflection stems."
  stems: [StemInput!]

  """
  If set, updates the definition's inflection tables. If the `id` property is
  set on any table in this list, it will update that existing table. For each
  table _without_ an `id`, a new definition inflection table is created.
  """
  inflectionTables: [EditDefinitionInflectionTableInput!]

  "If set, updates the definition's tags."
  tags: [String!]

  """
  If set, updates the definition's custom field values. To clear the
  definition's field values, pass an empty array, not `null`.
  """
  fields: [DefinitionFieldInput!]
}

"Input type for a definition inflection stem."
input StemInput {
  "The name of the stem."
  name: String!

  "The value of the stem."
  value: String!
}

"Input type for a new definition's inflection table."
input NewDefinitionInflectionTableInput {
  "An optional formatted text that describes the table."
  caption: TableCaptionInput

  """
  A list of custom inflected forms, which replace forms in the table. These are
  _generally_ irregular forms, but this is not guaranteed.
  """
  customForms: [CustomInflectedFormInput!]!

  "The inflection table used by the definition."
  inflectionTableId: InflectionTableId!
}

"Input type for editing a definition's inflection table."
input EditDefinitionInflectionTableInput {
  """
  The ID of the definition inflection table. If set, it will update an existing
  definition inflection table.
  """
  id: DefinitionInflectionTableId

  "An optional formatted text that describes the table."
  caption: TableCaptionInput

  """
  A list of custom inflected forms, which replace forms in the table. These are
  _generally_ irregular forms, but this is not guaranteed.
  """
  customForms: [CustomInflectedFormInput!]!

  """
  The inflection table used by the definition. When editing an existing table
  (`id` is not null), this property is ignored; you cannot change to another table.
  """
  inflectionTableId: InflectionTableId!

  """
  If true, upgrades the inflection table's layout to the current version. If the
  table already uses the current version, this field has no effect. When adding
  a new table (`id` is null), this field is ignored; the latest layout version
  is always used. If omitted, defaults to false.
  """
  upgradeTableLayout: Boolean
}

"""
Input type for a table caption, which is a single paragraph of formatted text.
"""
input TableCaptionInput {
  """
  A list of formatted text parts that make up the caption's content. Note that
  unlike a definition's description, a table caption cannot contain links.
  """
  inlines: [FormattedTextInput!]!
}

input CustomInflectedFormInput {
  "The inflected form that this value replaces within its table."
  inflectedFormId: InflectedFormId!

  "The inflected word itself; the value of the table cell."
  value: String!
}

"""
Input type for a single custom field value attached to a definition. At most one
of `booleanValue`, `listValues` and `textValue` can be set, and must match the
field's type.
"""
input DefinitionFieldInput {
  "The field to assign a value to."
  fieldId: FieldId!

  "The value of a boolean field."
  booleanValue: Boolean

  """
  The value of a list field. Some fields may only accept a single value. Passing
  the empty list is equivalent to omitting the field altogether.
  """
  listValues: [FieldValueId!]

  "The value of a plain-text field."
  textValue: String
}

extend type Mutation {
  """
  Adds a definition to the dictionary. The lemma is automatically created based
  on the `term`: if there is a lemma with that term, the definition is added to
  it; otherwise, a lemma is created.

  Requires authentication.
  """
  addDefinition(data: NewDefinitionInput!): Definition

  """
  Edits an existing definition.

  Requires authentication.
  """
  editDefinition(id: DefinitionId!, data: EditDefinitionInput!): Definition

  """
  Deletes a definition.

  Requires authentication.
  """
  deleteDefinition(id: DefinitionId!): Boolean
}