FOLIO Custom API

openapi: 3.2.0
info:
  title: Folio Custom API
  version: v1
  description: 'Operations tagged custom across 2 of this provider''s published API definitions: folio-folio-query-tool-metadata-querytool-openapi.json, folio-folio-query-tool-metadata-querytool-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://folio-etesting-snapshot-kong.ci.folio.org/
tags:
- name: Custom
paths:
  /entity-types/custom:
    post:
      operationId: createCustomEntityType
      tags:
      - Custom
      description: Create a custom entity type
      requestBody:
        description: Custom entity type definition
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customEntityType'
      responses:
        '201':
          description: Created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customEntityType'
          headers:
            Location:
              schema:
                type: string
                format: url
              description: The URL of the newly created custom entity type
              example: /entity-types/custom/6087a09b-8b34-4e6c-8173-c0c5f0f45e7a
        4XX:
          $ref: '#/components/responses/badRequestResponse'
      summary: Create custom entity type
      x-summary-source: derived
    servers:
    - url: https://folio-etesting-snapshot-kong.ci.folio.org/
  /entity-types/custom/{entityTypeId}:
    get:
      operationId: getCustomEntityType
      tags:
      - Custom
      parameters:
      - $ref: '#/components/parameters/entityTypeId'
      responses:
        '200':
          description: Definition of the requested custom entity type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customEntityType'
        4XX:
          $ref: '#/components/responses/badRequestResponse'
      summary: Get custom entity type
      x-summary-source: derived
    put:
      operationId: updateCustomEntityType
      tags:
      - Custom
      parameters:
      - $ref: '#/components/parameters/entityTypeId'
      requestBody:
        description: Custom entity type definition
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customEntityType'
      responses:
        '200':
          description: Definition of the requested custom entity type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customEntityType'
        4XX:
          $ref: '#/components/responses/badRequestResponse'
      summary: Update custom entity type
      x-summary-source: derived
    delete:
      operationId: deleteCustomEntityType
      tags:
      - Custom
      parameters:
      - $ref: '#/components/parameters/entityTypeId'
      responses:
        '204':
          description: Custom entity type has been deleted
        4XX:
          $ref: '#/components/responses/badRequestResponse'
      summary: Delete custom entity type
      x-summary-source: derived
    servers:
    - url: https://folio-etesting-snapshot-kong.ci.folio.org/
  /entity-types/custom/available-joins:
    post:
      operationId: getAvailableJoins
      tags:
      - Custom
      description: Get available entity types and fields for joining with a custom entity type
      requestBody:
        description: Custom entity type definition
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvailableJoinsRequest'
      responses:
        '200':
          description: Available entity types and fields for joining
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableJoinsResponse'
        4XX:
          $ref: '#/components/responses/badRequestResponse'
      summary: Get available joins
      x-summary-source: derived
    servers:
    - url: https://folio-etesting-snapshot-kong.ci.folio.org/
components:
  schemas:
    parameter:
      description: List of key/value parameters of an error
      type: object
      properties:
        key:
          description: Parameter key
          type: string
        value:
          description: Parameter value
          type: string
      additionalProperties: false
      required:
      - key
    id:
      description: A UUID identifying entity type
      type: string
    UUID:
      description: The content row represented as a map.
      type: string
      format: uuid
    AvailableJoinsResponse:
      properties:
        availableTargetIds:
          description: Available target entity types that can be joined with the custom entity type
          type: array
          items:
            $ref: '#/components/schemas/LabeledValueWithDescription'
        availableJoinConditions:
          description: Available join conditions between the source and target entity types, as a pair of source and target field values
          type: array
          items:
            $ref: '#/components/schemas/JoinFieldPair'
    sourceColumn:
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Source of an entity type column
      description: Source of an entity type column, from where the values for the column can be derived
      type: object
      properties:
        entityTypeId:
          description: A UUID identifying the source entity type
          type: string
          format: uuid
        type:
          description: 'Name of the source type. Possible values: entity-type, fqm. Default: entity-type'
          type: string
          default: entity-type
          enum:
          - entity-type
          - fqm
        name:
          description: Name of the source within the source type (e.g., 'currency')
          type: string
        columnName:
          description: Name of the source column
          type: string
      required:
      - entityTypeId
      - columnName
    parameters:
      description: List of key/value parameters of an error
      type: array
      items:
        $ref: '#/components/schemas/parameter'
    valueWithLabel:
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Column value with label Schema
      description: A value with a label
      type: object
      properties:
        value:
          description: The actual value that will be used in the query
          type: string
        label:
          description: The user-friendly name used in dropdowns, etc. If the label is not provided the value will be used instead.
          type: string
      required:
      - value
    customEntityType:
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Custom Entity Type Schema
      description: A definition of a custom entity types that can be used in the Query Tool
      type: object
      allOf:
      - $ref: '#/components/schemas/EntityType'
        required: []
      - properties:
          id:
            $ref: '#/components/schemas/id'
          _version:
            description: FQL query version, used for migrations
            type: string
          name:
            $ref: '#/components/schemas/description'
          private:
            $ref: '#/components/schemas/private'
          owner:
            description: A UUID identifying entity type owner
            type: string
            format: uuid
          shared:
            description: Denotes if the entity type is shared (true) or private (false)
            type: boolean
            default: false
          createdAt:
            description: The creation timestamp of the entity type
            type: string
            format: date-time
          updatedAt:
            description: The update timestamp of the entity type
            type: string
            format: date-time
          isCustom:
            description: Discriminator field to distinguish custom entity types from system entity types
            type: boolean
            default: true
            const: true
    entityTypeSource:
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Entity Type Source
      description: Definition for an entity type source, which provide a set of fields and can be joined with other sources
      allOf:
      - type: object
        discriminator:
          propertyName: type
          mapping:
            db: '#/components/schemas/entityTypeSourceDatabase'
            entity-type: '#/components/schemas/entityTypeSourceEntityType'
        properties:
          type:
            description: Type of source. Valid values are db, entity-type
            type: string
          alias:
            description: Alias of this source to be used in query/later joins
            type: string
          name:
            description: Name of this source. If set, this will override any source name translations
            type: string
          joinedViaEntityType:
            description: '[Internal use only, should not be included in definitions] The owning entity''s alias, if this source''s joining is handled by a parent entity in a cross-entity join'
            type: string
          order:
            description: Order of the inherited fields from this source, relative to the fields from other sources. Defaults to 1073741823 (INT_MAX/2)
            type: integer
        required:
        - type
        - alias
    LabeledValue:
      properties:
        label:
          type: string
          description: Human-readable label
        value:
          type: string
      required:
      - id
      - label
    description:
      description: A description of the entity type
      type: string
    EntityDataType:
      type: object
      properties:
        dataType:
          type: string
      required:
      - dataType
      discriminator:
        propertyName: dataType
    private:
      description: This flag denotes whether the entity type is private or not. Private entity types cannot be accessed by users for querying.
      type: boolean
    LabeledValueWithDescription:
      allOf:
      - $ref: '#/components/schemas/LabeledValue'
      - properties:
          description:
            type: string
            description: Description of the value
        required: []
    joinDirection:
      $schema: https://json-schema.org/draft/2020-12/schema
      description: Direction of the join, from the perspective of :this JOIN :target (e.g. inner, left, right)
      type: string
      enum:
      - inner
      - left
      - right
      - full
    EntityType:
      type: object
      properties:
        id:
          description: A UUID identifying entity type
          type: string
        name:
          description: The unique name of entity type like User, Loan, Item, etc.
          type: string
        description:
          description: A description of the entity type
          type: string
        labelAlias:
          description: The identifier used for a localized label/name for this entity.
          type: string
        private:
          description: This flag denotes whether the entity type is private or not. Private entity types cannot be accessed by users for querying.
          type: boolean
        columns:
          type: array
          items:
            $ref: '#/components/schemas/entityTypeColumn'
          default: []
        crossTenantQueriesEnabled:
          description: Indicates if this entity type supports cross-tenant queries
          type: boolean
          default: false
        defaultSort:
          type: array
          items:
            $ref: '#/components/schemas/entityTypeDefaultSort'
        groupByFields:
          description: Ordered list of fields used in the GROUP BY clause for this entity type
          type: array
          items:
            type: string
        sources:
          type: array
          items:
            $ref: '#/components/schemas/entityTypeSource'
          default: []
        requiredPermissions:
          description: List of permissions required to query this entity type
          type: array
          items:
            type: string
          default: []
        filterConditions:
          description: Filter conditions to be included in the WHERE clause of this entity type
          type: array
          items:
            type: string
          default: []
        additionalEcsConditions:
          description: Additional conditions to be included in the WHERE clause of this entity type in ECS environments
          type: array
          items:
            type: string
          default: []
        deleted:
          description: Indicates if this entity type is deleted
          type: boolean
          default: false
        usedBy:
          description: List of modules that use this entity type
          type: array
          items:
            type: string
          default: []
      required:
      - id
      - name
      - private
      additionalProperties: true
    entityTypeDefaultSort:
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Default sort criteria for an entity type
      description: A definition of default sort criteria for an entity type
      type: object
      properties:
        columnName:
          description: Name of the column using which entity type has to be sorted
          type: string
        direction:
          description: Direction of the sort (Ascending or Descending)
          type: string
          enum:
          - ASC
          - DESC
      required:
      - columnName
      - direction
    entityTypeSourceEntityType:
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Entity Type — Entity Type Source
      description: Definition for an entity type source referring to another entity type
      allOf:
      - $ref: '#/components/schemas/entityTypeSource'
      - type: object
        properties:
          sourceField:
            description: If joining, fully qualified field of the source entity type that targetId/targetField will join to
            type: string
          targetId:
            description: ID of the entity type newly included with this source
            type: string
            format: uuid
          targetField:
            description: If joining, field of the new entity type that will be joined to the source entity type
            type: string
          overrideJoinDirection:
            $ref: '#/components/schemas/joinDirection'
          cascadeJoinDirection:
            description: When true and this source is itself an entity-type LEFT-joined upstream, the overrideJoinDirection of this source is propagated into the joins of its inner sub-sources during flattening. Use this on outer-composite -> inner-composite LEFT joins to preserve upstream rows that would otherwise be dropped by a RIGHT JOIN emitted for an inner table.
            type: boolean
            default: false
          useIdColumns:
            description: Whether to use the idColumns of this source as idColumns for the enclosing entity type
            type: boolean
          essentialOnly:
            description: Indicates that only critical columns for core functionality should be inherited, excluding non-essential columns
            type: boolean
          inheritCustomFields:
            description: Whether to inherit custom fields from this source. If false, only core fields will be inherited.
            type: boolean
            default: true
          additionalJoinCondition:
            description: Filter condition to be included in the ON clause of the JOIN for entity type as SQL. This will be ANDed with the generated JOIN condition.
            type: string
        required:
        - targetId
    entityTypeColumn:
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Entity Type Column Schema
      description: A definition of the entity type column
      allOf:
      - $ref: '#/components/schemas/field'
      - type: object
        properties:
          visibleByDefault:
            description: Indicates if the column should be shown by default when the entity is viewed.
            type: boolean
          isCustomField:
            description: Indicates if the column belongs to the custom field.
            type: boolean
          isIdColumn:
            description: Indicates if the column is part of the unique identifier for this entity type
            type: boolean
          sourceAlias:
            description: Source alias for this column
            type: string
          essential:
            description: Indicates if a column is crucial to the definition of an entity type
            type: boolean
          joinsTo:
            description: A set of columns which this column may be joined to
            type: array
            items:
              $ref: '#/components/schemas/join'
            default: []
          originalEntityTypeId:
            description: '[Internal only, not for definitions] The simplest entity type that this column is derived from'
            type: string
            format: uuid
          maxColumnWidth:
            description: The maximum width of the column when displayed in the UI
            type: integer
        required: []
    JoinFieldPair:
      properties:
        sourceField:
          $ref: '#/components/schemas/LabeledValue'
        targetField:
          $ref: '#/components/schemas/LabeledValue'
      required:
      - sourceField
      - targetField
    join:
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Definition of a possible field join
      description: A listing of a way for a field to join to another
      allOf:
      - type: object
        discriminator:
          propertyName: type
          mapping:
            custom: '#/components/schemas/joinCustom'
            equality-simple: '#/components/schemas/joinEqualitySimple'
            equality-cast-uuid: '#/components/schemas/joinEqualityCastUUID'
        properties:
          targetId:
            description: The ID of the target entity type
            type: string
            format: uuid
          targetField:
            description: The field on the target entity type
            type: string
          type:
            description: Type of join expression (e.g. custom, equality-simple, equality-cast-uuid)
            type: string
          direction:
            $ref: '#/components/schemas/joinDirection'
        required:
        - targetId
        - targetField
        - type
    error:
      description: An error
      type: object
      properties:
        message:
          type: string
          description: Error message text
        code:
          type: string
          description: Error message code; see implementing module's API documentation for possible values
        parameters:
          description: Error message parameters
          $ref: '#/components/schemas/parameters'
      additionalProperties: false
      required:
      - message
      - code
    AvailableJoinsRequest:
      type: object
      properties:
        sources:
          type: array
          items:
            $ref: '#/components/schemas/entityTypeSourceEntityType'
        targetId:
          description: UUID of the target entity type
          $ref: '#/components/schemas/UUID'
    field:
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Source/query column details
      description: Properties for sourcing/querying a column or nested property
      type: object
      properties:
        name:
          description: The name of this field.
          type: string
        dataType:
          description: The data type for this field.
          $ref: '#/components/schemas/EntityDataType'
        labelAlias:
          description: A pre-localized identifier used to label/name this column.
          type: string
        queryable:
          description: Indicates whether this column can be used in a query.
          type: boolean
        queryOnly:
          description: Indicates whether this column can be used for querying only. If true, the column can be used in a query but cannot be included in results.
          type: boolean
        source:
          description: Reference to the root entity type column, from where the values of this column are sourced.
          $ref: '#/components/schemas/sourceColumn'
        valueSourceApi:
          description: Configuration defining where the available values for a column can be accessed
          $ref: '#/components/schemas/valueSourceApi'
        valueGetter:
          description: Configuration defining how to fetch values of this column from the underlying datasource.
          type: string
        filterValueGetter:
          description: Configuration defining how to filter values of this column from the underlying datasource when indexed values aren't very user-friendly.
          type: string
        idColumnName:
          description: Name of the corresponding ID column, if this column contains the value of an ID.
          type: string
        valueFunction:
          description: Configuration defining how to transform a static value for comparison with values produced by the filterValueGetter. This is useful when the filterValueGetter does extra processing that is not visible to the user. The static value can be referenced with ':value'
          type: string
        hidden:
          description: Indicates if the field is hidden in UI
          type: boolean
          default: false
        values:
          type: array
          description: Array of values for this column
          items:
            $ref: '#/components/schemas/valueWithLabel'
        ecsOnly:
          description: Indicates if the field is available only in ECS environments
          type: boolean
        validated:
          description: Indicates if the field values are validated against a predefined format or set of values
          type: boolean
          default: false
        localizeForExports:
          description: Indicates if the field values should be localized when exported (e.g., translating enum values or formatted values for exports)
          type: boolean
          default: false
        defaultValue:
          description: Default value for this field if none is provided
        availableOperators:
          description: The operators available for this field when building queries. When set, this overrides the default operator set for the data type. When absent, the default operators for the data type are used.
          type: array
          items:
            type: string
      required:
      - name
      - dataType
    valueSourceApi:
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Value source API config
      description: Configuration for a column's value source API, where the available values can be accessed
      type: object
      properties:
        path:
          description: 'Relative path to the FOLIO module API endpoint that can provide the available column values. Example: ''material-types'''
          type: string
        valueJsonPath:
          description: JsonPath defining how to access the values provided by the API
          type: string
        labelJsonPath:
          description: JsonPath defining how to access the labels for the values provided by the API
          type: string
        queryParams:
          description: Map of query parameters to be passed to API endpoint
          type: object
          additionalProperties:
            type: string
      required:
      - path
      - valueJsonPath
      - labelJsonPath
  responses:
    badRequestResponse:
      description: Invalid request
      content:
        application/json:
          example:
            message: Entity type ID 6c611396-b6bc-56a7-aada-3a90683d559c was not found
            code: entity.type.not.found
          schema:
            $ref: '#/components/schemas/error'
  parameters:
    entityTypeId:
      name: entityTypeId
      in: path
      required: true
      description: UUID of the entity type
      schema:
        $ref: '#/components/schemas/UUID'
x-refined-from:
- folio-folio-query-tool-metadata-querytool-openapi.json
- folio-folio-query-tool-metadata-querytool-openapi.yml