openapi: 3.0.1
info:
  title: API4KP Knowledge Base Construction API
  description: |2

    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
  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: 5.0.0
servers:
- url: /omg.org/spec/API4KP/20200801/api/knowledgebase/v5
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:
  /constructors:
    post:
      tags:
      - Compositional
      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
      operationId: constructCompositeAsset
      parameters:
      - 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: |
            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
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: structDefinition
  /constructors/assemblers:
    post:
      tags:
      - Compositional
      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
      operationId: assembleCompositeArtifact
      parameters:
      - 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: |
            A (Composite) KnowledgeCarrier that wraps the Artifacts and/or Surrogates referenced by the input Struct
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: struct
  /constructors/deconstructors:
    post:
      tags:
      - Compositional
      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.
      operationId: deconstructCompositeAsset
      parameters:
      - 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: |
            A struct that defines a Composite Knowledge Asset
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: artifact
  /constructors/disassemblers:
    post:
      tags:
      - Compositional
      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.
      operationId: disassembleCompositeArtifact
      parameters:
      - 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: |
            A collection of wrapped, individual Knowledge Artifacts, which are the Components of the
            input Composite
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: artifact
  /constructors/flatteners:
    post:
      tags:
      - Compositional
      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
      operationId: flattenArtifact
      parameters:
      - name: rootAssetid
        in: query
        description: The id of a root Knowledge Asset in a tree-based composite.
        schema:
          type: string
          format: uuid
      - 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: |
            An atomic, flat Knowledge Artifact
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: artifact
  /knowledgebases:
    post:
      tags:
      - KnowledgeBase
      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.
      operationId: initKnowledgeBase
      parameters:
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/KnowledgeCarrier'
        required: false
      responses:
        200:
          description: A reference to a newly created knowledgebase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
      x-codegen-request-body-name: initialComponent
  /knowledgebases/{kbaseId}:
    get:
      tags:
      - KnowledgeBase
      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.
      operationId: getKnowledgeBaseSeries
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: The knowledgebase
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pointer'
    delete:
      tags:
      - KnowledgeBase
      summary: Deletes Knowledge Base (history)
      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.
      operationId: deleteKnowledgeBase
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: Success
          content: {}
  /knowledgebases/{kbaseId}/versions/{versionTag}:
    get:
      tags:
      - KnowledgeBase
      summary: Get a snapshot of a Knowledge Base
      description: |
        Returns the state of a KnowledgeBase, manifested as a (possibly composite)
        Knowledge Artifact.
      operationId: getKnowledgeBase
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: The knowledgebase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
    post:
      tags:
      - KnowledgeBase
      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.
      operationId: populateKnowledgeBase
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        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 ID of the newly created knowledgebase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
      x-codegen-request-body-name: artifact
    head:
      tags:
      - KnowledgeBase
      summary: Determines if a Knowledge Base is present
      operationId: hasKnowledgeBase
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: The knowledgebase
          content: {}
        404:
          description: Not found
          content: {}
  /knowledgebases/{kbaseId}/versions:
    post:
      tags:
      - KnowledgeBase
      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
      operationId: nextKnowledgeBaseVersion
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: query
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: The next version of the KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
  /knowledgebases/{kbaseId}/versions/{versionTag}/struct:
    get:
      tags:
      - KnowledgeBase
      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
      operationId: getKnowledgeBaseStructure
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            A KnowledgeCarrier carrying the relationship graph
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
    put:
      tags:
      - KnowledgeBase
      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.
      operationId: setKnowledgeBaseStructure
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        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: |
            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.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
        406:
          description: |
            The Structure is expressed in a language/form that cannot be interpreted.
          content: {}
        409:
          description: |
            The Structure is incompatible/inconsistent with the KnowledgeBase Components.
          content: {}
      x-codegen-request-body-name: struct
  /knowledgebases/{kbaseId}/versions/{versionTag}/struct/components:
    get:
      tags:
      - KnowledgeBase
      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
      operationId: getKnowledgeBaseComponents
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            The list of pointers to the KB components
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pointer'
  /knowledgebases/{kbaseId}/versions/{versionTag}/carrier:
    get:
      tags:
      - KnowledgeBase
      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
      operationId: getKnowledgeBaseManifestation
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            A (Composite) KnowledgeCarrier carrying a Manifestation of the KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/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:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/Bindings'
        required: true
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
      x-codegen-request-body-name: bindings
  /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:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        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: true
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
      x-codegen-request-body-name: bindings
  /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:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        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: |
            (A pointer to) the resulting KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
      x-codegen-request-body-name: aspects
  /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:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        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/KnowledgeCarrier'
        required: true
      responses:
        200:
          description: |
            A pointer to the resulting KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
      x-codegen-request-body-name: aspects
  /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:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        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/KnowledgeCarrier'
        required: true
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
      x-codegen-request-body-name: selectDefinition
  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/selectors:
    post:
      tags:
      - KnowledgeBase
      summary: Projects a KnowledgeBase into a proper subset, using a specific operator
      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.
      operationId: select
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        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: |
            (A pointer to) the resulting KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
      x-codegen-request-body-name: selectDefinition
  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/extractors/{operatorId}:
    post:
      tags:
      - KnowledgeBase
      summary: Reshapes a KB to a given subset
      description: |
        Applies an extraction operator, which identifies specific concepts in a KnowledgeBase
        and extracts a focused representation of those concepts
      operationId: namedExtract
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: rootAssetid
        in: query
        description: The id of a root Knowledge Asset in a tree-based composite.
        schema:
          type: string
          format: uuid
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        required: true
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/extractors:
    post:
      tags:
      - KnowledgeBase
      summary: Reshapes a KB to a given subset
      description: |
        Reshapes a KnowledgeBase, deriving a different Structure from the
        existing Structure and/or Components
      operationId: extract
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: rootAssetid
        in: query
        description: The id of a root Knowledge Asset in a tree-based composite.
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/flatteners/{operatorId}:
    post:
      tags:
      - KnowledgeBase
      summary: Flattens a Knowledge Base using a component as a root
      description: |
        Requests that a flatten operation is performed using a specific operator
      operationId: namedFlatten
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        required: true
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: The flat KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/flatteners:
    post:
      tags:
      - KnowledgeBase
      summary: Flattens a Knowledge Base using a component as a root
      operationId: flatten
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/introspectors/{operatorId}:
    post:
      tags:
      - KnowledgeBase
      summary: Derives a metadata surrogate for (the root of) a given knowledgebase
      description: |
        Requests that a introspect operation is performed using a specific operator
      operationId: namedIntrospect
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        required: true
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            The Surrogate Component
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/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:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase, which contains the inferred Surrogate
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
  /knowledgebases/{kbaseId}/versions/{versionTag}/transcreators/transformers/{operatorId}:
    post:
      tags:
      - KnowledgeBase
      summary: Transforms the content of a KnowledgeBase (syntactically and/or semantically)
      description: |
        Requests that a transcreation operation is performed using a specific operator
      operationId: namedTransform
      parameters:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        required: true
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/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:
      - name: kbaseId
        in: path
        description: TODO
        required: true
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: path
        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)."
        required: true
        schema:
          type: string
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            (A pointer to) the resulting KnowledgeBase
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Pointer'
  /transcreators/binders/{operatorId}/kbases:
    post:
      tags:
      - Transcreate
      summary: Bind values to a formula with open variables
      description: |
        Applies a (detached) binding operator
      operationId: applyNamedBind
      parameters:
      - name: kbaseId
        in: query
        description: TODO
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: query
        schema:
          type: string
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        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: true
      responses:
        200:
          description: The Artifact carrying the bound expression
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: bindings
  /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:
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/KnowledgeCarrier'
        required: true
      responses:
        200:
          description: |
            The Artifact carrying the bound expression
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: artifact
  /transcreators/weavers/{operatorId}/kbases:
    post:
      tags:
      - Transcreate
      summary: Weave (fragments of) and artifact into a KB
      description: |
        Applies a (detached) weaving operator
      operationId: applyNamedWeave
      parameters:
      - name: kbaseId
        in: query
        description: TODO
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: query
        schema:
          type: string
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        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/KnowledgeCarrier'
        required: true
      responses:
        200:
          description: |
            The Artifact carrying the woven expression
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: aspects
  /transcreators/weavers/{operatorId}:
    post:
      tags:
      - Transcreate
      summary: Weave (fragments of) and artifact into a KB
      description: |
        Applies a specific (detached) weaving operator
      operationId: applyNamedWeaveDirect
      parameters:
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        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/KnowledgeCarrier'
        required: true
      responses:
        200:
          description: |
            The Artifact carrying the woven expression
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: aspects
  /transcreators/selectors/{operatorId}/kbases:
    post:
      tags:
      - Transcreate
      summary: Projects a KnowledgeBase into a proper subset of content
      description: |
        Applies a (detached) selection operator
      operationId: applyNamedSelect
      parameters:
      - name: kbaseId
        in: query
        description: TODO
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: query
        schema:
          type: string
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        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/KnowledgeCarrier'
        required: true
      responses:
        200:
          description: |
            The Artifact carrying the expression resulting from the selection
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: Definition
  /transcreators/selectors/{operatorId}:
    post:
      tags:
      - Transcreate
      summary: Projects a KnowledgeBase into a proper subset of content
      description: |
        Applies a specific, (detached) selection operator
      operationId: applyNamedSelectDirect
      parameters:
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        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/KnowledgeCarrier'
        required: true
      responses:
        200:
          description: |
            The Artifact carrying the expression resulting from the selection
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: Definition
  /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:
      - name: kbaseId
        in: query
        description: TODO
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: query
        schema:
          type: string
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        required: true
        schema:
          type: string
          format: uuid
      - name: rootAssetid
        in: query
        description: The id of a root Knowledge Asset in a tree-based composite.
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            The Artifact carrying the expression resulting from the extraction
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
  /transcreators/extractors/{operatorId}:
    post:
      tags:
      - Transcreate
      summary: Projects a KnowledgeBase into a proper subset of components
      description: |
        Applies a specific, (detached) extraction operator
      operationId: applyNamedExtractDirect
      parameters:
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        required: true
        schema:
          type: string
          format: uuid
      - name: rootAssetid
        in: query
        description: The id of a root Knowledge Asset in a tree-based composite.
        schema:
          type: string
          format: uuid
      - 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 Artifact carrying the expression resulting from the extraction
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: artifact
  /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:
      - name: kbaseId
        in: query
        description: TODO
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: query
        schema:
          type: string
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        required: true
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            The resulting Surrogate
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/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:
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        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/KnowledgeCarrier'
        required: true
      responses:
        200:
          description: |
            The resulting Surrogate
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: artifact
  /transcreators/transformers/{operatorId}/kbases:
    post:
      tags:
      - Transcreate
      summary: Transforms the content of a KnowledgeBase (syntactically and/or semantically)
      description: |
        Applies a (detached) transcreation operator
      operationId: applyNamedTransform
      parameters:
      - name: kbaseId
        in: query
        description: TODO
        schema:
          type: string
          format: uuid
      - name: versionTag
        in: query
        schema:
          type: string
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        required: true
        schema:
          type: string
          format: uuid
      - name: X-params
        in: header
        description: |
          Additional, operation-specific parameter
        schema:
          type: string
      responses:
        200:
          description: |
            The resulting Artifact
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
  /transcreators/transformers/{operatorId}:
    post:
      tags:
      - Transcreate
      summary: Transforms the content of a KnowledgeBase (syntactically and/or semantically)
      description: |
        Applies a specific, (detached) transcreation operator
      operationId: applyNamedTransformDirect
      parameters:
      - name: operatorId
        in: path
        description: |
          The id of an Operator, implementing one of the operations
          offered by a Component.
        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/KnowledgeCarrier'
        required: true
      responses:
        200:
          description: The resulting Artifact
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/KnowledgeCarrier'
      x-codegen-request-body-name: artifact
components:
  schemas:
    KnowledgeCarrier:
      type: object
    KnowledgeBase:
      type: object
    Bindings:
      type: object
    Pointer:
      type: object
  parameters:
    rootAssetId:
      name: rootAssetid
      in: query
      description: The id of a root Knowledge Asset in a tree-based composite.
      schema:
        type: string
        format: uuid
    assetId:
      name: assetId
      in: path
      description: The id of the Knowledge Asset (Series).
      required: true
      schema:
        type: string
    kbaseId:
      name: kbaseId
      in: path
      description: TODO
      required: true
      schema:
        type: string
        format: uuid
    kbaseIdRef:
      name: kbaseId
      in: query
      description: TODO
      schema:
        type: string
        format: uuid
    versionTagRef:
      name: versionTag
      in: query
      schema:
        type: string
    operatorId:
      name: operatorId
      in: path
      description: |
        The id of an Operator, implementing one of the operations
        offered by a Component.
      required: true
      schema:
        type: string
        format: uuid
    versionTag:
      name: versionTag
      in: path
      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)."
      required: true
      schema:
        type: string
    params:
      name: X-params
      in: header
      description: |
        Additional, operation-specific parameter
      schema:
        type: string
  requestBodies:
    artifact:
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/KnowledgeCarrier'
      required: true
    structDefinition:
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/KnowledgeCarrier'
      required: true
    struct:
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/KnowledgeCarrier'
      required: true