swagger: '2.0'
info:
  version: "1.0.0.Beta"
  title: 'API4KP Knowledge Base Construction API'
  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
  description: |

    The KnowledgeBae APIs enable the transition between Knowledge _at rest_, i.e. Knowledge in the form
    of Artifacts stored in a repository and not yet assembled into a Knowledge Base, and Knowledge
    _in motion_, i.e. Knowledge Bases deployed/paired with a runtime engine/reasoner/execution platform
    that is able to perform computations using that Knowledge.

    The Knowledge Base Construction and Composition APIs allow to compose one or more Knowledge Assets into
    Knowledge Bases that are suitable for processing/reasoning.
    The process, which is driven by metadata (surrogates), involves the retrieval, normalization,
    and structuring of Knowledge Artifacts that manifest the components of the Knowledge Base itself.

    ** Knowledge Base State **
    The Knowledge Base Management API is inspired by the State monad. Knowledge Bases are incubated
    within the server from their initialization, through their construction, until their deployment.
    As operations are applied to manipulate the KB, new versions are constructed ensuring reproducibility and traceabiilty.
    Implementations, however, are not required nor guaranteed to be transactional.

    ** Composition vs Transcreation (Mutation) Operators **
    Composition Operators allw to construct, incrementally, a Knowledge Base starting from known
    named (carriers of) Knowledge Assets.
    Transcreation operators allow to mutate Knowledge Artifacts, usually to create transient
    ephemeral versions which are used to prepare the KnowledgeBase for deployment, but would
    not otherwise be treated as Assets.
    Nevertheless, many Transcreation operations could be useful independently.
    For this reason, Transcreation operators are exposed in two different modalities:

    (i) a detached mode, where the operator is addressed independently and
    (i.a) the client is either responsible for providing the KnowledgeBase as an input, or
    (i.b) the operator is responsible for resolving the IDs provided by the client to a known KnowledgeBase,
    usually by means of delegation to a KnowledgeBase API implementation
    (ii) a connected mode, where an operator is attached to, and exposed in the context of a (client-managed)
    Knowledge Base. That is, the operator is bound to KnowledgeBase(s) at construction time, and is
    then invoked through the KnowledgeBase

    ** Service Boundaries **
    Implementations of KnowledgeBase API are likely to depend on the API4KP Knowledge Trans*ion APIs,
    to provide the necessary lifting/lowering capabilities involved in the processing of Components
    and Structures thereof.
    Implementations of Knowledge Base providers may depend on Knowledge Asset Repository implementations
    for attached operators to resolve Assets required during the processing.
    Implementations of this API are usually paired with API4KP Reasoning APIs, to provide a runtime
    for the constructed KnowledgeBases

    ** Maturity **
    As of this version, this API is considered experimental

tags:

  - name: Compositional
    description: |
      APIs for the manipulation of Composite Assets and Artifacts, including Knowledge Bases
  - name: KnowledgeBase
    description: |
      APIs for the Management of KnowledgeBase State
  - name: Transcreate
    description: |
      APIs that generate KnowledgeBase components via semantic manipulation

paths:



  ##########################################################################################

  #/composers:

  /constructors:
    post:
      tags:
        - Compositional
      operationId: constructCompositeAsset
      summary: 'Constructs a Composite Knowledge Asset'
      description: |
        Creates a new Composite Knowledge Asset (with a new AssetID), which is manifested
        by means of its 'structure'.
        The client is responsible to provide a 'definition', expressed in some query language
        (e.g. SPARQL), which should cover both extensional (i.e. enumerated) and intensional
        (i.e. query proper) ways to select component assets and their relationships.
        The server is expected to run that definition against a substrate, such as a Knowledge
        Asset Repository.
        The server will return a KnowledgeCarrier, wrapping the graph that results from the
        application of the definition with minimal asset metadata (id, version) and information
        on how the graph itself is represented.

        The client can use the structure to assemble a Composite Asset Surrogate, or a Composite
        Artifact, which in turn could be fed to an Introspector to infer an overall Surrogate
        for the composite itself
      parameters:
        - $ref: '#/parameters/structDefinition'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            A knowledge carrier that wraps a Structuring Artifact
            - a (manifestation of a) graph that describes how other Assets are
            organized and related to each other in a Composite Asset
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /constructors/assemblers:
    post:
      tags:
        - Compositional
      operationId: assembleCompositeArtifact
      summary: 'Assembles a Composite Knowledge Artifact'
      description: |
        Interprets a Structure, i.e. the Manifestation of a Structuring Knowledge Asset,
        as the blueprint of a Composite Artifact, as the manifestation of a Composite Knowledge Asset.
        The Structure must specify the identity, version, should specify the relationships,
        and could specify the types and roles of the component Assets.
        This information will be used to retrieve the proper manifestation (Surrogates and/or Carriers)
        of the components, which will be combined and returned as a CompositeKnowledgeCarrier
      parameters:
        - $ref: '#/parameters/struct'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            A (Composite) KnowledgeCarrier that wraps the Artifacts and/or Surrogates referenced by the input Struct
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /constructors/deconstructors:
    post:
      tags:
        - Compositional
      operationId: deconstructCompositeAsset
      summary: 'Deconstructs a Knowledge Artifact into a Composite Knowledge Asset (structure)'
      description: |
        Analyzes a Complex, possibly Composite Knowledge Artifact, identifies its components,
        and returns a Structure that describes those components, and possibly describes their
        types and mutual relationships.
        This operation is not expected to actually return the individual components
        (see disassembleCompositeArtifact). In particular, this operation may be applicable
        even when the actual disassembly is not feasible in practice.
      parameters:
        - $ref: '#/parameters/artifact'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            A struct that defines a Composite Knowledge Asset
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /constructors/disassemblers:
    post:
      tags:
        - Compositional
      operationId: disassembleCompositeArtifact
      summary: 'Deconstructs a (Composite) Knowledge Artifact into its component Artifacts'
      description: |
        Consumes a Composite Knowledge Carrier that wraps a flat Knowledge Artifact
        and a Structure, and follows the Structure blueprint to disassemble the Composite
        into its distinct Components, which are returned separately.

        The two operations assembleCompositeArtifact and disassembleCompositeArtifact
        should be mutually inverse for a given artifact.
      parameters:
        - $ref: '#/parameters/artifact'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            A collection of wrapped, individual Knowledge Artifacts, which are the Components of the
            input Composite
          schema:
            type: array
            items:
              $ref: '#/definitions/KnowledgeCarrier'


  /constructors/flatteners:
    post:
      tags:
        - Compositional
      operationId: flattenArtifact
      summary: 'Flattens a (Composite) Knowledge Artifact'
      description: |
        Constructs a single, flat KnowledgeArtifact from one or more source Artifacts.
        When applied to an Atomic Artifact, returns that Artifact.
        Composite Artifacts are flattened, using the semantics of the representation language.

        The flattening may require to super-impose a topology different than the one supported
        by a Composite. The strategy is left to the implementation, but the client is allowed
        to provide a hint in the form of the identifier of a 'root' component, which could be used
        to extract a tree from a graph, or to linearize a collection
      parameters:
        - $ref: '#/parameters/artifact'
        - $ref: '#/parameters/rootAssetId'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            An atomic, flat Knowledge Artifact
          schema:
            $ref: '#/definitions/KnowledgeCarrier'



  ##########################################################################################

  /knowledgebases:
    post:
      tags:
        - KnowledgeBase
      operationId: initKnowledgeBase
      summary: 'Create empty Knowledge Base'
      description: |
        Creates an empty knowledge base, returning a pointer to the new KB.
        Version tags are used by the server to denote the states of the KB
        at each construction stage.
        Optionally, a client can provide an initial component. If so,
        populateKnowledgeBase will be invoked using that component.
      parameters:
        - name: initialComponent
          in: body
          required: false
          schema:
            $ref: '#/definitions/KnowledgeCarrier'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: A reference to a newly created knowledgebase
          schema:
            $ref: '#/definitions/Pointer'


  /knowledgebases/{kbaseId}:
    get:
      tags:
        - KnowledgeBase
      operationId: getKnowledgeBaseSeries
      summary: 'Get a history of the Knowledge Base'
      description: |
        Returns a trace of the history of a KB's construction process, by means of
        pointers to each state.
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: The knowledgebase
          schema:
            type: array
            items:
              $ref: '#/definitions/Pointer'
    delete:
      tags:
        - KnowledgeBase
      operationId: deleteKnowledgeBase
      summary: 'Deletes Knowledge Base (history)'
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/params'
      description: |
        Removes all the states of a KnowledgeBase from the server
        - usually after the client has obtained a desired snapshot.
        Can be invoked for 'cleanup' purposes.
      responses:
        200:
          description: Success


  /knowledgebases/{kbaseId}/versions/{versionTag}:
    head:
      tags:
        - KnowledgeBase
      operationId: hasKnowledgeBase
      summary: 'Determines if a Knowledge Base is present'
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: The knowledgebase
        404:
          description: Not found

    get:
      tags:
        - KnowledgeBase
      operationId: getKnowledgeBase
      summary: 'Get a snapshot of a Knowledge Base'
      description: |
        Returns the state of a KnowledgeBase, manifested as a (possibly composite)
        Knowledge Artifact.
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: The knowledgebase
          schema:
            $ref: '#/definitions/KnowledgeBase'
    post:
      tags:
        - KnowledgeBase
      operationId: populateKnowledgeBase
      summary: 'Adds a component to a Knowledge Base'
      description: |
        Supports the initial, and subsequent incremental, population of a KnowledgeBase
        through the addition of components, one at a time.
        The server will determine the exact operational nature of the incremental composition,
        depending on the type of assets and languages involved.
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/artifact'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: The ID of the newly created knowledgebase
          schema:
            $ref: '#/definitions/Pointer'

  /knowledgebases/{kbaseId}/versions:
    post:
      tags:
        - KnowledgeBase
      operationId: nextKnowledgeBaseVersion
      summary: 'Increments the version of a Knowledge Base'
      description: |
        Clones a Knowledge Base, setting its version to the next,
        according to a versioning strategy determined by the server
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTagRef'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: The next version of the KnowledgeBase
          schema:
            $ref: '#/definitions/KnowledgeBase'


  /knowledgebases/{kbaseId}/versions/{versionTag}/struct:
    get:
      tags:
        - KnowledgeBase
      operationId: getKnowledgeBaseStructure
      summary: 'Gets the Structure of a Knowledge Base'
      description: |
        Given the id of a Knowledge Base,
        returns a Structure that describes the internal relationships of the KB's components.
        The Structure itself is a Knowledge Artifact, expressed in a suitable language
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            A KnowledgeCarrier carrying the relationship graph
          schema:
            $ref: '#/definitions/KnowledgeCarrier'
    put:
      tags:
        - KnowledgeBase
      operationId: setKnowledgeBaseStructure
      summary: 'Sets the Structure of a Knowledge Base'
      description: |
        Imposes a Structure onto a KnowledgeBase.
        Any existing Structure, if present, will be replaced.
        The new Structure should be consistent with the KnowledgeBase: the Structure should
        reference Components that are or are not prohibited from becoming part of the KnowledgeBase.
        Likewise, the relationships imposed by the should be acceptable and consistent.
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/struct'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            A Pointer to the updated KnowledgeBase. The Pointer must resolve to a KB
            that manifests in the form of a CompositeKnowledgeCarrier whose Structuring Component
            is the Structure provided as an input to this operation.
          schema:
            $ref: '#/definitions/Pointer'
        406:
            description: |
              The Structure is expressed in a language/form that cannot be interpreted.
        409:
            description: |
              The Structure is incompatible/inconsistent with the KnowledgeBase Components.

  /knowledgebases/{kbaseId}/versions/{versionTag}/struct/components:
    get:
      tags:
        - KnowledgeBase
      operationId: getKnowledgeBaseComponents
      summary: 'Gets the Components of a Knowledge Base'
      description: |
        Returns a list of Pointers to the individual Components of a Knowledge Base,
        providing direct access
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            The list of pointers to the KB components
          schema:
            type: array
            items:
              $ref: '#/definitions/Pointer'

  /knowledgebases/{kbaseId}/versions/{versionTag}/carrier:
    get:
      tags:
        - KnowledgeBase
      operationId: getKnowledgeBaseManifestation
      summary: 'Gets (a Carrier of) a Manifestation of a Knowledge Base'
      description: |
        Given a Knowledge Base (or a root asset that is interpreted as the 'seed' of a KB),
        returns a manifestation of the KnowledgeBase, in the form of a (Composite) Knowledge Carrier
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            A (Composite) KnowledgeCarrier carrying a Manifestation of the KnowledgeBase
          schema:
            $ref: '#/definitions/KnowledgeCarrier'



  ###################################################################################################



  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/binders:
    post:
      tags:
        - KnowledgeBase
      summary: 'Bind values to a formula with open variables'
      description: |
        Returns a new version of a KnowledgeBase, which results from the assignment
        of the client-provided values to the corresponding variable fragments in the Artifacts
        that are included in the target KnowledgeBase
      operationId: bind
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - name: bindings
          in: body
          required: true
          schema:
            $ref: '#/definitions/Bindings'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          schema:
            $ref: '#/definitions/Pointer'


  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/binders/{operatorId}:
    post:
      tags:
        - KnowledgeBase
      summary: 'Bind values to a formula with open variables'
      description: |
        Requests that a bind operation is performed using a specific operator
      operationId: namedBind
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/operatorId'
        - name: bindings
          in: body
          required: true
          schema:
            $ref: '#/definitions/Bindings'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          schema:
            $ref: '#/definitions/Pointer'

  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/weavers:
    post:
      tags:
        - KnowledgeBase
      summary: 'Weave (fragments of) an artifact into a KB'
      description: |
        Applies a Weaving operator, such that fragments of a given 'aspects' Artifact
        are extracted and bound to a target Knowledge Base.
      operationId: weave
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - name: aspects
          in: body
          required: true
          schema:
            $ref: '#/definitions/KnowledgeCarrier'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          schema:
            $ref: '#/definitions/Pointer'

  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/weavers/{operatorId}:
    post:
      tags:
        - KnowledgeBase
      summary: 'Weave (fragments of) an artifact into a KB'
      description: |
        Requests that a weave operation is performed using a specific operator
      operationId: namedWeave
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/operatorId'
        - name: aspects
          in: body
          required: true
          schema:
            $ref: '#/definitions/KnowledgeCarrier'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            A pointer to the resulting KnowledgeBase
          schema:
            $ref: '#/definitions/Pointer'

  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/selectors/{operatorId}:
    post:
      tags:
        - KnowledgeBase
      summary: 'Projects a KnowledgeBase into a proper subset'
      description: |
        Requests that a select operation is performed using a specific operator
      operationId: namedSelect
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/operatorId'
        - name: selectDefinition
          in: body
          required: true
          schema:
            $ref: '#/definitions/KnowledgeCarrier'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          schema:
            $ref: '#/definitions/Pointer'

  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/selectors:
    post:
      tags:
        - KnowledgeBase
      summary: 'Projects a KnowledgeBase into a proper subset, using a specific operator'
      operationId: select
      description: |
        Applies a selection operator, which produces a new Knowledge Base
        applying a 'selection' query to an existing KB.
        More specifically, a selection query is a query that extracts existing fragments
        without interpretation nor inference.
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - name: selectDefinition
          in: body
          required: true
          schema:
            $ref: '#/definitions/KnowledgeCarrier'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          schema:
            $ref: '#/definitions/Pointer'



  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/extractors/{operatorId}:
    post:
      tags:
        - KnowledgeBase
      summary: 'Reshapes a KB to a given subset'
      operationId: namedExtract
      description: |
        Applies an extraction operator, which identifies specific concepts in a KnowledgeBase
        and extracts a focused representation of those concepts
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/rootAssetId'
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          schema:
            $ref: '#/definitions/Pointer'

  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/extractors:
    post:
      tags:
        - KnowledgeBase
      summary: 'Reshapes a KB to a given subset'
      operationId: extract
      description: |
        Reshapes a KnowledgeBase, deriving a different Structure from the
        existing Structure and/or Components
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/rootAssetId'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          schema:
            $ref: '#/definitions/Pointer'



  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/flatteners/{operatorId}:
    post:
      tags:
        - KnowledgeBase
      summary: Flattens a Knowledge Base using a component as a root
      operationId: namedFlatten
      description: |
        Requests that a flatten operation is performed using a specific operator
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: The flat KnowledgeBase
          schema:
            $ref: '#/definitions/Pointer'

  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/flatteners:
    post:
      tags:
        - KnowledgeBase
      summary: Flattens a Knowledge Base using a component as a root
      operationId: flatten
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          schema:
            $ref: '#/definitions/Pointer'



  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/introspectors/{operatorId}:
    post:
      tags:
        - KnowledgeBase
      summary: Derives a metadata surrogate for (the root of) a given knowledgebase
      operationId: namedIntrospect
      description: |
        Requests that a introspect operation is performed using a specific operator
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            The Surrogate Component
          schema:
            $ref: '#/definitions/Pointer'

  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/introspectors:
    post:
      tags:
        - KnowledgeBase
      summary: Derives a metadata surrogate for (the root of) a given knowledgebase
      description: |
        Applies introspection operator, which derives a Knowledge Asset Surrogate,
        usually from an Artifact that carries that Asset, and/or related Artifacts,
        and/or other Artifacts that provide context
      operationId: introspect
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase, which contains the inferred Surrogate
          schema:
            $ref: '#/definitions/Pointer'


  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/transformers/{operatorId}:
    post:
      tags:
        - KnowledgeBase
      summary: Transforms the content of a KnowledgeBase (syntactically and/or semantically)
      operationId: namedTransform
      description: |
        Requests that a transcreation operation is performed using a specific operator
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          schema:
            $ref: '#/definitions/Pointer'

  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/transformers:
    post:
      tags:
        - KnowledgeBase
      summary: Transforms the content of a KnowledgeBase (syntactically and/or semantically)
      description: |
        Applies a transcreation operator, which produces a new derivative Artifact, that
        is the Carrier of a new, derivative Asset.
      operationId: transform
      parameters:
        - $ref: '#/parameters/kbaseId'
        - $ref: '#/parameters/versionTag'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          schema:
            $ref: '#/definitions/Pointer'


  #########################################################################

  /transcreators/binders/{operatorId}/kbases:
    post:
      tags:
        - Transcreate
      summary: 'Bind values to a formula with open variables'
      operationId: applyNamedBind
      description: |
        Applies a (detached) binding operator
      parameters:
        - $ref: '#/parameters/kbaseIdRef'
        - $ref: '#/parameters/versionTagRef'
        - $ref: '#/parameters/operatorId'
        - name: bindings
          in: body
          required: true
          schema:
            $ref: '#/definitions/Bindings'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: The Artifact carrying the bound expression
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /transcreators/binders/{operatorId}:
    post:
      tags:
        - Transcreate
      summary: 'Bind values to a formula with open variables'
      description: |
        Applies a specific (detached) binding operator
      operationId: applyNamedBindDirect
      parameters:
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/artifact'
      responses:
        200:
          description: |
            The Artifact carrying the bound expression
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /transcreators/weavers/{operatorId}/kbases:
    post:
      tags:
        - Transcreate
      summary: 'Weave (fragments of) and artifact into a KB'
      operationId: applyNamedWeave
      description: |
        Applies a (detached) weaving operator
      parameters:
        - $ref: '#/parameters/kbaseIdRef'
        - $ref: '#/parameters/versionTagRef'
        - $ref: '#/parameters/operatorId'
        - name: aspects
          in: body
          required: true
          schema:
            $ref: '#/definitions/KnowledgeCarrier'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            The Artifact carrying the woven expression
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /transcreators/weavers/{operatorId}:
    post:
      tags:
        - Transcreate
      summary: 'Weave (fragments of) and artifact into a KB'
      operationId: applyNamedWeaveDirect
      description: |
        Applies a specific (detached) weaving operator
      parameters:
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/artifact'
        - name: aspects
          in: body
          required: true
          schema:
            $ref: '#/definitions/KnowledgeCarrier'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            The Artifact carrying the woven expression
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /transcreators/selectors/{operatorId}/kbases:
    post:
      tags:
        - Transcreate
      summary: 'Projects a KnowledgeBase into a proper subset of content'
      operationId: applyNamedSelect
      description: |
        Applies a (detached) selection operator
      parameters:
        - $ref: '#/parameters/kbaseIdRef'
        - $ref: '#/parameters/versionTagRef'
        - $ref: '#/parameters/operatorId'
        - name: Definition
          in: body
          required: true
          schema:
            $ref: '#/definitions/KnowledgeCarrier'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            The Artifact carrying the expression resulting from the selection
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /transcreators/selectors/{operatorId}:
    post:
      tags:
        - Transcreate
      summary: 'Projects a KnowledgeBase into a proper subset of content'
      operationId: applyNamedSelectDirect
      description: |
        Applies a specific, (detached) selection operator
      parameters:
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/artifact'
        - name: Definition
          in: body
          required: true
          schema:
            $ref: '#/definitions/KnowledgeCarrier'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            The Artifact carrying the expression resulting from the selection
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /transcreators/extractors/{operatorId}/kbases:
    post:
      tags:
        - Transcreate
      summary: 'Projects a KnowledgeBase into a proper subset of components'
      description: |
        Applies a (detached) extraction operator
      operationId: applyNamedExtract
      parameters:
        - $ref: '#/parameters/kbaseIdRef'
        - $ref: '#/parameters/versionTagRef'
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/rootAssetId'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            The Artifact carrying the expression resulting from the extraction
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /transcreators/extractors/{operatorId}:
    post:
      tags:
        - Transcreate
      summary: 'Projects a KnowledgeBase into a proper subset of components'
      operationId: applyNamedExtractDirect
      description: |
        Applies a specific, (detached) extraction operator
      parameters:
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/artifact'
        - $ref: '#/parameters/rootAssetId'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            The Artifact carrying the expression resulting from the extraction
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /transcreators/introspectors/{operatorId}/kbases:
    post:
      tags:
        - Transcreate
      summary: 'Extract a Knowledge Asset Surrogate from a given Knowledge Artifact'
      description: |
        Applies a (detached) introspection operator
      operationId: applyNamedIntrospect
      parameters:
        - $ref: '#/parameters/kbaseIdRef'
        - $ref: '#/parameters/versionTagRef'
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            The resulting Surrogate
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /transcreators/introspectors/{operatorId}:
    post:
      tags:
        - Transcreate
      summary: 'Extract a Knowledge Asset Surrogate from a given Knowledge Artifact'
      description: |
        Applies a specific, (detached) introspection operator
      operationId: applyNamedIntrospectDirect
      parameters:
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/artifact'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            The resulting Surrogate
          schema:
            $ref: '#/definitions/KnowledgeCarrier'


  /transcreators/transformers/{operatorId}/kbases:
    post:
      tags:
        - Transcreate
      summary: Transforms the content of a KnowledgeBase (syntactically and/or semantically)
      operationId: applyNamedTransform
      description: |
        Applies a (detached) transcreation operator
      parameters:
        - $ref: '#/parameters/kbaseIdRef'
        - $ref: '#/parameters/versionTagRef'
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/params'
      responses:
        200:
          description: |
            The resulting Artifact
          schema:
            $ref: '#/definitions/KnowledgeCarrier'

  /transcreators/transformers/{operatorId}:
    post:
      tags:
        - Transcreate
      summary: Transforms the content of a KnowledgeBase (syntactically and/or semantically)
      operationId: applyNamedTransformDirect
      description: |
        Applies a specific, (detached) transcreation operator
      parameters:
        - $ref: '#/parameters/operatorId'
        - $ref: '#/parameters/artifact'
        - $ref: '#/parameters/params'
      responses:
        200:
          description:
            The resulting Artifact
          schema:
            $ref: '#/definitions/KnowledgeCarrier'


  ###################################################################################################




definitions:

  KnowledgeCarrier:
    type: object

  KnowledgeBase:
    type: object

  Bindings:
    type: object

  Pointer:
    type: object

parameters:

  artifact:
    name: artifact
    in: body
    required: true
    schema:
      $ref: '#/definitions/KnowledgeCarrier'

  rootAssetId:
    in: query
    name: rootAssetid
    required: false
    type: string
    format: uuid
    description: "The id of a root Knowledge Asset in a tree-based composite."


  assetId:
    in: path
    name: assetId
    required: true
    type: string
    description: "The id of the Knowledge Asset (Series)."

  kbaseId:
    in: path
    name: kbaseId
    description: TODO
    required: true
    type: string
    format: uuid

  kbaseIdRef:
    in: query
    name: kbaseId
    description: TODO
    required: false
    type: string
    format: uuid

  versionTagRef:
    in: query
    name: versionTag
    required: false
    type: string

  structDefinition:
    name: structDefinition
    in: body
    required: true
    schema:
      $ref: '#/definitions/KnowledgeCarrier'

  struct:
    name: struct
    in: body
    required: true
    schema:
      $ref: '#/definitions/KnowledgeCarrier'

  operatorId:
    in: path
    name: operatorId
    description: |
      The id of an Operator, implementing one of the operations
      offered by a Component.
    required: true
    type: string
    format: uuid

  versionTag:
    in: path
    name: versionTag
    required: true
    type: string
    description: "The version tag of a Versioned Entity. \n Versioned Identifiers identify specific,
    Immutable Versions of Mutable Entities, which reflect the state of that Entity at a given point
    in time. Where a version(ed) identifier is universal, the Tag represents the local part of that
    identifier, under the scope of the identifier that denotes the Entity (series)."

  params:
    in: header
    name: X-params
    description: |
      Additional, operation-specific parameter
    required: false
    type: string

schemes:
  - https
basePath: /omg.org/spec/API4KP/20230201/api/knowledgebase