openapi: 3.1.0
info:
  title: TRM Registry API
  version: 4.0.0
  description: |
    It describes the
    registry protocol only: endpoint inputs, outputs, and HTTP status codes.

    `{package}` is a registry package identifier. Its naming convention is
    registry-defined. This is intentionally a protocol-level contract.

    Call `GET /` before authenticating. Its `authentication_type` selects
    unauthenticated, HTTP Basic, bearer-token, or OAuth2 authentication for
    subsequent operations.
servers:
  - url: https://registry.example.com/
security:
  - {}
  - basicAuth: []
  - bearerAuth: []
paths:
  /:
    get:
      operationId: ping
      summary: Get registry metadata
      security: []
      responses:
        '200':
          description: Registry capabilities and messages
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Ping' }
        default: { $ref: '#/components/responses/Error' }
  /whoami:
    get:
      operationId: whoAmI
      summary: Get the authenticated identity
      responses:
        '200':
          description: Current identity
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WhoAmI' }
        '401': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
  /auth:
    post:
      operationId: exchangeOAuthToken
      summary: Exchange an OAuth2 authorization code or refresh token
      description: Implement this operation only when ping reports `OAUTH2` authentication.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OAuthTokenRequest' }
      responses:
        '200':
          description: OAuth2 tokens
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OAuthTokenResponse' }
        '400': { $ref: '#/components/responses/Error' }
        '401': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
  /batchCompare:
    post:
      operationId: batchCompare
      summary: Compare requested versions with the latest available version
      security: [{}, { basicAuth: [] }, { bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items: { $ref: '#/components/schemas/VersionRequest' }
      responses:
        '200':
          description: One comparison result per supplied item
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/VersionComparison' }
        '400': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
  /package/{package}:
    parameters:
      - $ref: '#/components/parameters/Package'
      - $ref: '#/components/parameters/Version'
    get:
      operationId: getPackage
      summary: Get package metadata and an artifact download link
      security: [{}, { basicAuth: [] }, { bearerAuth: [] }]
      responses:
        '200':
          description: Selected package release
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Package' }
        '400': { $ref: '#/components/responses/Error' }
        '404': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
  /transport/{trkorr}:
    description: Endpoint for registry transport.
    parameters:
      - name: trkorr
        in: path
        required: true
        description: Registry transport
        schema:
          type: string
          pattern: '^[A-Z0-9]{3}K[0-9A-Z]{6}$'
      - name: target
        in: query
        required: false
        description: Optional destination transport request allocated by the target SAP system. When omitted, the canonical transport is downloaded unchanged.
        schema:
          type: string
          pattern: '^[A-Z0-9]{3}K[A-Z0-9]{6}$'
    get:
      operationId: downloadTransport
      summary: Package transport download
      description: Downloads the canonical transports.
      security: [{ basicAuth: [] }, { bearerAuth: [] }]
      responses:
        '200':
          description: The transport is ready to download
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransportDownload' }
        '400': { $ref: '#/components/responses/Error' }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        '404': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        '422': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        '502': { $ref: '#/components/responses/Error' }
        '503': { $ref: '#/components/responses/Error' }
        '504': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
  /delete:
    post:
      operationId: createDeletionTransport
      description: Endpoint for deletion transport.
      security: [{ basicAuth: [] }, { bearerAuth: [] }]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema: { $ref: '#/components/schemas/DeleteTransportRequest' }
      responses:
        '200':
          description: The deletion transport is ready to download
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransportDownload' }
        '400': { $ref: '#/components/responses/Error' }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        '404': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        '413': { $ref: '#/components/responses/Error' }
        '422': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        '502': { $ref: '#/components/responses/Error' }
        '503': { $ref: '#/components/responses/Error' }
        '504': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
  /package/tag/{package}:
    parameters:
      - $ref: '#/components/parameters/Package'
    put:
      operationId: addTag
      summary: Assign a tag to a package version
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TagAssignment' }
      responses:
        '204': { description: Tag assigned }
        '400': { $ref: '#/components/responses/Error' }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
    delete:
      operationId: removeTag
      summary: Remove a package tag
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Tag' }
      responses:
        '204': { description: Tag removed }
        '400': { $ref: '#/components/responses/Error' }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
  /publish/check/{package}:
    parameters:
      - $ref: '#/components/parameters/Package'
      - $ref: '#/components/parameters/RequiredVersion'
      - name: private
        in: query
        required: false
        description: Package visibility indicator.
        schema: { type: string }
    get:
      operationId: checkPublish
      summary: Check whether a package version can be published
      responses:
        '204': { description: Publishing is permitted }
        '400': { $ref: '#/components/responses/Error' }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
  /publish/{package}:
    parameters:
      - $ref: '#/components/parameters/Package'
      - $ref: '#/components/parameters/RequiredVersion'
      - name: tags
        in: query
        required: false
        description: Comma-separated tags to apply. Defaults to `latest`.
        schema: { type: string, default: latest }
    post:
      operationId: publish
      summary: Upload a package artifact
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema: { $ref: '#/components/schemas/PublishRequest' }
      responses:
        '201': { description: Package published successfully }
        '202':
          description: Publication accepted for asynchronous processing
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Publish' }
        '400': { $ref: '#/components/responses/Error' }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        '413': { $ref: '#/components/responses/Error' }
        '422': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
  /deprecate/{package}:
    parameters:
      - $ref: '#/components/parameters/Package'
      - $ref: '#/components/parameters/Version'
    post:
      operationId: deprecate
      summary: Mark a package release as deprecated
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DeprecationRequest' }
      responses:
        '204': { description: Release deprecated }
        '400': { $ref: '#/components/responses/Error' }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        '404': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
  /unpublish/{package}:
    parameters:
      - $ref: '#/components/parameters/Package'
      - $ref: '#/components/parameters/Version'
    post:
      operationId: unpublish
      summary: Remove or yank a package release
      responses:
        '204': { description: Release removed }
        '400': { $ref: '#/components/responses/Error' }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        '404': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use when ping reports `BASIC` authentication.
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Supply a registry-supported credential when ping reports `TOKEN` or `OAUTH2` authentication.
  parameters:
    Package:
      name: package
      in: path
      required: true
      description: A package identifier appended exactly as supplied by RegistryV2. It may contain path separators; do not percent-encode `/` within the identifier.
      schema: { type: string, minLength: 1 }
    Version:
      name: version
      in: query
      required: false
      description: Release version or distribution tag. Defaults to `latest`.
      schema: { type: string, default: latest }
    RequiredVersion:
      name: version
      in: query
      required: true
      description: Release version.
      schema: { type: string }
  responses:
    Error:
      description: Request failed
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Error:
      type: object
      required: [message]
      properties:
        message: { type: string }
    Ping:
      type: object
      required: [authentication_type]
      properties:
        authentication_type: { type: string, enum: [NO_AUTH, BASIC, OAUTH2, TOKEN] }
        authentication_data: { $ref: '#/components/schemas/OAuth2Data' }
        alert_email: { type: string, format: email }
        messages:
          type: array
          items: { $ref: '#/components/schemas/Message' }
      allOf:
        - if:
            properties:
              authentication_type: { const: OAUTH2 }
          then:
            required: [authentication_data]
    OAuth2Data:
      type: object
      required: [authorization_url, client_id, response_type]
      properties:
        authorization_url: { type: string, format: uri }
        client_id: { type: string }
        response_type: { type: string, const: code }
        scope: { type: string }
    OAuthTokenRequest:
      type: object
      required: [grant_type]
      properties:
        grant_type: { type: string, enum: [authorization_code, refresh_token] }
        code: { type: string }
        refresh_token: { type: string }
        redirect_uri: { type: string }
      allOf:
        - if:
            properties:
              grant_type: { const: authorization_code }
          then:
            required: [code, redirect_uri]
        - if:
            properties:
              grant_type: { const: refresh_token }
          then:
            required: [refresh_token]
    OAuthTokenResponse:
      type: object
      required: [access_token, token_type, expires_in]
      properties:
        access_token: { type: string }
        token_type: { type: string, const: Bearer }
        expires_in: { type: integer, minimum: 0 }
        refresh_token: { type: string }
    WhoAmI:
      type: object
      required: [user]
      properties:
        user: { type: string }
        messages:
          type: array
          items: { $ref: '#/components/schemas/Message' }
    Message:
      type: object
      required: [type, text]
      properties:
        type: { type: string, enum: [INFO, WARNING, ERROR] }
        text: { type: string }
    VersionRequest:
      type: object
      required: [name, version]
      properties:
        name: { type: string, description: Package identifier. }
        version: { type: string, description: Version to compare. }
    VersionComparison:
      type: object
      required: [name, version]
      properties:
        name: { type: string }
        version: { type: string }
        latestVersion: { type: string }
        comparison: { type: string, enum: ['<', '=', '>'] }
        error: { type: string, description: Present when this item could not be compared. }
    Package:
      type: object
      required: [name, dist_tags, versions, yanked_versions, manifest, deprecated, download_link, checksum, transports]
      properties:
        name: { type: string }
        dist_tags:
          type: object
          description: Distribution tag names mapped to release versions.
          additionalProperties: { type: string }
        versions:
          type: array
          items: { type: string }
        yanked_versions:
          type: array
          items: { type: string }
        manifest:
          type: object
          description: Package manifest supplied by the artifact.
          required: [name, version]
          properties:
            name: { type: string }
            version: { type: string }
            engines:
              type: object
              description: SAP system requirements (software components, products, SAP Notes, table checks) verified on install.
          additionalProperties: true
        deprecated: { type: boolean }
        deprecated_message: { type: string }
        changelog:
          type: string
          description: Optional Markdown changelog supplied at publication time and sanitized by the registry before storage and response.
        download_link:
          type: string
          format: uri
          description: A URL that returns the package `.trm` artifact as `application/octet-stream`. RegistryV2 follows redirects when downloading it.
        download_link_expiry: { type: integer, format: int64, description: Unix epoch milliseconds. }
        checksum:
          type: string
          description: Base64-encoded SHA-512 digest of the exact artifact bytes returned by `download_link`.
        transports:
          type: array
          description: Transports available in the selected release.
          items: { $ref: '#/components/schemas/Transport' }
    Transport:
      type: object
      required: [trkorr, type, description, contents]
      properties:
        trkorr:
          type: string
          pattern: '^[0-9A-Z]{3}K[0-9A-Z]{6}$'
        type:
          type: string
          enum: [TADIR, DEVC, LANG, CUST]
        description: { type: string }
        contents:
          $ref: '#/components/schemas/TransportContents'
    TransportContents:
      type: object
      required: [download_link, download_link_expiry, checksum]
      properties:
        download_link:
          type: string
          format: uri
          description: A URL that returns the exact parsed R3trans log JSON for this release transport.
        download_link_expiry:
          type: integer
          format: int64
          description: Unix epoch milliseconds.
        checksum:
          type: string
          description: Base64-encoded SHA-512 digest of the exact JSON bytes returned by `download_link`.
    TransportDownload:
      type: object
      required: [download_link, download_link_expiry, checksum]
      properties:
        download_link:
          type: string
          format: uri
          description: A URL that returns a ZIP containing the K and R transport files.
        download_link_expiry:
          type: integer
          format: int64
          description: Unix epoch milliseconds.
        checksum:
          type: string
          description: Base64-encoded SHA-512 digest of the exact ZIP bytes returned by `download_link`.
    DeleteTransportRequest:
      type: object
      required: [header, data]
      properties:
        header:
          type: string
          format: binary
          contentMediaType: application/octet-stream
          description: The K/header file of the source transport.
        data:
          type: string
          format: binary
          contentMediaType: application/octet-stream
          description: The R/data file of the source transport.
    Tag:
      type: object
      required: [tag]
      properties:
        tag: { type: string }
    TagAssignment:
      allOf:
        - $ref: '#/components/schemas/Tag'
        - type: object
          required: [version]
          properties:
            version: { type: string }
    PublishRequest:
      type: object
      required: [artifact]
      properties:
        artifact:
          type: string
          format: binary
          contentMediaType: application/octet-stream
          description: Package artifact.
        readme:
          type: string
          format: binary
          description: Optional Markdown or plain-text README.
        changelog:
          type: string
          format: binary
          description: Optional Markdown or plain-text changelog for this release.
        retainedCustomizing:
          type: string
          maxLength: 2048
          description: JSON-encoded array of up to 100 unique CUST TRKORRs from the immediately preceding published release to retain by reference.
          examples:
            - '["TRMK900012", "TRMK900013"]'
    Publish:
      type: object
      required: [progress_pool_url, steps, current_step]
      properties:
        progress_pool_url:
          type: string
          format: uri
          description: URL to poll for publication progress.
        steps:
          type: integer
          minimum: 0
          description: Total number of publication steps.
        current_step:
          type: integer
          minimum: 0
          description: Current publication step.
        current_step_message:
          type: string
          description: Optional description of the current publication step.
    DeprecationRequest:
      type: object
      required: [deprecate_note]
      properties:
        deprecate_note:
          type: string
          description: Message explaining why the release is deprecated.