openapi: 3.0.1
info:
  title: API4KP Knowledge Reasoning API
  description: |2

    APIs that expose the information processing capabilities of Knowledge Platform Components,
    usually known as engines or reasoners, which are able to apply "knowledge" to "data",
    in order to derive new information.

    Knowledge Reasoning APIs are likely to provide an abstraction layer for the proprietary
    API of existing engines, but could also be used to expose engine-less microservices designed
    to work with individual, named knowledge bases.

    The APIs pivot on the notion of Knowledge Base _in motion_, and consider reasoners
    as operators applied to the KBs.
    In this context, Knowledge Bases prepared for Reasoning are also called Knowledge Models,
    or "Models" for short, providing a connection to modern AI implementations.

    The boundary between 'instance data' and 'universal knowledge' is fuzzy, and is abstracted
    once the substrate Knowledge Base is bound to the reasoner. Knowledge Graphs are a primary example.
    Some reasoning operations allow Clients to provide bindings for input variables.

    ** Implementation patterns **
    The binding between the Knowledge Base and the Reasoning service can be implemented in different ways.
    Patterns include, but are not limited to,
    (i) Knowledge Bases deployed within an engine backing the server; (ii) be implemented by the server directly,
    through manual software development or trans-compilation process; (iii) references that can be
    resolved by the server; (iv) support proxy/broker/adapter patterns where the server delegates
    the execution to another service

    ** Service Boundaries **
    Reasoning APIs integrate with KnowledgeBase construction APIs to gather the knowledge,
    and prepare it in a form that can be processed by the engine.
    Reasoning APIs may produce Knowledge Base (components), and KnowledgeBase Construction APIs
    can be used to construct augmented, inferred Knowledge Bases, which can be further processed using
    the Reasoning APIs

    **Maturity**
    As of this version, this API is considered experimental.
    Stateful, Incremental and/or Asynchronous reasoning APIs are not supported in this version
  contact:
    name: Davide Sottara
    email: sottara.davide@mayo.edu
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0.Beta
servers:
- url: /omg.org/spec/API4KP/20230201/api/inference
tags:
- name: Reasoning
  description: |
    Endpoints that expose Reasoning capabilities as synchronous, stateless services
paths:
  /models:
    get:
      tags:
      - Model
      summary: List Models
      description: |
        Lists the Knowledge Bases that are available to this server for reasoning.
      operationId: listModels
      responses:
        200:
          description: |
            A List of pointers to the available Models
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pointer'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pointer'
  /models/{modelId}/versions/{versionTag}:
    get:
      tags:
      - Model
      summary: Describe Model
      description: |
        Return descriptive metadata about a Model.
        This operation may return a Surrogate, including a canonical API4KP
        Surrogate associated to the Knowledge Base, but could also return
        a runtime-oriented Surrogate that describes the Knowledge Base as an executable artifact.
      operationId: getModel
      parameters:
      - name: modelId
        in: path
        description: |
          The Identifier of a known Knowledge Base that is deployed and executed as a Service.
          This identifier SHOULD be an ID of the Asset itself, not of the manifestation of the Asset within the server.
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        description: The Identifier os a specific version of a Model, within the series
          identified by a modelId.
        required: true
        schema:
          type: string
      responses:
        200:
          description: |
            A runtime surrogate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
            application/xml:
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
  /models/{modelId}/versions/{versionTag}/reasoners/inferences:
    post:
      tags:
      - Reasoning
      summary: Derives all logical consequences of a given KB
      description: |
        Derives the necessary, inferred consequences of a given (asserted) Knowledge Base,
        by means of logical derivation.
        The client may optionally provide some input Bindings
      operationId: infer
      parameters:
      - name: modelId
        in: path
        description: |
          The Identifier of a known Knowledge Base that is deployed and executed as a Service.
          This identifier SHOULD be an ID of the Asset itself, not of the manifestation of the Asset within the server.
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        description: The Identifier os a specific version of a Model, within the series
          identified by a modelId.
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Bindings'
        required: false
      responses:
        200:
          description: |
            The inferred axioms
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: features
  /models/{modelId}/versions/{versionTag}/reasoners/inferences/consequents:
    post:
      tags:
      - Reasoning
      summary: Derives inferred features, based on input bindings
      description: |
        Evaluates a 'model' against some user provided 'inputs'.
        Binds the client-provided inputs to the proper Knowledge Base variables,
        performs an inference (see: infer), and returns the values associated
        to some output variables.
      operationId: evaluate
      parameters:
      - name: modelId
        in: path
        description: |
          The Identifier of a known Knowledge Base that is deployed and executed as a Service.
          This identifier SHOULD be an ID of the Asset itself, not of the manifestation of the Asset within the server.
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        description: The Identifier os a specific version of a Model, within the series
          identified by a modelId.
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Bindings'
        required: false
      responses:
        200:
          description: |
            The inferred values for the KB's output variables
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bindings'
      x-codegen-request-body-name: features
  /models/{modelId}/versions/{versionTag}/reasoners/inferences/entailments:
    post:
      tags:
      - Reasoning
      summary: tests whether a set of statements is a logical consequence of a KB
      description: |
        performs an inference using the given Knowledge Base as a substrate, then
        verifies whether the client's provided Knowledge Base Component is a subset
        of the substrate Knowledge Base, and/or its logical consequences.
      operationId: entails
      parameters:
      - name: modelId
        in: path
        description: |
          The Identifier of a known Knowledge Base that is deployed and executed as a Service.
          This identifier SHOULD be an ID of the Asset itself, not of the manifestation of the Asset within the server.
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        description: The Identifier os a specific version of a Model, within the series
          identified by a modelId.
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeCarrier'
        required: true
      responses:
        200:
          description: |
            Whether or not the target KB entails the client provided one
          content:
            application/json:
              schema:
                type: boolean
      x-codegen-request-body-name: potentialConsequence
  /models/{modelId}/versions/{versionTag}/reasoners/queryanswers:
    post:
      tags:
      - Reasoning
      summary: queries the KB, returning bindings to the query's variables
      description: |
        applies the client's provided Query to the target Knowledge Base.
        If the query specifies any output variable, this operation will
        return the inferred bindings for those variables.
      operationId: askQuery
      parameters:
      - name: modelId
        in: path
        description: |
          The Identifier of a known Knowledge Base that is deployed and executed as a Service.
          This identifier SHOULD be an ID of the Asset itself, not of the manifestation of the Asset within the server.
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        description: The Identifier os a specific version of a Model, within the series
          identified by a modelId.
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/KnowledgeCarrier'
        required: true
      responses:
        200:
          description: |
            The bindings of the query variables
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QueryResults'
      x-codegen-request-body-name: query
  /models/{modelId}/versions/{versionTag}/reasoners/checks:
    post:
      tags:
      - Reasoning
      summary: determines whether the KB is internally logically consistent
      description: |
        Determines the consistency of a Knowledge Base, usually by determining
        whether 'false' is a logical consequence of the KB
      operationId: checkConsistency
      parameters:
      - name: modelId
        in: path
        description: |
          The Identifier of a known Knowledge Base that is deployed and executed as a Service.
          This identifier SHOULD be an ID of the Asset itself, not of the manifestation of the Asset within the server.
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        description: The Identifier os a specific version of a Model, within the series
          identified by a modelId.
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            Whether or not the target KB is logically consistent
          content:
            '*/*':
              schema:
                type: boolean
  /models/{modelId}/versions/{versionTag}/reasoners/sats:
    post:
      tags:
      - Reasoning
      summary: determines whether the KB is satisfiable
      description: |
        Determines whether the Knowledge Base is satisfiable, i.e. whether the KB is not inconsistent
        and, if the KB has open variables, there is at least one binding of those variables
        that would result in a KB that is still consistent.
      operationId: checkSatisfiability
      parameters:
      - name: modelId
        in: path
        description: |
          The Identifier of a known Knowledge Base that is deployed and executed as a Service.
          This identifier SHOULD be an ID of the Asset itself, not of the manifestation of the Asset within the server.
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        description: The Identifier os a specific version of a Model, within the series
          identified by a modelId.
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            A list of at least one Binding if the KB is satisfiable, or an empty list if the KB is not.
            Notice that an empty list of Bindings denotes an unsatisfiable KB, while a list with
            Bindings that are empty would denote a trivially satisfiable KB - a KB that is consistent
            and has no free variables.
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bindings'
  /models/{modelId}/versions/{versionTag}/reasoners/classifiers/individuals/{entityId}:
    get:
      tags:
      - Reasoning
      summary: lists all the classes that an individual is member of
      description: |
        Given the id of an individual, and optional features that describe that individual,
        returns all the classes that the individual is a member of, or all the types
        that the individual is an instance of.

        This operation supports both qualitative and quantitative classifications.
      operationId: listMembership
      parameters:
      - name: modelId
        in: path
        description: |
          The Identifier of a known Knowledge Base that is deployed and executed as a Service.
          This identifier SHOULD be an ID of the Asset itself, not of the manifestation of the Asset within the server.
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        description: The Identifier os a specific version of a Model, within the series
          identified by a modelId.
        required: true
        schema:
          type: string
      - name: entityId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/Bindings'
        required: false
      responses:
        200:
          description: |
            References to the class(es) that the individual is a member of
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pointer'
      x-codegen-request-body-name: features
    post:
      tags:
      - Reasoning
      summary: determines if an individual is member of a class
      description: |
        Given the id of an individual, some optional features that describe that individual,
        and the id of a specific class, determines whether the individual is a member of that class
      operationId: checkMembership
      parameters:
      - name: modelId
        in: path
        description: |
          The Identifier of a known Knowledge Base that is deployed and executed as a Service.
          This identifier SHOULD be an ID of the Asset itself, not of the manifestation of the Asset within the server.
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        description: The Identifier os a specific version of a Model, within the series
          identified by a modelId.
        required: true
        schema:
          type: string
      - name: entityId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: classId
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            Whether or not the given individual is a member of the given class
          content:
            '*/*':
              schema:
                type: boolean
  /models/{modelId}/versions/{versionTag}/reasoners/classifiers/classes/{entityId}:
    get:
      tags:
      - Reasoning
      summary: lists all the superclasses of a given Class
      description: |
        Given the identifier of a class, returns all the classes that the given class is a subclass of.
      operationId: listSubsumptions
      parameters:
      - name: modelId
        in: path
        description: |
          The Identifier of a known Knowledge Base that is deployed and executed as a Service.
          This identifier SHOULD be an ID of the Asset itself, not of the manifestation of the Asset within the server.
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        description: The Identifier os a specific version of a Model, within the series
          identified by a modelId.
        required: true
        schema:
          type: string
      - name: entityId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            References to the superclasses of the given class
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pointer'
    post:
      tags:
      - Reasoning
      summary: determines if a Class is a subclass of another class
      description: |
        Given the identifiers of two classes, returns true if and only if the former is a subclass of the latter.
      operationId: checkSubsumption
      parameters:
      - name: modelId
        in: path
        description: |
          The Identifier of a known Knowledge Base that is deployed and executed as a Service.
          This identifier SHOULD be an ID of the Asset itself, not of the manifestation of the Asset within the server.
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        description: The Identifier os a specific version of a Model, within the series
          identified by a modelId.
        required: true
        schema:
          type: string
      - name: entityId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: classId
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            Whether or not the given class (entity) is a subclass of the reference class
          content:
            '*/*':
              schema:
                type: boolean
components:
  schemas:
    Pointer:
      type: object
      description: Compact proxy object that carries references to another Resource.
        This object used in operations that browse and list collections.
    KnowledgeCarrier:
      type: object
      description: A Resource that describes a particular representation of a Knowledge
        Asset.
    Bindings:
      type: object
    QueryResults:
      type: object
  parameters:
    modelId:
      name: modelId
      in: path
      description: |
        The Identifier of a known Knowledge Base that is deployed and executed as a Service.
        This identifier SHOULD be an ID of the Asset itself, not of the manifestation of the Asset within the server.
      required: true
      schema:
        type: string
        format: uuid
    versionTag:
      name: versionTag
      in: path
      description: The Identifier os a specific version of a Model, within the series
        identified by a modelId.
      required: true
      schema:
        type: string
    entityId:
      name: entityId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    classId:
      name: classId
      in: query
      required: true
      schema:
        type: string
        format: uuid
    lambdaId:
      name: lambdaId
      in: path
      description: TODO
      required: true
      schema:
        type: string
        format: uuid
    xAccept:
      name: xAccept
      in: query
      description: |
        A formal MIME type used for content negotiation
      schema:
        type: string
    params:
      name: X-params
      in: header
      description: |
        Additional, operation-specific parameter
      schema:
        type: string
  requestBodies:
    features:
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Bindings'
      required: false
    sourceArtifact:
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/KnowledgeCarrier'
      required: true