openapi: 3.0.0
info:
  title: Multiple Allele Code Service
  version: '1.5'
  description: |-
    A collection of services for working with Multiple Allele Codes (MAC).
    
    Some useful links:
    - [Swagger Editor](https://editor-next.swagger.io/?url=https://hml.nmdp.org/mac/mac-oas.yaml)
    - [MAC UI: User interface](https://hml.nmdp.org/macui/)
    - [HLA Nomenclature]( http://hla.alleles.org/nomenclature/index.html)
    - [IMGT/HLA reference files on GitHub](https://github.com/ANHIG/IMGTHLA)
    - [Genotype List String manuscript ]( http://www.ncbi.nlm.nih.gov/pubmed/23849068)
    - [py-ard: HLA Nomenclature tool](https://py-ard.org/)
    - [Sample clients](https://github.com/nmdp-bioinformatics/multiple-allele-code/tree/master/client)
  termsOfService: https://network.nmdp.org/legal/terms-of-use

servers:
  - url: https://hml.nmdp.org/mac/api/
paths:
  /codes:
    get:
      description: Get a tab separated table of MAC definitions.
      responses:
        '200':
          description: 'MAC definitions in 3 columns (ALLELE_SPECIFIC_FLAG, CODE, ALLELE_FIELD_LIST)'
          content:
            text/plain:
              schema:
                example: "\tGB\t12/13\n\tGC\t01/05/07\n*\tGD\t03:01/52:01\n*\tGE\t02:01/32:01\n"
                type: string
        '400':
          description: "Bad request"
          content:
            text/plain:
              schema:
                example: "The multiple allele code 'ODD' is not valid"
                type: string
        '500':
          description: 'Server error'
          content:
            text/plain:
              schema:
                example: "System Error.  Details in logs"
                type: string
      operationId: get_codes
      parameters:
        - name: after
          in: query
          required: false
          description: |
            Only return code definitions with a code greater than the specified value.
            If "AAA" is specified,  will not include itself or shorter codes like "ZZ".
          schema:
            type: string
            example: AAA
        - name: before
          in: query
          required: false
          description: Only return code definitions with a code less than the specified value.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: |
            Maximum number of returned definitions.  
            Defaults to 1,000 and must be in range 1 to 10,000.
          schema:
            example: 10
            default: 1000
            minimum: 1
            maximum: 10000
            format: int32
            type: integer
  /codes/{code}:
    get:
      responses:
        '200':
          description: 'MAC definitions in 3 columns (ALLELE_SPECIFIC_FLAG, CODE, ALLELE_FIELD_LIST)'
          content:
            text/plain:
              schema:
                example: "\tABCD\t01/03/19/27/28/41"
                type: string
        '400':
          description: 'Bad request'
          content:
            text/plain:
              schema:
                type: string
                example: "The allele code 'ODD' is not valid for parameter 'code'"
        '500':
          description: 'Server error'
          content:
            text/plain:
              schema:
                type: string
      description: Retrieve the multiple allele code definition for the specified code
      operationId: get_codes-code
    parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          example: ABCD
        description: A multiple allele code (2 or more upper-case letters)
  /encode:
    post:
      description: Encode a GL String into a MAC designation.
      responses:
        '200':
          description: 'A MAC designation which represents a list of 2-field alleles'
          headers:
            x-warning:
              description: information that should be logged or shown to user
              schema:
                type: string
          content:
            text/plain:
              schema:
                example: HLA-A*01:AB
                type: string
        '400':
          description: 'Bad request'
          content:
            text/plain:
              schema:
                example: 'Invalid allele: HLA-B*01:01'
                type: string
        '500':
          description: 'Server error'
          content:
            text/plain:
              schema:
                type: string
      operationId: post_encode
      requestBody:
        content:
          text/plain:
            schema:
              example: HLA-A*01:01/HLA-A*01:02
              type: string
        required: true
        description: GL String
      parameters:
        - name: trialRun
          in: query
          required: false
          description: Simulate an encode without allowing MAC creation.
          schema:
            type: boolean
        - name: imgtHlaRelease
          in: query
          required: false
          description: |
            Optionally specify the IMGT/HLA Release like "3.19.0" (default is the latest release)
          schema:
            type: string
            example: "3.57.0"
        - name: email
          in: query
          required: false
          description: |
            Specify an email identifying the requester.  
            Without this no new allele code will be created
          schema:
            type: string
  /decode:
    get:
      description: 'Decode a MAC designation into a list of alleles'
      responses:
        '200':
          description: 'A list of 2-field alleles'
          content:
            text/plain:
              schema:
                example: 'HLA-DRB1*01:01/HLA-DRB1*01:02'
                type: string
        '400':
          description: "Bad request"
          content:
            text/plain:
              schema:
                example: 'Invalid allele code: ONE'
                type: string
        '500':
          description: 'Server error'
          content:
            text/plain:
              schema:
                type: string
      operationId: get_decode
      parameters:
        - name: imgtHlaRelease
          in: query
          required: false
          description: |
            Optionally specify the IMGT/HLA Release like "3.19.0" (default is the latest release)
          schema:
            type: string
        - name: typing
          in: query
          required: true
          description: An allele code designation in the format locus*firstField:alleleCode
          schema:
            type: string
            example: 'HLA-DRB1*01:AB'
        - name: expand
          in: query
          required: false
          description: flag indicating whether to expand to 2-field allele names or to full IMGT/HLA allele names.
          schema:
            default: false
            type: boolean
  /decodeList:
    post:
      responses:
        '200':
          description: 'jSON array of DecodedTyping'
          content:
            application/json:
              schema:
                example:
                  - typing: HLA-A*01:AB
                    alleleString: HLA-A*01:01/HLA-A*01:02
                    httpStatus: 200
                    errorMsg: 'null'
                  - typing: HLA-DRB1*15:ML
                    alleleString: HLA-DRB1*15:01/HLA-DRB1*15:13/HLA-DRB1*15:16/HLA-DRB1*15:18
                    httpStatus: 200
                    errorMsg: 'null'
                  - typing: HLA-A*99:BOGUS
                    alleleString: 'null'
                    httpStatus: 400
                    errorMsg: Could not decode typing
                type: array
                items:
                  $ref: '#/components/schemas/DecodedTyping'
        '400':
          description: "Bad request"
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: 'Server error'
          content:
            text/plain:
              schema:
                type: string
      operationId: post_decodeList
      requestBody:
        description: JSON array of MAC designations
        content:
          application/json:
            example:
              - HLA-A*01:AB
              - HLA-DRB1*15:ML
              - HLA-A*99:BOGUS
            schema:
              type: array
              items:
                type: string
        required: true
      parameters:
        - name: imgtHlaRelease
          in: query
          required: false
          description: |
            Optionally specify the IMGT/HLA Release like "3.19.0" (default is the latest release)
          schema:
            type: string
  /imgtHlaReleases:
    get:
      description: Return the known IMGT/HLA Releases.
      responses:
        '200':
          description: A table of IMGT/HLA Releases from most recent to oldest.
          content:
            text/plain:
              schema:
                example: |-
                  3.57.0 2024-08
                  3.56.0 2024-04
                  3.55.0 2024-01
                type: string
        '400':
          description: "Bad request"
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: 'Server error'
          content:
            text/plain:
              schema:
                type: string
      operationId: get_imgtHlaReleases
  /validate:
    get:
      description: Validate a MAC Designation for the specified IMGT/HLA Release
      responses:
        '200':
          description: 'JSON ValidationResult'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '400':
          description: "Bad request"
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: 'Server error'
          content:
            text/plain:
              schema:
                type: string
      operationId: get_validate
      parameters:
        - name: imgtHlaRelease
          in: query
          required: true
          description: The IMGT/HLA Release version.
          schema:
            type: string
            example: 3.57.0
        - name: typing
          in: query
          required: true
          description: An allele code designation in the format locus*family:alleleCode
          schema:
            type: string
            example:  HLA-B*01:AB
  /validateList:
    post:
      description: Validate a list of MAC Designations for the specified IMGT/HLA Release
      responses:
        '200':
          description: 'JSON ValidationResult array'
          content:
            application/json:
              schema:
                example:
                  - typing: A*01:AB
                    httpStatus: 200
                    errorMsg: 'null'
                    validationResult:
                      valid: true
                      historicallyValid: true
                      description: The MACD is valid
                      conditions: []
                  - typing: C*01:AB
                    httpStatus: 200
                    errorMsg: 'null'
                    validationResult:
                      valid: false
                      historicallyValid: true
                      description: 'The MACD contains a RENAMED allele: [C*01:01]'
                      conditions:
                        - code: RENAMED
                          imgtHlaRelease: 3.35.0
                          itemValue: C*01:01
                  - typing: A*24:AB
                    httpStatus: 200
                    errorMsg: 'null'
                    validationResult:
                      valid: false
                      historicallyValid: true
                      description: 'The MACD contains a DELETED allele: [A*24:01]'
                      conditions:
                        - code: DELETED
                          imgtHlaRelease: 3.35.0
                          itemValue: A*24:01
                  - typing: HLA-B*24:AB
                    httpStatus: 200
                    errorMsg: 'null'
                    validationResult:
                      valid: false
                      historicallyValid: false
                      description: 'The MACD contains INVALID alleles: [HLA-B*24:01, HLA-B*24:02]'
                      conditions:
                        - code: INVALID
                          imgtHlaRelease: 3.35.0
                          itemValue: HLA-B*24:01
                        - code: INVALID
                          imgtHlaRelease: 3.35.0
                          itemValue: HLA-B*24:02
                  - typing: A*01:XX
                    httpStatus: 400
                    errorMsg: Only MAC Designations are supported. [A*01:XX] is not a valid MAC Designation for IMGT HLA Release 3.35.0
                    validationResult: null
                  - typing: HLA-A*01:01
                    httpStatus: 400
                    errorMsg: Only MAC Designations are supported. [HLA-A*01:01] is not a valid MAC Designation for IMGT HLA Release 3.35.0
                    validationResult: null
                  - typing: A*24:BOGUS
                    httpStatus: 400
                    errorMsg: Only MAC Designations are supported. [A*24:BOGUS] is not a valid MAC Designation for IMGT HLA Release 3.35.0
                    validationResult: null
                type: array
                items:
                  $ref: '#/components/schemas/ValidatedTyping'
        '400':
          description: "Bad request"
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: 'Server error'
          content:
            text/plain:
              schema:
                type: string
      operationId: post_validateList
      requestBody:
        description: JSON array of ValidatonResult
        content:
          application/json:
            example:
              - A*01:AB
              - C*01:AB
              - A*24:AB
              - HLA-B*24:AB
              - A*01:XX
              - HLA-A*01:01
              - A*24:BOGUS
            schema:
              type: array
              items:
                type: string
        required: true
      parameters:
        - name: imgtHlaRelease
          in: query
          description: |
            Optionally specify the IMGT/HLA Release like "3.19.0" (default is the latest release)
          schema:
            type: string
  /expand:
    get:
      description: Expand a MAC Designation into a JSON array of alleles with transformation reasons.
      responses:
        '200':
          description: 'JSON array of alleles with transformation reasons'
          content:
            application/json:
              schema:
                example:
                  - transformationReason: 'null'
                    oldName: 'null'
                    oldNameStatus: valid
                    expanded: A*01:03:01:02
                  - oldName: A*01:34N
                    oldNameStatus: invalid
                    expanded: A*01:01:38L
                    transformationReason: DELRENAME
                type: array
                items:
                  $ref: '#/components/schemas/AlleleResponseItem'
        '400':
          description: "Bad request"
          content:
            text/plain:
              schema:
                example: 'Invalid allele code: ONE'
                type: string
        '500':
          description: 'Server error'
          content:
            text/plain:
              schema:
                type: string
      operationId: get_expand
      parameters:
        - name: imgtHlaRelease
          in: query
          required: false
          description: |
            Optionally specify the IMGT/HLA Release like "3.19.0" (default is the latest release)
          schema:
            type: string
        - name: typing
          in: query
          required: true
          description: An allele code designation in the format locus*firstField:alleleCode
          schema:
            example: "HLA-A*01:RAD"
            type: string
  /transform:
    get:
      description: Transform a MAC designation to the preferred format
      responses:
        '200':
          description: 'JSON object of the preferred MAC Designation with transformation reasons'
          content:
            application/json:
              example:
                macd: HLA-A*01:EZHXE
                transformations:
                  - oldName: A*01:04
                    oldNameStatus: valid
                    expanded: A*01:04N
                    transformationReason: DISPLAYEXP
                  - oldName: A*01:11
                    oldNameStatus: valid
                    expanded: A*01:11N
                    transformationReason: DISPLAYEXP
              schema:
                $ref: '#/components/schemas/TransformedMacd'
        '400':
          description: "Bad request"
          content:
            text/plain:
              schema:
                example: 'Invalid allele code: ONE'
                type: string
        '500':
          description: 'Server error'
          content:
            text/plain:
              schema:
                type: string
      operationId: get_transform
      parameters:
        - name: imgtHlaRelease
          in: query
          required: false
          description: |
            Optionally specify the IMGT/HLA Release like "3.19.0" (default is the latest release)
          schema:
            type: string
        - name: typing
          in: query
          required: true
          description: An allele code designation in the format locus*firstField:alleleCode
          schema:
            type: string
            example: "HLA-A*01:ET"
components:
  schemas:
    AlleleResponseItem:
      properties:
        oldName:
          description: If a transformation is done, the original value
          type: string
        oldNameStatus:
          type: string
        expanded:
          description: The full allele name used for display.
          type: string
        transformationReason:
          description: |
            The code for the transformation performed.
              * DISPLAYEXP - Added, updated, or removed an expression character
              * DELRENAME - Transformed a deleted or renamed allele
          type: string
      required:
        - oldNameStatus
        - expanded
      type: object
    TransformedMacd:
      description: A transformed multiple allele code designation like "HLA-A*01:AB"
      properties:
        macd:
          type: string
        transformations:
          type: array
          items:
            $ref: '#/components/schemas/AlleleResponseItem'
      required:
        - macd
        - transformations
      type: object
    DecodedTyping:
      description: A decoded typing like "HLA-A*01:AB"
      properties:
        typing:
          type: string
        alleleString:
          type: string
        httpStatus:
          type: integer
        errorMsg:
          type: string
      required:
        - typing
        - httpStatus
      type: object
    AlleleValidationCondition:
      description: A validation condition for a single allele
      properties:
        code:
          description: |
            Symbolic code for the condition
              * DELETE - The original allele was deleted
              * RENAME - The original allele has been renamed
              * INVALID - The allele is invalid (never existed)
              * DEPRECATED - The allele has been deleted/renamed, but is temporarily still valid
          type: string
        imgtHlaRelease:
          description: IMGT HLA Release version for the condition
          type: string
        itemValue:
          description: Allele or value associated with response code
          type: string
      required:
        - code
        - itemValue
      type: object
    ValidationResult:
      description: The results returned by the /validate endpoint
      properties:
        valid:
          description: Whether the type is currently valid
          type: boolean
        historicallyValid:
          description: Whether the type was historically valid (Delete/Rename)
          type: boolean
        description:
          description: A text description of the validation result
          type: string
          example: "The MACD is valid"
        conditions:
          description: A list of conditions determined on individual alleles
          type: array
          example: "[]"
          items:
            $ref: '#/components/schemas/AlleleValidationCondition'
      required:
        - valid
        - historicallyValid
        - description
      type: object
    ValidatedTyping:
      description: A validated typing like "HLA-A*01:AB"
      properties:
        typing:
          type: string
        validationResult:
          oneOf:
            - $ref: '#/components/schemas/ValidationResult'
            - type: object
        httpStatus:
          type: integer
        errorMsg:
          type: string
      required:
        - typing
        - httpStatus
      type: object
  responses: {}
  parameters: {}
  examples: {}
  requestBodies: {}
  headers: {}
  securitySchemes: {}
  links: {}
  callbacks: {}