openapi.yaml

openapi: 3.0.2
info:
  description: >
    This is an NLP services server that analyzes a text using the library [KotlinNLP](https://github.com/KotlinNLP).
  version: 1.0.0
  title: NLP Services
  contact:
    email: info@kotlinnlp.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
  description: Visit the full KotlinNLP library
  url: https://github.com/KotlinNLP
servers:
  - url: http://localhost
    variables:
      port:
        default: '3000'
      basePath:
        default: /
tags:
  - name: NLPService
    description: Services for the analysis of texts written in natural language
    externalDocs:
      description: Find out more
      url: https://github.com/KotlinNLP/NLPServer
paths:
  /analyze:
    post:
      tags:
        - NLPService
      summary: Get the complete analysis of a text
      operationId: analyzeText
      parameters:
        - name: distribution
          in: query
          description: whether to return the score distributions of various analysis elements
          required: false
          schema:
            type: boolean
            default: false
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          description: text successfully analyzed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NLPAnalysis'
        400:
          description: Invalid input
  /categorize:
    post:
      tags:
        - NLPService
      summary: Categorize a text respect to all the available domains
      operationId: categorize
      parameters:
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
        - name: distribution
          in: query
          description: whether to return the score distributions of the possible categories
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/AllCategorizations'
        400:
          description: Invalid input
  /categorize/{domainId}:
    post:
      tags:
        - NLPService
      summary: Categorize a text respect to a given domain
      operationId: categorizeDomain
      parameters:
        - $ref: '#/components/parameters/DomainId'
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
        - name: distribution
          in: query
          description: whether to return the score distributions of the possible categories
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/SingleCategorization'
        400:
          description: Invalid input
  /compare:
    post:
      tags:
        - NLPService
      summary: Compare a reference text with others
      operationId: compare
      parameters:
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/ComparingTexts'
      responses:
        200:
          $ref: '#/components/responses/Comparison'
        400:
          description: Invalid input
  /compare/{language}:
    post:
      tags:
        - NLPService
      summary: Compare a reference text with others, forcing the analysis language
      operationId: compareLang
      parameters:
        - $ref: '#/components/parameters/LanguageISO'
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/ComparingTexts'
      responses:
        200:
          $ref: '#/components/responses/Comparison'
        400:
          description: Invalid input
  /frames:
    post:
      tags:
        - NLPService
      summary: Extract frames from a text, respect to all the available domains
      operationId: extractFrames
      parameters:
        - name: lang
          in: query
          description: force the language analysis
          required: false
          schema:
            $ref: '#/components/schemas/IsoA2'
        - name: distribution
          in: query
          description: whether to return the score distributions of various analysis elements
          required: false
          schema:
            type: boolean
            default: false
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/FramesExtraction'
        400:
          description: Invalid input
  /frames/{domainId}:
    post:
      tags:
        - NLPService
      summary: Extract frames from a text, respect to a given domain
      operationId: extractDomainFrames
      parameters:
        - $ref: '#/components/parameters/DomainId'
        - name: lang
          in: query
          description: force the language analysis
          required: false
          schema:
            $ref: '#/components/schemas/IsoA2'
        - name: distribution
          in: query
          description: whether to return the score distributions of various analysis elements
          required: false
          schema:
            type: boolean
            default: false
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/FramesExtraction'
        400:
          description: Invalid input
  /language:
    post:
      tags:
        - NLPService
      summary: Detect the language of a text
      operationId: getLanguage
      parameters:
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
        - name: distribution
          in: query
          description: whether to return the score distributions of the possible languages
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/LangDetection'
        400:
          description: Invalid input
  /label:
    post:
      tags:
        - NLPService
      summary: Label a text respect to all the available domains
      operationId: label
      parameters:
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/AllLabelings'
        400:
          description: Invalid input
  /label/{domainId}:
    post:
      tags:
        - NLPService
      summary: Label a text respect to a given domain
      operationId: labelDomain
      parameters:
        - $ref: '#/components/parameters/DomainId'
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/SingleLabeling'
        400:
          description: Invalid input
  /locations:
    post:
      tags:
        - NLPService
      summary: Find locations mentioned in a text
      operationId: findLocations
      parameters:
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/Locations'
      responses:
        200:
          $ref: '#/components/responses/Locations'
        400:
          description: Invalid input
  /locations/{language}:
    post:
      tags:
        - NLPService
      summary: Find locations mentioned in a text, forcing the analysis language
      operationId: findLocationsLang
      parameters:
        - $ref: '#/components/parameters/LanguageISO'
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/Locations'
      responses:
        200:
          $ref: '#/components/responses/Locations'
        400:
          description: Invalid input
  /morpho/datetimes:
    post:
      tags:
        - NLPService
      summary: Search for date-time expressions in a text
      operationId: getDateTimes
      parameters:
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/DateTimes'
        400:
          description: Invalid input
  /morpho/datetimes/{language}:
    post:
      tags:
        - NLPService
      summary: Search for date-time expressions in a text, forcing the analysis language
      operationId: getLangDateTimes
      parameters:
        - $ref: '#/components/parameters/LanguageISO'
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/DateTimes'
        400:
          description: Invalid input
  /morpho/numbers:
    post:
      tags:
        - NLPService
      summary: Search for numerical expressions in a text
      operationId: getNumbers
      parameters:
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/Numbers'
        400:
          description: Invalid input
  /morpho/numbers/{language}:
    post:
      tags:
        - NLPService
      summary: Search for numerical expressions in a text, forcing the analysis language
      operationId: getLangNumbers
      parameters:
        - $ref: '#/components/parameters/LanguageISO'
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/Numbers'
        400:
          description: Invalid input
  /parse:
    post:
      tags:
        - NLPService
      summary: Parse syntactically and morphologically a text
      operationId: parse
      parameters:
        - name: distribution
          in: query
          description: whether to return the score distributions of various analysis elements
          required: false
          schema:
            type: boolean
            default: false
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          description: text successfully parsed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinguisticAnalysis'
        400:
          description: Invalid input
  /parse/{language}:
    post:
      tags:
        - NLPService
      summary: Parse syntactically and morphologically a text, forcing the language analysis
      operationId: parseLang
      parameters:
        - $ref: '#/components/parameters/LanguageISO'
        - name: distribution
          in: query
          description: whether to return the score distributions of various analysis elements
          required: false
          schema:
            type: boolean
            default: false
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          description: text successfully parsed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinguisticAnalysis'
        400:
          description: Invalid input
  /summarize:
    post:
      tags:
        - NLPService
      summary: Get the summary of a text
      operationId: summarize
      parameters:
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          description: text successfully summarized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Summary'
        400:
          description: Invalid input
  /summarize/{language}:
    post:
      tags:
        - NLPService
      summary: Get the summary of a text, forcing the analysis language
      operationId: summarizeLang
      parameters:
        - $ref: '#/components/parameters/LanguageISO'
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          description: text successfully summarized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Summary'
        400:
          description: Invalid input
  /tokenize:
    post:
      tags:
        - NLPService
      summary: Split a text in sentences and tokens, automatically detecting the language
      operationId: tokenize
      parameters:
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/Tokenization'
        400:
          description: Invalid input
  /tokenize/{language}:
    post:
      tags:
        - NLPService
      summary: Split a text in sentences and tokens, using the tokenizer for a specific language
      operationId: tokenizeLang
      parameters:
        - $ref: '#/components/parameters/LanguageISO'
        - name: pretty
          in: query
          description: whether to indent the returned JSON string, for a major readability
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/InputText'
      responses:
        200:
          $ref: '#/components/responses/Tokenization'
        400:
          description: Invalid input
components:
  parameters:
    DomainId:
      name: domainId
      in: path
      description: the ID of a domain
      required: true
      schema:
        type: string
    LanguageISO:
      name: language
      in: path
      description: the ISO 639-1 code of a language
      required: true
      schema:
        $ref: '#/components/schemas/IsoA2'
  requestBodies:
    InputText:
      description: the input text
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InputText'
    Locations:
      description: the input text
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LocationsInput'
    ComparingTexts:
      description: the texts for the comparison
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ComparingTexts'
  responses:
    LangDetection:
      description: language detected successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Language'
    Tokenization:
      description: text tokenized successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TokenizedText'
    AllCategorizations:
      description: texts classified successfully
      content:
        application/json:
          schema:
            type: array
            description: the categorizations respect to all the available domains
            items:
              $ref: '#/components/schemas/Categorization'
    SingleCategorization:
      description: texts classified successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Categorization'
    AllLabelings:
      description: texts labeled successfully
      content:
        application/json:
          schema:
            type: array
            description: the labelings respect to all the available domains
            items:
              $ref: '#/components/schemas/Labeling'
    SingleLabeling:
      description: texts labeled successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Labeling'
    FramesExtraction:
      description: frames extracted successfully
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ExtractFramesResponse'
    Comparison:
      description: texts compared successfully
      content:
        application/json:
          schema:
            type: array
            description: the comparison between a text and others
            items:
              $ref: '#/components/schemas/ScoredId'
    Numbers:
      description: numbers searched successfully
      content:
        application/json:
          schema:
            type: array
            description: the numerical expressions found in the input text
            items:
              $ref: '#/components/schemas/NumExpr'
    DateTimes:
      description: date-times searched successfully
      content:
        application/json:
          schema:
            type: array
            description: the date-time expressions found in the input text
            items:
              $ref: '#/components/schemas/DateTimeExpr'
    Locations:
      description: locations searched successfully
      content:
        application/json:
          schema:
            type: array
            description: the locations mentioned in the input text
            items:
              $ref: '#/components/schemas/Location'
  schemas:
    InputText:
      type: object
      description: the input text
      required:
        - text
      properties:
        text:
          type: string
        id:
          type: integer
          format: int32
          nullable: true
          default: null
    LocationsInput:
      allOf:
        - $ref: '#/components/schemas/InputText'
        - type: object
          properties:
            candidates:
              type: array
              description: >
                Entities candidate as locations.
                If present, they are validated and disambiguated respect to actual geo-locations, otherwise candidates
                are searched automatically with a named-entity labeler.
              items:
                type: object
                required:
                  - name
                  - score
                properties:
                  name:
                    type: string
                    description: the candidate name
                  score:
                    type: number
                    format: double
                    description: >
                      An initial score associated to the candidate.
                      It is used to give importance to the candidate respect to a specific aspect (e.g. linguistic or
                      semantic).
    TokenizedText:
      type: array
      description: a text split in sentences and tokens
      items:
        $ref: '#/components/schemas/TokenizedSentence'
    TokenizedSentence:
      type: object
      description: a sentence split in tokens
      required:
        - start
        - end
        - tokens
      properties:
        start:
          type: integer
          format: int32
          description: the starting char index
        end:
          type: integer
          format: int32
          description: the ending char index
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/TokenizedToken'
    TokenizedToken:
      type: object
      description: a sentence split in tokens
      required:
        - start
        - end
        - form
      properties:
        start:
          type: integer
          format: int32
          description: the starting char index
        end:
          type: integer
          format: int32
          description: the ending char index
        form:
          type: string
          description: the token form
    ExtractFramesResponse:
      type: object
      required:
        - domain
        - sentences
      properties:
        domain:
          type: string
        sentences:
          type: array
          items:
            $ref: '#/components/schemas/ExtractedFrame'
    ExtractedFrame:
      type: object
      required:
        - intent
      properties:
        intent:
          $ref: '#/components/schemas/NLPIntent'
        distribution:
          type: array
          items:
            type: object
            required:
              - intent
              - score
            properties:
              intent:
                type: string
                description: The name of the intent
              score:
                $ref: '#/components/schemas/Score'
    Categorization:
      type: object
      description: the text categorization respect to a specific domain
      required:
        - domain
        - categories
      properties:
        domain:
          type: string
          description: the categorization domain
        categories:
          type: array
          description: the categories assigned, one per hierarchical level
          items:
            $ref: '#/components/schemas/Category'
    Labeling:
      type: object
      description: the text labeling respect to a specific domain
      required:
        - domain
        - sentences
      properties:
        domain:
          type: string
          description: the labeling domain
        sentences:
          type: array
          description: the labeled sentences
          items:
            type: object
            required:
              - tokens
            properties:
              tokens:
                type: array
                description: the labeled tokens
                items:
                  $ref: '#/components/schemas/LabeledToken'
    Summary:
      type: object
      description: the text summary
      required:
        - salience
        - sentences
        - itemsets
        - keywords
      properties:
        salience:
          type: array
          description: the salience distribution in 10 buckets of a fixed interval of 0.1
          items:
            type: number
            format: double
        sentences:
          type: array
          description: the sentences relevance
          items:
            $ref: '#/components/schemas/ScoredText'
        itemsets:
          type: array
          description: the most relevant itemsets with their relevance
          items:
            $ref: '#/components/schemas/ScoredText'
        keywords:
          type: array
          description: the most relevant keywords with their relevance
          items:
            $ref: '#/components/schemas/ScoredKeyword'
    ComparingTexts:
      type: object
      required:
        - text
        - comparing
      properties:
        text:
          type: string
          description: the reference text
        comparing:
          type: array
          description: the comparing texts
          items:
            $ref: '#/components/schemas/InputText'
    ScoredId:
      allOf:
        - $ref: '#/components/schemas/ScoredElement'
        - type: object
          description: an ID that references something
          required:
            - id
          properties:
            id:
              type: integer
              format: int32
    NLPIntent:
      type: object
      required:
        - name
        - slots
        - score
      properties:
        name:
          type: string
        slots:
          type: array
          items:
            $ref: '#/components/schemas/NLPSlot'
        score:
          $ref: '#/components/schemas/Score'
    NLPSlot:
      type: object
      required:
        - name
        - value
        - tokens
      properties:
        name:
          type: string
        value:
          type: string
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/IndexedScore'
    NLPAnalysis:
      type: object
      required:
        - linguisticAnalysis
        - categories
        - locations
        - dateTimes
        - entities
      properties:
        linguisticAnalysis:
          $ref: '#/components/schemas/LinguisticAnalysis'
        categories:
          type: object
          properties:
            iptc:
              $ref: '#/components/schemas/Category'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        dateTimes:
          type: array
          items:
            $ref: '#/components/schemas/DateTimeExpr'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/Entity'
    LinguisticAnalysis:
      type: object
      description: the linguistic analysis of the text, including syntactic, morphological and semantic information
      required:
        - sentences
        - language
      properties:
        sentences:
          type: array
          items:
            $ref: '#/components/schemas/LinguisticSentence'
        language:
          $ref: '#/components/schemas/Language'
    LinguisticSentence:
      allOf:
        - $ref: '#/components/schemas/PositionalElement'
        - type: object
          description: >
            the linguistic analysis of a sentence, including syntactic, morphological and semantic information
          required:
            - id
            - score
            - tokens
          properties:
            id:
              type: integer
              format: int32
              example: 0
            score:
              $ref: '#/components/schemas/Score'
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/LinguisticToken'
    LinguisticToken:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: integer
          format: int32
          example: 0
        type:
          type: string
      discriminator:
        propertyName: type
        mapping:
          WORD: '#/components/schemas/TokenWord'
          TRACE: '#/components/schemas/TokenTrace'
          WORD-TRACE: '#/components/schemas/TokenWordTrace'
          WORD-COMPOSITE: '#/components/schemas/TokenComposite'
    TokenBase:
      type: object
      required:
        - posBase
        - dependency
        - coReferences
        - semanticRelations
        - morphology
      properties:
        posBase:
          $ref: '#/components/schemas/POSBase'
        dependency:
          $ref: '#/components/schemas/Dependency'
        coReferences:
          type: array
          items:
            $ref: '#/components/schemas/CoReference'
        semanticRelations:
          type: array
          items:
            $ref: '#/components/schemas/SemanticRelation'
        morphology:
          type: array
          items:
            $ref: '#/components/schemas/SingleMorphology'
    FormToken:
      type: object
      required:
        - form
        - translitForm
      properties:
        form:
          type: string
        translitForm:
          type: string
    TokenTrace:
      allOf:
        - $ref: '#/components/schemas/LinguisticToken'
        - $ref: '#/components/schemas/TokenBase'
    TokenWordTrace:
      allOf:
        - $ref: '#/components/schemas/LinguisticToken'
        - $ref: '#/components/schemas/TokenBase'
        - $ref: '#/components/schemas/FormToken'
    TokenWord:
      allOf:
        - $ref: '#/components/schemas/LinguisticToken'
        - $ref: '#/components/schemas/TokenBase'
        - $ref: '#/components/schemas/FormToken'
        - $ref: '#/components/schemas/PositionalElement'
    TokenComposite:
      allOf:
        - $ref: '#/components/schemas/LinguisticToken'
        - $ref: '#/components/schemas/FormToken'
        - $ref: '#/components/schemas/PositionalElement'
        - type: object
          required:
            - components
          properties:
            components:
              type: array
              items:
                $ref: '#/components/schemas/TokenWord'
    LanguageObject:
      type: object
      required:
        - id
        - name
      properties:
        id:
          $ref: '#/components/schemas/IsoA2'
        name:
          type: string
          description: the standard English name
          example: English
    IsoA2:
      type: string
      example: en
      pattern: '^[a-z][a-z]$'
      description: the ISO 639-1 code of the language (2 chars)
    ScoredLanguage:
      allOf:
        - $ref: '#/components/schemas/LanguageObject'
        - $ref: '#/components/schemas/ScoredElement'
    Language:
      allOf:
        - $ref: '#/components/schemas/LanguageObject'
        - type: object
          description: the language in which the text has been written
          properties:
            distribution:
              type: array
              description: the distribution of the score among the languages
              items:
                $ref: '#/components/schemas/ScoredLanguage'
    LabeledToken:
      type: object
      description: a labeled token
      required:
        - form
        - iob
        - label
        - score
      properties:
        form:
          type: string
          description: the token form
        iob:
          type: string
          description: the IOB tag of the label
        label:
          type: string
          description: the token label
        score:
          type: number
          format: double
          description: the label score
    Category:
      type: object
      description: a category that indicates the content of the text
      required:
        - id
        - score
      properties:
        id:
          type: integer
          format: int32
          description: the index of the best category within the categories list
          example: 0
        score:
          $ref: '#/components/schemas/Score'
        distribution:
          type: array
          description: the distribution of the score among the possibile categories
          items:
            $ref: '#/components/schemas/Score'
    SingleLocation:
      type: object
      description: a geo-location
      required:
        - id
        - unlocode
        - isoA2
        - type
        - subType
        - name
        - labels
        - translations
        - isCapital
        - demonym
        - area
        - population
        - languages
        - borders
        - altDivisions
        - coords
      properties:
        id:
          type: string
          description: a unique identifier of the location
          example: '250A01D310045'
        unlocode:
          type: string
          description: the UN/LOCODE (United Nations Code for Trade and Transport Locations)
          nullable: true
          example: GBHMP
        isoA2:
          allOf:
            - $ref: '#/components/schemas/IsoA2'
            - type: string
              nullable: true
        type:
          type: string
          description: the hierarchical type
          example: City
          enum:
            - City
            - AdminArea1
            - AdminArea2
            - Country
            - Region
            - Continent
        subType:
          type: string
          description: the sub-type
          nullable: true
          example: town
        name:
          type: string
          description: the common name
          example: London
        labels:
          type: array
          description: all the labels (lower case) with which the location can be named
          items:
            type: string
            example:
              london
        translations:
          type: object
          description: translations of the name associated by lower case language ISO 639-1 code
        isCapital:
          type: boolean
          description: whether this location is the capital city of a country
        demonym:
          type: string
          nullable: true
          description: the demonym
        area:
          type: string
          description: the area in km^2
          nullable: true
        population:
          type: string
          description: the population
          nullable: true
        languages:
          type: array
          description: the spoken languages
          items:
            $ref: '#/components/schemas/IsoA2'
        borders:
          type: array
          description: the border countries
          example:
            - "441A000000000"
            - "4426000000000"
          items:
            type: string
            description: the ID of a country
        altDivisions:
          type: array
          description: alternative administrative divisions of hierarchical super-levels
          items:
            type: object
            required:
              - type
              - name
              - level
            properties:
              type:
                type: string
                description: the division type
                example: County
              name:
                type: string
                description: the division name
                example: County of London
              level:
                type: integer
                format: int32
                description: the hierarchical level of the division
                example: 1
        coords:
          type: object
          description: the geographical coordinates
          nullable: true
          required:
            - lat
            - lon
          properties:
            lat:
              type: number
              format: double
              description: the latitude
              example: 51.5073219
            lon:
              type: number
              format: double
              description: the longitude
              example: -0.1276474
    Location:
      allOf:
        - $ref: '#/components/schemas/SingleLocation'
        - type: object
          required:
            - parents
            - stats
          properties:
            parents:
              type: object
              description: the hierarchical super-levels of the location
              required:
                - adminArea1
                - adminArea2
                - country
                - continent
              properties:
                adminArea1:
                  allOf:
                    - $ref: '#/components/schemas/SingleLocation'
                    - type: object
                      description: the administrative area of level 1 inside which this location is included
                      nullable: true
                adminArea2:
                  allOf:
                    - $ref: '#/components/schemas/SingleLocation'
                    - type: object
                      description: the administrative area of level 2 inside which this location is included
                      nullable: true
                country:
                  allOf:
                    - $ref: '#/components/schemas/SingleLocation'
                    - type: object
                      description: the country inside which this location is included
                      nullable: true
                continent:
                  allOf:
                    - $ref: '#/components/schemas/SingleLocation'
                    - type: object
                      description: the continent inside which this location is included
                      nullable: true
            stats:
              type: object
              required:
                - score
                - confidence
                - countryStrength
              properties:
                score:
                  allOf:
                    - $ref: '#/components/schemas/StatScore'
                    - type: object
                      description: >
                        How much the location is relevant respect to the others in the text.
                        It is a percentage distributed among all the locations found in the text.
                confidence:
                  allOf:
                    - $ref: '#/components/schemas/StatScore'
                    - type: object
                      description: >
                        the confidence that the location is the correct one within the possibile candidates
                        with the same name
                countryStrength:
                  type: number
                  format: double
                  description: >
                    The strength of the country of this location within the text (based on the other locations of the same
                    country).
                    It has a meaning for locations of type 'Country' or locations that are inside a country.
    NumExpr:
      type: object
      description: a numerical expression
      required:
        - value
        - asWord
        - original
        - startToken
        - endToken
        - startChar
        - endChar
      properties:
        value:
          type: number
          description: the numeric value
        asWord:
          type: string
          description: the standard representation of the number in letters
        original:
          type: string
          description: the original string representing the number
        startToken:
          type: integer
          format: int32
          description: the index of the first token of this expression, within the tokens list
        endToken:
          type: integer
          format: int32
          description: the index of the last token of this expression, within the tokens list
        startChar:
          type: integer
          format: int32
          description: the index of the first char of this expression in the original text
        endChar:
          type: integer
          format: int32
          description: the index of the last char of this expression in the original text
    DateTimeExpr:
      type: object
      description: a date-time expression
      required:
        - type
        - startToken
        - endToken
        - startChar
        - endChar
      properties:
        type:
          type: string
        startToken:
          type: integer
          format: int32
          description: the index of the first token of this expression, within the tokens list
        endToken:
          type: integer
          format: int32
          description: the index of the last token of this expression, within the tokens list
        startChar:
          type: integer
          format: int32
          description: the index of the first char of this expression in the original text
        endChar:
          type: integer
          format: int32
          description: the index of the last char of this expression in the original text
      discriminator:
        propertyName: type
        mapping:
          DATE: '#/components/schemas/DateSimple'
          HOLIDAY: '#/components/schemas/Holiday'
          TIME: '#/components/schemas/Time'
          DATE_TIME: '#/components/schemas/DateTimeSimple'
          ORDINAL: '#/components/schemas/DateOrdinal'
          ORDINAL_DATE: '#/components/schemas/DateOrdinalDate'
          OFFSET: '#/components/schemas/Offset'
          OFFSET_DATE: '#/components/schemas/OffsetDate'
          OFFSET_TIME: '#/components/schemas/OffsetTime'
          DATE_OFFSET: '#/components/schemas/DateOffset'
          INTERVAL_OPEN_TO: '#/components/schemas/Interval'
          INTERVAL_OPEN_FROM: '#/components/schemas/Interval'
          INTERVAL_CLOSE: '#/components/schemas/Interval'
    SingleDateTime:
      allOf:
        - $ref: '#/components/schemas/DateTimeExpr'
        - type: object
          description: a single date-time expression
          required:
            - isoFormat
          properties:
            isoFormat:
              type: string
              description: the date-time formatted in 'TZ' ISO format
              format: date-time
              example: '2018-01-13T09:15:00Z'
    DateSimple:
      allOf:
        - $ref: '#/components/schemas/SingleDateTime'
        - type: object
          description: an expression of a date
          properties:
            day:
              type: integer
              format: int32
              description: the number of the day
              minimum: 1
              maximum: 31
              nullable: true
            weekDay:
              type: integer
              format: int32
              description: the number of the week day in the range
              minimum: 1
              maximum: 7
              nullable: true
            month:
              type: integer
              format: int32
              description: the number of the month
              minimum: 1
              maximum: 12
              nullable: true
            year:
              type: integer
              format: int32
              description: the number of the year
              nullable: true
            yearAbbr:
              type: boolean
              description: whether the year is intended as abbreviated form (e.g. '98 stands for 1998)
            yearFull:
              type: integer
              format: int32
              description: >
                The full number of the year.
                In case of abbreviation, from '0 to '50 it becomes 20XX, otherwise 19XX.
              nullable: true
    HolidayEnum:
      type: string
      description: the name of a holiday
      example: CHRISTMAS
      enum:
        - CHRISTMAS
        - CHRISTMAS_EVE
        - EASTER
    Holiday:
      allOf:
        - $ref: '#/components/schemas/SingleDateTime'
        - type: object
          description: an expression of a holiday
          required:
            - holiday
          properties:
            holiday:
              $ref: '#/components/schemas/HolidayEnum'
    GenericMoment:
      type: string
      description: a generic moment of the day
      example: MORNING
      nullable: true
      enum:
        - MORNING
        - NOON
        - AFTERNOON
        - EVENING
        - NIGHT
    Time:
      allOf:
        - $ref: '#/components/schemas/SingleDateTime'
        - type: object
          description: an expression of a time
          properties:
            hour:
              type: integer
              format: int32
              description: the number of the hour
              minimum: 0
              maximum: 23
              nullable: true
            min:
              type: integer
              format: int32
              description: the number of the minute
              minimum: 0
              maximum: 59
              nullable: true
            sec:
              type: integer
              format: int32
              description: the number of the second
              minimum: 0
              maximum: 59
              nullable: true
            millisec:
              type: integer
              format: int32
              description: the number of the millisecond
              minimum: 0
              maximum: 999
              nullable: true
            generic:
              $ref: '#/components/schemas/GenericMoment'
            timezone:
              type: string
              description: the timezone ID
              example: Europe/Rome
    DateTimeSimple:
      allOf:
        - $ref: '#/components/schemas/SingleDateTime'
        - type: object
          description: an expression of a date and a time
          required:
            - date
            - time
          properties:
            date:
              $ref: '#/components/schemas/DateSimple'
            time:
              $ref: '#/components/schemas/Time'
    DateOrdinalUnit:
      type: string
      description: the date unit
      example: DAY
      enum:
        - DATE
        - DAY
        - WEEK
        - WEEKEND
        - MONTH
    DateOrdinal:
      allOf:
        - $ref: '#/components/schemas/SingleDateTime'
        - type: object
          description: an ordinal date
          required:
            - unit
            - position
            - dateTime
            - hasYearReference
          properties:
            unit:
              $ref: '#/components/schemas/DateOrdinalUnit'
            position:
              type: integer
              format: int32
              description: the ordinal position (-1 means 'last')
            dateTime:
              $ref: '#/components/schemas/SingleDateTime'
            hasYearReference:
              type: boolean
              description: >
                whether the reference date-time indicates a whole year (e.g. "the first Monday of the next year")
    DateOrdinalDate:
      allOf:
        - $ref: '#/components/schemas/DateOrdinal'
        - type: object
          description: an ordinal date of date units
          required:
            - value
          properties:
            value:
              $ref: '#/components/schemas/DateSimple'
    OffsetUnitsType:
      type: string
      description: the type of the offset units
      example: QUARTER_HOUR
      enum:
        - DATE
        - TIME
        - HOUR
        - QUARTER_HOUR
        - HALF_HOUR
        - MINUTE
        - SECOND
        - DAY
        - WEEK
        - WEEKEND
        - MONTH
        - YEAR
    Offset:
      allOf:
        - $ref: '#/components/schemas/SingleDateTime'
        - type: object
          description: an offset respect to a reference date or time
          required:
            - units
            - unitsType
          properties:
            units:
              type: integer
              format: int64
              description: the count of the offset units
            unitsType:
              $ref: '#/components/schemas/OffsetUnitsType'
    OffsetDate:
      allOf:
        - $ref: '#/components/schemas/Offset'
        - type: object
          description: an offset of date
          required:
            - value
          properties:
            value:
              $ref: '#/components/schemas/DateSimple'
    OffsetTime:
      allOf:
        - $ref: '#/components/schemas/Offset'
        - type: object
          description: an offset of time
          required:
            - value
          properties:
            value:
              $ref: '#/components/schemas/Time'
    DateOffset:
      allOf:
        - $ref: '#/components/schemas/SingleDateTime'
        - type: object
          description: a date expressed respect to an offset
          required:
            - dateTime
            - offset
          properties:
            dateTime:
              $ref: '#/components/schemas/SingleDateTime'
            offset:
              $ref: '#/components/schemas/Offset'
    Interval:
      allOf:
        - $ref: '#/components/schemas/DateTimeExpr'
        - type: object
          description: an interval of date-times (can be open)
          properties:
            from:
              $ref: '#/components/schemas/DateTimeExpr'
            to:
              $ref: '#/components/schemas/DateTimeExpr'
    Entity:
      type: object
      description: an entity recognized in the text
      required:
        - name
        - type
        - score
        - sentences
      properties:
        name:
          type: string
          example: Albert Einstein
        type:
          type: string
          example: PER
          enum:
            - PER
            - ORG
        score:
          type: number
          format: double
          example: 0.78
        sentences:
          type: array
          items:
            $ref: '#/components/schemas/ScoredSentence'
    Sentence:
      type: object
      description: a sentence with ranges of tokens that represent specific information
      required:
        - id
        - tokens
      properties:
        id:
          type: integer
          format: int32
          description: the sentence id
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/TokensRange'
    ScoredSentence:
      type: object
      description: a sentence with ranges of tokens that represent specific information, with the related system score
      required:
        - id
        - tokens
      properties:
        id:
          type: integer
          format: int32
          description: the sentence id
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/ScoredTokensRange'
    TokensRange:
      type: object
      description: a range of tokens that represent an information extracted from the text
      required:
        - startIndex
        - endIndex
      properties:
        startIndex:
          type: integer
          format: int32
          description: the index of the first token of the range (within the 'tokens' list of the sentence)
          example: 2
        endIndex:
          type: integer
          format: int32
          description: the index of the last token of the range (within the 'tokens' list of the sentence)
          example: 4
    ScoredTokensRange:
      allOf:
        - $ref: '#/components/schemas/TokensRange'
        - $ref: '#/components/schemas/ScoredElement'
    Score:
      type: number
      format: double
      description: the confidence of the system for this element
      example: 0.89
    ScoredElement:
      type: object
      required:
        - score
      properties:
        score:
          $ref: '#/components/schemas/Score'
    ScoredText:
      allOf:
        - $ref: '#/components/schemas/ScoredElement'
        - type: object
          description: a text with a score
          required:
            - text
          properties:
            text:
              type: string
    ScoredKeyword:
      allOf:
        - $ref: '#/components/schemas/ScoredElement'
        - type: object
          description: a keyword with a score
          required:
            - keyword
          properties:
            keyword:
              type: string
    IndexedScore:
      allOf:
        - $ref: '#/components/schemas/ScoredElement'
        - type: object
          required:
            - index
          properties:
            index:
              type: integer
              format: int32
              example: 0
    StatScore:
      type: object
      description: a statistical score, with a value and a deviation
      required:
        - value
        - deviation
      properties:
        value:
          type: number
          format: double
        deviation:
          type: number
          format: double
    Position:
      type: object
      description: the position in the text
      required:
        - index
        - start
        - end
      properties:
        index:
          type: integer
          format: int32
          example: 0
        start:
          type: integer
          format: int32
          example: 0
        end:
          type: integer
          format: int32
          example: 8
    PositionalElement:
      type: object
      required:
        - position
      properties:
        position:
          $ref: '#/components/schemas/Position'
    SingleMorphology:
      oneOf:
        - $ref: '#/components/schemas/BaseMorphology'
        - $ref: '#/components/schemas/NumberMorphology'
    BaseMorphology:
      type: object
      required:
        - oov
        - lemma
        - pos
        - score
      properties:
        oov:
          type: boolean
          description: whether this morphology is Out Of Vocabulary because it has been generated respect to the context
        lemma:
          type: string
        pos:
          $ref: '#/components/schemas/POS'
        score:
          $ref: '#/components/schemas/Score'
    NumberMorphology:
      allOf:
        - $ref: '#/components/schemas/BaseMorphology'
        - type: object
          required:
            - numericForm
          properties:
            numericForm:
              type: number
              description: the number expressed in digits
              example: 123.5
    CoReference:
      type: object
      required:
        - sentenceId
        - tokenId
        - score
      properties:
        sentenceId:
          type: integer
          format: int32
          example: 1
        tokenId:
          type: integer
          format: int32
          example: 5
        score:
          $ref: '#/components/schemas/Score'
    Dependency:
      type: object
      required:
        - head
        - relation
        - attachmentScore
        - relationScore
      properties:
        head:
          type: integer
          format: int32
          example: -1
        relation:
          $ref: '#/components/schemas/SyntacticRelation'
        attachmentScore:
          $ref: '#/components/schemas/Score'
        relationScore:
          $ref: '#/components/schemas/Score'
    POSBase:
      type: string
      enum:
        - ADJ
        - ADV
        - ART
        - CONJ
        - NOUN
        - PRON
        - PREP
        - POSTPOS
        - INTERJ
        - PHRASE
        - PUNCT
        - VERB
        - DATE
        - HOUR
        - NUM
        - PREDET
        - UNKNOWN
    POS:
      type: string
      enum:
        - ADJ
        - ADJ-COMPAR
        - ADJ-DEITT
        - ADJ-DEMONS
        - ADJ-DEMONS-ANTEC
        - ADJ-DEMONS-SUCC
        - ADJ-EXCLAM
        - ADJ-INDEF
        - ADJ-INDEF-SUBORD
        - ADJ-INDEF-DISTR
        - ADJ-INDEF-QUANT
        - ADJ-INTERR
        - ADJ-POSS
        - ADJ-ORDIN
        - ADJ-QUALIF
        - ADJ-QUALIF-POST
        - ADJ-RELAT
        - ADV
        - ADV-ADVERS
        - ADV-COMPAR
        - ADV-CONCESS
        - ADV-DEITT
        - ADV-INDEF
        - ADV-INDEF-SUBORD
        - ADV-INTERR
        - ADV-LIMIT
        - ADV-LOC
        - ADV-NEG
        - ADV-PHRAS
        - ADV-QUANT
        - ADV-STRENG
        - ADV-STRENG-NEG
        - ADV-TIME
        - ART
        - ART-DEF
        - ART-INDEF
        - ART-INDEF-PART
        - CONJ
        - CONJ-COMPAR
        - CONJ-COMPAR-ANTEC
        - CONJ-COMPAR-SUCC
        - CONJ-CONCESS
        - CONJ-COORD
        - CONJ-COORD-ADVERS
        - CONJ-COORD-DISJ
        - CONJ-COORD-EXPLIC
        - CONJ-COORD-NEG
        - CONJ-CORREL
        - CONJ-CORREL-ANTEC
        - CONJ-CORREL-SUCC
        - CONJ-SUBORD
        - CONJ-SUBORD-ADVERS
        - CONJ-SUBORD-INTERR
        - NOUN
        - NOUN-COMMON
        - NOUN-COMMON-GERUND
        - NOUN-COMMON-QUANT
        - NOUN-PROPER
        - NOUN-PROPER-LOC
        - NOUN-PROPER-ORG
        - NOUN-PROPER-PER
        - PRON
        - PRON-DEMONS
        - PRON-EXCLAM
        - PRON-INDEF
        - PRON-INDEF-DISTR
        - PRON-INDEF-QUANT
        - PRON-INDEF-SUBORD
        - PRON-INTERR
        - PRON-ORDIN
        - PRON-PERS
        - PRON-PERS-ENCLIT
        - PRON-PERS-PROCLIT
        - PRON-PERS-PROCLIT-REFL
        - PRON-PERS-PROCLIT-VARIANT
        - PRON-PERS-REFL
        - PRON-PERS-VARIANT
        - PRON-POSS
        - PRON-RELAT
        - PRON-RELAT-DOUBLE
        - PREP
        - PREP-ART
        - PREP-POSS
        - PREP-COMPAR
        - PREDET
        - POSTPOS
        - POSTPOS-POSS
        - PHRASE
        - PHRASE-EXCLAM
        - PHRASE-INTERR
        - PHRASE-NEG
        - VERB
        - VERB-MODAL
        - VERB-AUX
        - INTERJ
        - PUNCT
        - DATE
        - HOUR
        - NUM
        - UNKNOWN
    SyntacticRelation:
      type: string
      enum:
        - TOP
        - INITIATOR
        - SUBJ
        - SUBJ-INTERR
        - SUBJ-PASS
        - OBJ
        - OBJ-INTERR
        - IOBJ
        - IOBJ-INTERR
        - INDCOMPL
        - PREDCOMPL
        - PREDCOMPL-SUBJ
        - PREDCOMPL-OBJ
        - PREDCOMPL-SUBJ-INTERR
        - PREDCOMPL-OBJ-INTERR
        - PREDCOMPL-INTERR
        - RMOD
        - RMOD-EXCLAM
        - RMOD-INTERR
        - RMOD-NEG
        - RMOD-POSS
        - RMOD-COMPAR
        - RMOD-QUANT
        - RMOD2ND
        - RMOD2ND-NEG
        - EXTRAOBJ
        - EXTRASUBJ
        - EMPTYCOMPL
        - LOC
        - PART
        - VOC
        - DET
        - APPOSITION
        - RELCL
        - RELCL-REDUC
        - AUX
        - AUX-TENSE
        - AUX-PASSIVE
        - AUX-PROGRESSIVE
        - COORD
        - COORD-ANTEC
        - COORD-NEG
        - COORD2ND
        - COORD2ND-NEG
        - COORD2ND-ADVERS
        - COORD2ND-COMPAR
        - COORD2ND-CORRELAT
        - COORD2ND-EXPLIC
        - COORD2ND-SYMMETRIC
        - SEPARATOR
        - SEPARATOR-OPEN
        - SEPARATOR-CLOSE
        - QUOTES
        - QUOTES-OPEN
        - QUOTES-CLOSE
        - CONN
        - CONTIN
        - CONTIN-DENOM
        - CONTIN-LOCUT
        - CONTIN-NUM
        - CONTIN-COORD
        - END
        - END-INTERROGATIVE
        - END-ASSERTIVE
        - END-IMPERATIVE
        - INTERJ
        - _
        - UNKNOWN
        - WRONG
    SemanticRelation:
      type: string
      enum:
        - SPACETIME
        - SPACETIME-INTERVAL
        - SPACETIME-START
        - SPACETIME-END
        - TEMP
        - TEMP-START
        - TEMP-END
        - TEMP-PREV
        - TEMP-POST
        - TEMP-PROXIM
        - LOC
        - LOC-IN
        - LOC-DEST
        - LOC-DIST
        - LOC-UP
        - LOC-DOWN
        - LOC-AROUND
        - LOC-SOURCE
        - LOC-PROXIM
        - LOC-CONTACT
        - LOC-SIDE
        - LOC-SIDE-RIGHT
        - LOC-SIDE-LEFT
        - MOV
        - MOV-IN
        - MOV-FROM
        - MOV-TO
        - MOV-TROUGH
        - COMPAR
        - COMPAR-LIMIT
        - COMPAR-ACC
        - COMPAR-EQUAL
        - COMPAR-EQUAL-NEG
        - MANNER
        - MANNER-EQUAL
        - MANNER-UNEQUAL
        - MODAL
        - COND
        - CONC
        - CAUS
        - REASON
        - REASONCAUSE
        - ADVERS
        - LIMIT
        - GOAL
        - EXCEPT
        - EXPLIC
        - THEME
        - PROGRESS
        - UNION
        - DISUNION
        - CONCERNS
        - PARTITIVE
        - SPEC
        - SPEC-DENOM
        - COMPANIONSHIP
        - COMPANIONSHIP-FIG
        - BENEFICIARY
        - BENEFICIARY-DIS
        - MEANS
        - INSTRUMENT
        - MATERIAL
        - FAULT
        - PENALTY
        - REPLACEMENT