openapi: 3.2.0
info:
  title: Folio Records Editor API
  version: '6.0'
  contact:
    name: FOLIO
  description: 'Operations tagged records-editor across 2 of this provider''s published API definitions: folio-mod-quick-marc-records-editor-openapi.json, folio-mod-quick-marc-records-editor-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://folio-edev-spitfire-diku.ci.folio.org
  description: Development environment.
- url: https://folio-etesting-{environment}.ci.folio.org
  description: Reference environments.
  variables:
    environment:
      default: snapshot-diku
      enum:
      - snapshot-diku
      - sprint-fs09000000
tags:
- name: records-editor
  description: Operations for managing MARC records
paths:
  /records-editor/records:
    get:
      tags:
      - records-editor
      summary: Get MARC record by external ID
      description: Retrieves a MARC record associated with the provided external entity UUID
      operationId: getRecordByExternalId
      parameters:
      - name: externalId
        in: query
        required: true
        description: UUID of the external entity that is related to the MARC record
        schema:
          type: string
          format: uuid
        example: b9a5f035-de63-4e2c-92c2-07240c89b817
      responses:
        '200':
          description: MARC record successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/quickMarcView'
              example:
                parsedRecordId: c9db5d7a-e1d4-11e8-9f32-f2801f1b9fd1
                parsedRecordDtoId: c56b70ce-4ef6-47ef-8bc3-c470bafa0b8c
                externalId: b9a5f035-de63-4e2c-92c2-07240c89b817
                externalHrid: in00000000001
                marcFormat: BIBLIOGRAPHIC
                leader: 01587ccm a2200361   4500
                fields:
                - tag: '100'
                  content:
                    $a: Mozart, Wolfgang Amadeus,
                    $d: 1756-1791.
                  indicators:
                  - '1'
                  - ' '
                - tag: '245'
                  content:
                    $a: Test Title
                  indicators:
                  - '1'
                  - '0'
        '400':
          description: Bad request, e.g. malformed request body or query parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: MARC record with the given external ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    post:
      tags:
      - records-editor
      summary: Create new MARC record
      description: Creates a new MARC record with the provided data
      operationId: createNewRecord
      requestBody:
        required: true
        description: MARC record data to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/quickMarcCreate'
      responses:
        '201':
          description: MARC record successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/quickMarcView'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: Unprocessable Entity - MARC record validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validationResult'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    servers:
    - url: https://folio-edev-spitfire-diku.ci.folio.org
      description: Development environment.
    - url: https://folio-etesting-{environment}.ci.folio.org
      description: Reference environments.
      variables:
        environment:
          default: snapshot-diku
          enum:
          - snapshot-diku
          - sprint-fs09000000
  /records-editor/records/{id}:
    put:
      tags:
      - records-editor
      summary: Update MARC record
      description: Updates an existing MARC record with the provided data
      operationId: updateRecord
      parameters:
      - name: id
        in: path
        required: true
        description: The UUID of the MARC record
        schema:
          type: string
          format: uuid
        example: c9db5d7a-e1d4-11e8-9f32-f2801f1b9fd1
      requestBody:
        required: true
        description: MARC record data to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/quickMarcEdit'
      responses:
        '202':
          description: MARC record accepted for updating
        '400':
          description: Bad request, e.g. malformed request body or query parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '409':
          description: Conflict - Update failed due to optimistic locking
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: Unprocessable Entity - MARC record validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validationResult'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    servers:
    - url: https://folio-edev-spitfire-diku.ci.folio.org
      description: Development environment.
    - url: https://folio-etesting-{environment}.ci.folio.org
      description: Reference environments.
      variables:
        environment:
          default: snapshot-diku
          enum:
          - snapshot-diku
          - sprint-fs09000000
  /records-editor/links/suggestion:
    post:
      tags:
      - records-editor
      summary: Suggest links for MARC record
      description: Analyzes MARC record and suggests authority links based on the specified search parameter
      operationId: suggestLinks
      parameters:
      - name: authoritySearchParameter
        in: query
        required: false
        description: Authority field to search by
        schema:
          $ref: '#/components/schemas/authoritySearchParameter'
      - name: ignoreAutoLinkingEnabled
        in: query
        required: false
        description: Indicates if we need to ignore autoLinkingEnabled flag when filtering the fields for suggestions
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        description: MARC record to analyze for link suggestions
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/quickMarcView'
      responses:
        '201':
          description: Link suggestions successfully generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/quickMarcView'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    servers:
    - url: https://folio-edev-spitfire-diku.ci.folio.org
      description: Development environment.
    - url: https://folio-etesting-{environment}.ci.folio.org
      description: Reference environments.
      variables:
        environment:
          default: snapshot-diku
          enum:
          - snapshot-diku
          - sprint-fs09000000
  /records-editor/validate:
    post:
      tags:
      - records-editor
      summary: Validate MARC record
      description: Validates a MARC record against defined rules and specifications
      operationId: validateRecord
      requestBody:
        required: true
        description: MARC record data to validate
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/validatableRecord'
      responses:
        '200':
          description: MARC record validation completed (may contain validation issues)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validationResult'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    servers:
    - url: https://folio-edev-spitfire-diku.ci.folio.org
      description: Development environment.
    - url: https://folio-etesting-{environment}.ci.folio.org
      description: Reference environments.
      variables:
        environment:
          default: snapshot-diku
          enum:
          - snapshot-diku
          - sprint-fs09000000
components:
  schemas:
    userInfo:
      type: object
      description: User Display Information
      properties:
        userId:
          description: ID of the user
          type: string
          format: uuid
          readOnly: true
        username:
          description: Username of the user
          type: string
          readOnly: true
        lastName:
          type: string
          readOnly: true
          description: Last name of the user
        firstName:
          type: string
          readOnly: true
          description: First name of the user
        middleName:
          type: string
          readOnly: true
          description: Middle name or initial of the user
      example:
        userId: c56b70ce-4ef6-47ef-8bc3-c470bafa0b8c
        username: john-doe
        lastName: Doe
        firstName: John
        middleName: X.
    validationResult:
      type: object
      description: Collection of validation issues found during MARC record validation
      properties:
        issues:
          description: List of issues
          type: array
          items:
            $ref: '#/components/schemas/validationIssue'
    validationIssue:
      type: object
      description: Details of a validation issue found in a MARC record
      properties:
        tag:
          description: Associated tag for the issue identified
          type: string
        severity:
          description: Level of impact of the discovered issue
          type: string
        definitionType:
          description: Type of definition flagged during validation
          type: string
        helpUrl:
          description: Help URL that is defined in the definition
          type: string
        message:
          description: A concise summary of the identified issue
          type: string
    fieldItem:
      description: MARC field structure containing tag, content, and optional indicators
      type: object
      properties:
        tag:
          description: Field's tag
          type: string
          pattern: ^[0-9]{3}$
          example: '001'
        content:
          description: Field's content (string for control fields, object with subfields for data fields)
          type: object
          example:
            $a: '393893'
            $b: Mike
        indicators:
          description: Field's indicators
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 1
          minItems: 0
          maxItems: 2
        isProtected:
          description: Flag indicates if the field data is protected
          type: boolean
          readOnly: true
          example: true
        linkDetails:
          $ref: '#/components/schemas/linkDetails'
      required:
      - tag
      - content
      example:
        tag: '100'
        content:
          $a: '393893'
          $b: Mike
        indicators:
        - '1'
        - '2'
        isProtected: true
    validatableRecord:
      type: object
      description: Validatable MARC Record
      properties:
        leader:
          type: string
          description: MARC record's leader
        fields:
          description: MARC record's fields
          type: array
          items:
            type: object
            properties:
              tag:
                description: Field's tag
                type: string
              content:
                description: Field's content
                type: object
              indicators:
                description: Field's indicators
                type: array
                items:
                  type: string
        marcFormat:
          $ref: '#/components/schemas/marcFormat'
      required:
      - marcFormat
    baseMarcRecord:
      type: object
      title: Base MARC record for QuickMARC
      description: Common properties for all MARC record types in QuickMARC
      properties:
        leader:
          type: string
          description: MARC record's leader
        fields:
          description: MARC record's fields
          type: array
          items:
            $ref: '#/components/schemas/fieldItem'
        suppressDiscovery:
          type: boolean
          default: false
          description: Flag indicates if the record is displayed during a search
        marcFormat:
          $ref: '#/components/schemas/marcFormat'
        sourceVersion:
          type: integer
          description: Version of the source record
          default: -1
          example: 1
      required:
      - marcFormat
      - leader
      - fields
    marcFormat:
      type: string
      description: MARC Format
      enum:
      - BIBLIOGRAPHIC
      - HOLDINGS
      - AUTHORITY
    quickMarcEdit:
      type: object
      description: MARC record edit model with required identifiers
      x-implements:
      - org.folio.qm.domain.model.BaseQuickMarcRecord
      allOf:
      - $ref: '#/components/schemas/baseMarcRecord'
      - type: object
        properties:
          parsedRecordId:
            description: MARC record Id
            type: string
            format: uuid
          parsedRecordDtoId:
            description: ParsedRecordDto identifier
            type: string
            format: uuid
          externalId:
            description: Identifier of external entity
            type: string
            format: uuid
          externalHrid:
            description: HRID of external entity
            type: string
        required:
        - parsedRecordId
        - parsedRecordDtoId
        - externalId
        - externalHrid
    quickMarcView:
      type: object
      description: MARC record view model with read-only metadata
      x-implements:
      - org.folio.qm.domain.model.BaseQuickMarcRecord
      allOf:
      - $ref: '#/components/schemas/baseMarcRecord'
      - type: object
        properties:
          parsedRecordId:
            description: MARC record Id
            type: string
            format: uuid
          parsedRecordDtoId:
            description: ParsedRecordDto identifier
            type: string
            format: uuid
          externalId:
            description: Identifier of external entity
            type: string
            format: uuid
          externalHrid:
            description: HRID of external entity
            type: string
          updateInfo:
            $ref: '#/components/schemas/updateInfo'
    updateInfo:
      type: object
      description: Record metadata
      properties:
        recordState:
          $ref: '#/components/schemas/recordState'
        updateDate:
          description: Date and time of last successful update of the record
          type: string
          format: date-time
        updatedBy:
          $ref: '#/components/schemas/userInfo'
    error:
      type: object
      description: Error response
      properties:
        message:
          type: string
          description: Error message
          example: may not be null
        type:
          type: string
          description: Error type identifier
          example: '1'
        code:
          type: string
          description: Error code
          example: '-1'
        parameters:
          type: array
          description: Additional error parameters
          items:
            type: object
            properties:
              key:
                type: string
                example: moduleTo
              value:
                type: string
                example: 'null'
    recordState:
      type: string
      description: State of source record
      enum:
      - ACTUAL
      - IN_PROGRESS
      - ERROR
    linkDetails:
      description: Link-related fields
      type: object
      properties:
        authorityId:
          description: Id of the authority that controls subfields
          type: string
          format: uuid
          example: c9db5d6a-e1d4-11e8-9f32-f2801f1b9fd1
        authorityNaturalId:
          description: Natural id of the authority that controls subfields
          type: string
          example: n1234567890
        linkingRuleId:
          description: Linking rule ID by which the link was created
          type: integer
          example: 1
        status:
          description: Link status
          type: string
          readOnly: true
          example: ACTUAL
        errorCause:
          description: Cause of error status
          type: string
          readOnly: true
          example: Optimistic locking
      required:
      - authorityId
      - authorityNaturalId
      - linkingRuleId
      - status
      example:
        authorityId: c9db5d6a-e1d4-11e8-9f32-f2801f1b9fd1
        authorityNaturalId: n1234567890
        linkingRuleId: 1
        status: ERROR
        errorCause: Optimistic locking
    quickMarcCreate:
      type: object
      description: MARC record creation model
      x-implements:
      - org.folio.qm.domain.model.BaseQuickMarcRecord
      allOf:
      - $ref: '#/components/schemas/baseMarcRecord'
    authoritySearchParameter:
      description: Authority search parameter for link suggestions
      type: string
      enum:
      - ID
      - NATURAL_ID
      default: NATURAL_ID
x-refined-from:
- folio-mod-quick-marc-records-editor-openapi.json
- folio-mod-quick-marc-records-editor-openapi.yml