openapi_models.yaml

components:
  parameters:
    EidParam:
      name: eid
      in: query
      description: Unique identifier (UUID) for the exercise.
      required: true
      schema:
        type: string
        example: 12345678-1234-5678-1234-567812345678
    LangParam:
      name: lang
      in: query
      description: ISO 639-1 Language Code for the localization of exercise content.
      required: true
      schema:
        type: string
        example: en
    LastUpdateTimeParam:
      name: last_update_time
      in: query
      description: Time (in milliseconds) of the last update.
      required: true
      schema:
        type: integer
        example: 123456789
    SolutionIndicesParam:
      name: solution_indices
      in: query
      description: Indices for the solutions that should be included in the download.
      required: false
      schema:
        type: array
        items:
          type: integer
          example: 0
        default: []
    UrnParam:
      name: urn
      in: query
      description: CTS URN for referencing the corpus.
      required: true
      schema:
        type: string
        example: urn:cts:latinLit:phi1254.phi001.perseus-lat2:5.6.21-5.6.21
  schemas:
    AnnisResponse:
      description: A response with graph data from ANNIS, possibly with additional data for exercises.
      type: object
      properties:
        exercise_id:
          type: string
          description: Unique identifier (UUID) for the exercise.
          example: 12345678-1234-5678-1234-567812345678
          default: ""
        exercise_type:
          type: string
          description: Type of exercise, concerning interaction and layout.
          example: ddwtos
          default: ""
        frequency_analysis:
          type: array
          description: List of items with frequency data for linguistic phenomena.
          items:
            $ref: "#/components/schemas/FrequencyItem"
          default: []
        graph_data:
          $ref: "#/components/schemas/GraphData"
        solutions:
          type: array
          description: Correct solutions for this exercise.
          items:
            $ref: '#/components/schemas/Solution'
          default: []
        text_complexity:
          $ref: '#/components/schemas/TextComplexity'
        uri:
          type: string
          description: URI for accessing the exercise in this API.
          example: /mc/api/v1.0/file/fd97630c-1f5a-4102-af56-20eb0babdfee
          default: ""
    Corpus:
      description: Collection of texts.
      type: object
      x-tablename: Corpus
      properties:
        author:
          type: string
          description: Author of the texts in the corpus.
          example: Aulus Gellius
          default: "Anonymus"
          nullable: false
        cid:
          type: integer
          description: Unique identifier for the corpus.
          example: 1
          x-primary-key: true
          x-autoincrement: true
        citation_level_1:
          type: string
          description: First level for citing the corpus.
          example: Book
          default: default
        citation_level_2:
          type: string
          description: Second level for citing the corpus.
          example: Chapter
          default: default
        citation_level_3:
          type: string
          description: Third level for citing the corpus.
          example: Section
          default: default
        source_urn:
          type: string
          description: CTS base URN for referencing the corpus.
          example: urn:cts:latinLit:phi1254.phi001.perseus-lat2
          x-unique: true
        title:
          type: string
          description: Corpus title.
          example: Noctes Atticae
          nullable: false
          default: Anonymus
      required:
        - source_urn
    Exercise:
      allOf:
        - $ref: "#/components/schemas/ExerciseBase"
        - $ref: "#/components/schemas/ExerciseExtension"
        - description: Data for creating and evaluating interactive exercises.
          type: object
          x-tablename: Exercise
          properties:
            exercise_type_translation:
              type: string
              description: Localized expression of the exercise type.
              example: Cloze
              default: ""
    ExerciseAuthor:
      type: string
      enum: [ callidus, potsdam ]
      description: Authors of curated exercises in the Machina Callida.
      example: callidus
    ExerciseBase:
      description: Base data for creating and evaluating interactive exercises.
      type: object
      properties:
        correct_feedback:
          type: string
          description: Feedback for successful completion of the exercise.
          example: Well done!
          default: ""
        general_feedback:
          type: string
          description: Feedback for finishing the exercise.
          example: You have finished the exercise.
          default: ""
        incorrect_feedback:
          type: string
          description: Feedback for failing to complete the exercise successfully.
          example: Unfortunately, that answer is wrong.
          default: ""
        instructions:
          type: string
          description: Hints for how to complete the exercise.
          example: Fill in the gaps!
          default: ""
        language:
          type: string
          description: ISO 639-1 Language Code for the localization of exercise content.
          example: en
          default: de
        partially_correct_feedback:
          type: string
          description: Feedback for successfully completing certain parts of the exercise.
          example: Some parts of this answer are correct.
          default: ""
        search_values:
          type: string
          description: Search queries that were used to build the exercise.
          example: "['upostag=noun', 'dependency=object']"
          default: "[]"
        work_author:
          type: string
          description: Name of the person who wrote the base text for the exercise.
          example: C. Iulius Caesar
          default: ""
        work_title:
          type: string
          description: Title of the base text for the exercise.
          example: Noctes Atticae
          default: ""
      required:
        - instructions
        - search_values
    ExerciseExtension:
      description: Additional data for creating and evaluating interactive exercises.
      type: object
      properties:
        conll:
          type: string
          description: CONLL-formatted linguistic annotations represented as a single string.
          example: \# newdoc id = ...\n# sent_id = 1\n# text = Caesar fortis est.\n1\tCaesar\tCaeso\tVERB ...
          default: ""
          nullable: false
        eid:
          type: string
          description: Unique identifier (UUID) for the exercise.
          example: 12345678-1234-5678-1234-567812345678
          x-primary-key: true
        exercise_type:
          type: string
          description: Type of exercise, concerning interaction and layout.
          example: markWords
          default: ""
          nullable: false
        last_access_time:
          type: number
          format: float
          description: When the exercise was last accessed (as POSIX timestamp).
          example: 1234567.789
          x-index: true
        solutions:
          type: string
          description: Correct solutions for the exercise.
          example: "[{'target': {'sentence_id': 1, 'token_id': 7, 'salt_id': 'salt:/urn:...', 'content': 'eo'}, 'value': {'sentence_id': 0, 'token_id': 0, 'content': None, 'salt_id': 'salt:/urn:...'}}]"
          default: "[]"
          nullable: false
        text_complexity:
          type: number
          format: float
          description: Overall text complexity as measured by the software's internal language analysis.
          example: 54.53
          default: 0.0
        urn:
          type: string
          description: CTS URN for the text passage from which the exercise was created.
          example: urn:cts:latinLit:phi0448.phi001.perseus-lat2:1.1.1-1.1.1
          default: ""
          nullable: false
      required:
        - eid
        - last_access_time
    ExerciseForm:
      x-body-name: exercise_data
      type: object
      allOf:
        - $ref: '#/components/schemas/ExerciseBase'
        - description: Additional exercise data.
          type: object
          properties:
            type:
              type: string
              description: Type of exercise, concerning interaction and layout.
              example: markWords
            type_translation:
              type: string
              description: Localized expression of the exercise type.
              example: Cloze
              default: ""
            urn:
              type: string
              description: CTS URN for the text passage from which the exercise was created.
              example: urn:cts:latinLit:phi0448.phi001.perseus-lat2:1.1.1-1.1.1
          required:
            - type
            - urn
    ExerciseTypePath:
      type: string
      enum: [dialog_cards, drag_text, fill_blanks, find_words, mark_words, multi_choice, voc_list]
      description: Paths to the data directories for various H5P exercise types.
      example: drag_text
    FileForm:
      x-body-name: file_data
      description: Metadata for file content to be saved for later access.
      type: object
      properties:
        file_type:
          $ref: '#/components/schemas/FileType'
        html_content:
          type: string
          description: HTML content to be serialized.
          example: <html></html>
        learning_result:
          type: string
          description: Serialized XAPI results for an interactive exercise.
          example: "{'0': {}}"
        urn:
          type: string
          description: CTS URN for the text passage from which the HTML content was created.
          example: urn:cts:latinLit:phi0448.phi001.perseus-lat2:1.1.1-1.1.1
    FileType:
      type: string
      enum: [docx, h5p, json, pdf, xml, zip]
      description: File format for the requested serialization.
      example: pdf
    FrequencyItem:
      type: object
      properties:
        count:
          type: integer
          description: How often the given combination of values occurred.
          example: 1
          default: 0
        phenomena:
          type: array
          description: Labels for the linguistic phenomena described in this frequency entry.
          items:
            $ref: '#/components/schemas/Phenomenon'
          default: []
        values:
          type: array
          description: Values for the phenomena described in this frequency entry.
          items:
            type: string
            example: ""
          default: []
    GraphData:
      type: object
      description: Nodes, edges and metadata for a graph.
      properties:
        directed:
          type: boolean
          description: Whether edges in the returned graph are directed.
          example: true
        graph:
          type: object
          description: Additional graph data.
          example: {}
        links:
          type: array
          description: List of edges for the graph.
          items:
            $ref: '#/components/schemas/Link'
        multigraph:
          type: boolean
          description: Whether the graph consists of multiple subgraphs.
          example: true
        nodes:
          type: array
          description: List of nodes for the graph.
          items:
            $ref: '#/components/schemas/NodeMC'
      required:
        - links
        - nodes
    H5PForm:
      type: object
      description: Metadata for the H5P exercise.
      x-body-name: h5p_data
      properties:
        eid:
          type: string
          description: Unique identifier (UUID) for the exercise.
          example: 12345678-1234-5678-1234-567812345678
        exercise_type_path:
          $ref: '#/components/schemas/ExerciseTypePath'
        lang:
          type: string
          description: ISO 639-1 Language Code for the localization of exercise content.
          example: en
        solution_indices:
          type: array
          items:
            type: integer
            example: 0
          description: Indices for the solutions that should be included in the download.
    KwicForm:
      x-body-name: kwic_data
      type: object
      description: Relevant parameters for creating a Keyword In Context view.
      properties:
        search_values:
          type: string
          description: Search queries that were used to build the exercise.
          example: "['upostag=noun', 'dependency=object']"
          default: "[]"
        urn:
          type: string
          description: CTS URN for the text passage from which the KWIC view should be generated.
          example: urn:cts:latinLit:phi0448.phi001.perseus-lat2:1.1.1-1.1.1
        ctx_left:
          type: integer
          description: Number of tokens that should be given as context on the left side of a target.
          example: 5
        ctx_right:
          type: integer
          description: Number of tokens that should be given as context on the right side of a target.
          example: 5
      required:
        - ctx_left
        - ctx_right
        - search_values
        - urn
    LearningResult:
      description: Learner data for completed exercises.
      type: object
      x-tablename: LearningResult
      properties:
        actor_account_name:
          type: string
          description: H5P user ID, usually unique per device.
          example: ebea3f3e-7410-4215-b34d-c1417f7c7c18
          default: ""
        actor_object_type:
          type: string
          description: Describes the kind of object that was recognized as actor.
          example: Agent
          default: ""
        category_id:
          type: string
          description: Link to the exercise type specification.
          example: http://h5p.org/libraries/H5P.MarkTheWords-1.9
          default: ""
        category_object_type:
          type: string
          description: Describes the kind of object that was recognized as exercise.
          example: Activity
          default: ""
        choices:
          type: string
          description: JSON string containing a list of possible choices, each with ID and description.
          example: "[{'id':'2','description':{'en-US':'Quintus ist bei allen in der Provinz beliebt.\n'}},{'id':'3','description':{'en-US':'Asia ist eine unbekannte Provinz.\n'}}]"
          default: "[]"
        completion:
          type: boolean
          description: Whether the exercise was fully processed or not.
          example: true
        correct_responses_pattern:
          type: string
          description: JSON string containing a list of possible solutions to the exercise, given as patterns of answers.
          example: "['0[,]1[,]2']"
        created_time:
          type: number
          format: float
          description: When the learner data was received (POSIX timestamp).
          example: 1234567.789
          x-index: true
          x-primary-key: true
        duration:
          type: string
          description: How many seconds it took a learner to complete the exercise.
          example: PT9.19S
          default: "PT0S"
        extensions:
          type: string
          description: JSON string containing a mapping of keys and values (usually the local content ID, i.e. a versioning mechanism).
          example: "{'http://h5p.org/x-api/h5p-local-content-id':1}"
          default: "{}"
        interaction_type:
          type: string
          description: Exercise type.
          example: choice
          default: ""
        object_definition_description:
          type: string
          description: Exercise content, possibly including instructions.
          example: "Bestimme die Form von custodem im Satz: Urbs custodem non tyrannum, domus hospitem non expilatorem recepit.\n"
        object_definition_type:
          type: string
          description: Type of object definition that is presented to the user.
          example: http://adlnet.gov/expapi/activities/cmi.interaction
          default: ""
        object_object_type:
          type: string
          description: Type of object that is presented to the user.
          example: Activity
          default: ""
        response:
          type: string
          description: Answer provided by the user, possibly as a pattern.
          example: His in rebus[,]sociis[,]civibus[,]rei publicae
        score_max:
          type: integer
          description: Maximum possible score to be achieved in this exercise.
          example: 1
        score_min:
          type: integer
          description: Minimum score to be achieved in this exercise.
          example: 0
        score_raw:
          type: integer
          description: Score that was actually achieved by the user in this exercise.
          example: 1
        score_scaled:
          type: number
          format: float
          description: Relative score (between 0 and 1) that was actually achieved by the user in this exercise.
          example: 0.8889
          default: 0.0
        success:
          type: boolean
          description: Whether the exercise was successfully completed or not.
          example: true
        verb_display:
          type: string
          description: Type of action that was performed by the user.
          example: answered
          default: ""
        verb_id:
          type: string
          description: Link to the type of action that was performed by the user.
          example: http://adlnet.gov/expapi/verbs/answered
          default: ""
      required:
        - completion
        - correct_responses_pattern
        - created_time
        - object_definition_description
        - response
        - score_max
        - score_min
        - score_raw
        - success
    Link:
      type: object
      properties:
        annis_component_name:
          type: string
          description: Component name as given by ANNIS.
          example: dep
        annis_component_type:
          type: string
          description: Component type as given by ANNIS.
          example: Pointing
        source:
          type: string
          description: ID of the source node for the edge.
          example: salt:/urn:custom:latinLit:proiel.caes-gal.lat:1.1.1/doc1#sent52548tok1
        target:
          type: string
          description: ID of the target node for the edge.
          example: salt:/urn:custom:latinLit:proiel.caes-gal.lat:1.1.1/doc1#sent52548tok3
        udep_deprel:
          type: string
          description: Dependency relation described by the edge.
          example: "det"
    MatchingExercise:
      allOf:
        - $ref: "#/components/schemas/ExerciseBase"
        - $ref: "#/components/schemas/ExerciseExtension"
        - description: Extra data for comparison with a reference vocabulary.
          type: object
          properties:
            exercise_type_translation:
              type: string
              description: Localized expression of the exercise type.
              example: Cloze
            matching_degree:
              type: number
              format: float
              description: Percentage of words in the exercise that match a reference vocabulary.
              example: 76.34
    NearestNeighborCount:
      type: integer
      description: Number of nearest neighbors that should be considered for each target node in a graph analysis.
      example: 50
      default: 0
    NodeMC:
      type: object
      properties:
        annis_node_name:
          type: string
          description: Node name as given by ANNIS.
          example: "urn:custom:latinLit:proiel.caes-gal.lat:1.1.1/doc1#sent52548tok1"
        annis_node_type:
          type: string
          description: Node type as given by ANNIS.
          example: "node"
        annis_tok:
          type: string
          description: Raw word form as given by ANNIS.
          example: "Galliae"
        annis_type:
          type: string
          description: Node type as given by ANNIS (?).
          example: "node"
        id:
          type: string
          description: Unique identifier for the node in the SALT model.
          example: "salt:/urn:custom:latinLit:proiel.caes-gal.lat:1.1.1/doc1#sent52548tok1"
        is_oov:
          type: boolean
          description: Whether the raw word form is missing in a given vocabulary.
          example: true
        udep_lemma:
          type: string
          description: Lemmatized word form.
          example: "Gallia"
        udep_upostag:
          type: string
          description: Universal part of speech tag for the word form.
          example: "PROPN"
        udep_xpostag:
          type: string
          description: Language-specific part of speech tag for the word form.
          example: "Ne"
        udep_feats:
          type: string
          description: Additional morphological information.
          example: "Case=Nom|Gender=Fem|Number=Sing"
        solution:
          type: string
          description: Solution value for this node in an exercise.
          example: ""
    Phenomenon:
      type: string
      enum: [dependency, feats, lemma, upostag]
      description: "Linguistic phenomena: syntactic dependencies, morphological features, lemmata, parts of speech."
      example: upostag
    RawTextForm:
      x-body-name: raw_text_data
      description: Text data for an annotation request.
      properties:
        plain_text:
          description: Plain text data that should be annotated.
          example: Gallia est omnis divisa in partes tres.
          type: string
      required:
        - plain_text
      type: object
    SearchRegex:
      type: string
      description: Regular expression for a textual search.
      example: ver[aoe]
    Sentence:
      type: object
      description: Sentence with metadata
      properties:
        id:
          type: integer
          description: Unique identifier (in the corpus).
          example: 1
        matching_degree:
          type: number
          format: float
          description: Percentage of words in the sentence that match a reference vocabulary.
          example: 76.34
    Solution:
      type: object
      description: Correct solution for an exercise.
      properties:
        target:
          $ref: '#/components/schemas/SolutionElement'
        value:
          $ref: '#/components/schemas/SolutionElement'
    SolutionElement:
      type: object
      description: Target or value of a correct solution for an exercise.
      properties:
        content:
          type: string
          description: Content of the solution element.
          example: unam
        salt_id:
          type: string
          description: Unique identifier for the node in the SALT model.
          example: salt:/urn:custom:latinLit:proiel.caes-gal.lat:1.1.1/doc1#sent52548tok9
        sentence_id:
          type: integer
          description: Unique identifier for the sentence in a corpus.
          example: 52548
        token_id:
          type: integer
          description: Unique identifier for the token in a sentence.
          example: 9
      required:
        - sentence_id
        - token_id
    StaticExercise:
      type: object
      description: Metadata for a static exercise.
      properties:
        solutions:
          type: array
          description: Solutions for the exercise.
          items:
            type: array
            description: Single solution, given as tuple of correct response and its lemma.
            items:
              description: Correct response or corresponding lemma.
              type: string
              example: gaudeas
        urn:
          type: string
          description: CTS URN for the text passage from which the exercise was created.
          example: urn:cts:latinLit:phi0448.phi001.perseus-lat2:1.1.1-1.1.1
    TextComplexity:
      type: object
      description: Mapping of various elements of text complexity to their corresponding values.
      properties:
        all:
          type: number
          format: float
          description: Overall text complexity of the given corpus.
          example: 42.31
        avg_w_len:
          type: number
          format: float
          description: Average length of a word in the given corpus.
          example: 5.4
        avg_w_per_sent:
          type: number
          format: float
          description: Average number of words per sentence.
          example: 5.4
        lex_den:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Lexical density of the given corpus.
          example: 0.43
        n_abl_abs:
          type: integer
          description: Number of ablativi absoluti in the given corpus.
          example: 1
        n_clause:
          type: integer
          description: Number of clauses in the given corpus.
          example: 1
        n_gerund:
          type: integer
          description: Number of gerunds in the given corpus.
          example: 1
        n_inf:
          type: integer
          description: Number of infinitives in the given corpus.
          example: 1
        n_part:
          type: integer
          description: Number of participles in the given corpus.
          example: 1
        n_punct:
          type: integer
          description: Number of punctuation signs in the given corpus.
          example: 1
        n_sent:
          type: integer
          description: Number of sentences in the given corpus.
          example: 1
        n_subclause:
          type: integer
          description: Number of subclauses in the given corpus.
          example: 1
        n_types:
          type: integer
          description: Number of distinct word forms in the given corpus.
          example: 1
        n_w:
          type: integer
          description: Number of words in the given corpus.
          example: 1
        pos:
          type: integer
          description: Number of distinct part of speech tags in the given corpus.
          example: 1
    UpdateInfo:
      description: Timestamps for updates of various resources.
      type: object
      x-tablename: UpdateInfo
      properties:
        created_time:
          type: number
          format: float
          description: When the resource was created (as POSIX timestamp).
          example: 1234567.789
          x-index: true
        last_modified_time:
          type: number
          format: float
          description: When the resource was last modified (as POSIX timestamp).
          example: 1234567.789
          x-index: true
        resource_type:
          type: string
          enum: [cts_data, exercise_list, file_api_clean]
          description: Name of the resource for which update timestamps are indexed.
          example: cts_data
          x-primary-key: true
      required:
        - created_time
        - last_modified_time
        - resource_type
    VectorNetworkForm:
      x-body-name: network_data
      type: object
      description: Relevant parameters for finding sentences that are similar to a target word.
      properties:
        search_regex:
          $ref: '#/components/schemas/SearchRegex'
        nearest_neighbor_count:
          $ref: '#/components/schemas/NearestNeighborCount'
      required:
        - search_regex
    VocabularyMC:
      type: string
      enum: [agldt, bws, proiel, vischer, viva]
      description: "Reference vocabularies: Ancient Greek and Latin Dependency Treebank, Bamberger Wortschatz,
      PROIEL treebank, Vischer Wortkunde, VIVA textbook"
      example: agldt
    VocabularyForm:
      x-body-name: vocabulary_data
      type: object
      description: Relevant parameters for comparing a corpus to a reference vocabulary.
      properties:
        frequency_upper_bound:
          type: integer
          description: Upper bound for reference vocabulary frequency.
          example: 500
        query_urn:
          type: string
          description: URN for the query corpus.
          example: urn:cts:latinLit:phi0448.phi001.perseus-lat2:1.1.1-1.1.1
        vocabulary:
          $ref: '#/components/schemas/VocabularyMC'
      required:
        - frequency_upper_bound
        - query_urn
        - vocabulary
    ZenodoForm:
      x-body-name: zenodo_data
      type: object
      description: Relevant parameters for accessing file URIs in a Zenodo record.
      properties:
        record_id:
          type: integer
          description: Unique identifier of the record for which file URIs shall be retrieved.
          example: 4548959
      required:
        - record_id
    ZenodoMetadataPrefix:
      type: string
      enum: [ marc21, oai_datacite ]
      description: Prefix for requests to the Zenodo API, indicating the desired metadata scheme.
      example: oai_datacite
    ZenodoRecord:
      type: object
      description: Record with header and metadata from Zenodo.
      properties:
        author:
          type: string
          description: Author of the text that serves as a basis or target for this record.
          example: Caesar
        contributor:
          type: array
          items:
            type: string
            description: People that contributed something to the record.
            example: Forst, Alexandra
        creator_name:
          type: array
          items:
            type: string
            description: People that created the record.
            example: Glockemann, Brunhild
        description:
          type: array
          items:
            type: string
            description: Description of the record.
            example: Die Materialien dieser Lerneinheit sollen Lateinstudierende bei der Wortschatzarbeit unterstützen.
        identifier:
          type: array
          items:
            type: string
            description: Identifier for easy access to the record.
            example: https://zenodo.org/record/4515301
        language:
          type: array
          items:
            type: string
            description: Language of the materials in the record.
            example: deu
        subject:
          type: array
          items:
            type: string
            description: Tag that classifies the record.
            example: Latein
        title:
          type: array
          items:
            type: string
            description: Title of the record.
            example: Wortschatztraining zu Caesar, Bellum civile II, 43 bis 44
        version:
          type: array
          items:
            type: string
            description: Version of the record.
            example: 2.0
        work:
          type: array
          items:
            type: string
            description: Name of the work that serves as a basis or target for this record.
            example: Bellum civile II, 43-44