schemas.yaml

openapi: "3.0.0"
info:
  title: Databack API
  description: API for communications and administration of databacker instances
  version: "1.0.0"
paths: {} # technically not needed under openapi3, but does not hurt, and aids backwards-compatibility
components:
  schemas:
    KeyInfo:
      type: string
      description: types of info to use for key derivation functions
      enum:
      - SymmetricKey
    Metadata:
      type: object
      properties:
        name:
          type: string
          description: name of the config
        description:
          type: string
          description: description of the config
        digest:
          type: string
          description: SHA256 digest of the config, optional

    CommonRemoteDetails:
      type: object
      properties:
        url:
          type: string
          description: URL to the remote
        credentials:
          type: string
          description: |
            Credentials to use to authenticate to the remote server.
            Format is base64-encoded Curve25519 key
          example: BwMqVfr1myxqX8tikIPYCyNtpHgMLIg/2nUE+pLQnTE=
        certificates:
          type: array
          description: |
            Fingerprints of the remote certificate of the remote server, or one that signed it in the chain.
            Starts with hash algorithm, e.g. sha256, followed by a : and the hex of the fingerprint.
          example: sha256:69729b8e15a86efc177a57afb7171dfc64add28c2fca8cf1507e34453ccb1470
          items:
            type: string

    Config:
      type: object
      description: |
        Base configuration for a databack instance, with details in the spec.
        Spec is determined by the kind.
      required:
        - version
        - kind
        - metadata
        - spec
      properties:
        version:
          type: string
          enum:
          - config.databack.io/v1
        kind:
          type: string
          enum:
          - local
          - remote
          - encrypted
        metadata:
          $ref: '#/components/schemas/Metadata'
          
        spec:
          type: object
          discriminator:
            propertyName: kind
            mapping:
              local: '#/components/schemas/ConfigSpec'
              remote: '#/components/schemas/RemoteSpec'
              encrypted: '#/components/schemas/EncryptedSpec'
    ConfigSpec:
      type: object
      description: configuration details for a databack instance
      properties:
        database:
          $ref: "#/components/schemas/Database"
          description: configuration information for accessing database to backup
        dump:
          $ref: "#/components/schemas/Dump"
          description: schedule and details for backups
        targets:
          type: object
          description: |
            Configuration for individual targets that may be used for backup or restore.
            To be referenced from within the Dump or Restore configuration.
          additionalProperties:
            $ref: '#/components/schemas/Target'
        telemetry:
          $ref: '#/components/schemas/Telemetry'
        prune:
          $ref: '#/components/schemas/Prune'
        restore:
          $ref: '#/components/schemas/Restore'
        logging:
          type: string
          description: logging level, one of debug, info, warn, error, fatal          
          enum:
          - trace
          - debug
          - info
          - warn
          - error

    Prune:
      type: object
      properties:
        retention:
          type: string
          description: retention policies for backups

    Restore:
      type: object
      properties:
        preRestore:
          type: string
          description: directory where to find scripts to run before the restore
        postRestore:
          type: string
          description: directory where to find scripts to run after the restore

    Database:
      type: object
      properties:
        server: 
          type: string
          description: hostname:port to database
        port:
          type: integer
          description: port to connect to, defaults to 5432, overrides "server"
        credentials:
          $ref: "#/components/schemas/DBCredentials"

    DBCredentials:
      type: object
      properties:
        username:
          type: string
          description: username for the database
        password:
          type: string
          description: password for the database

    Dump:
      type: object
      properties:
        include:
          type: array
          description: list of database names to backup, defaults to all
          items:
            type: string
        exclude:
          type: array
          description: list of database names to exclude from backup, defaults to none
          items:
            type: string
        safechars:
          type: boolean
          description: whether to use safe characters in the backup name, defaults to false
        noDatabaseName:
          type: boolean
          description: do not include database name in backup, assumes will run restore already selected to specific database
        skipExtendedInsert:
          type: boolean
          description: whether to skip extended insert statements and use one insert per row, defaults to false
        schedule:
          $ref: '#/components/schemas/Schedule'
        compression:
          type: string
          description: compression algorithm to use, defaults to none
        compact:
          type: boolean
          description: whether to compact the backup, defaults to false
        triggers:
          type: boolean
          description: whether to include triggers in the backup, defaults to false
        routines:
          type: boolean
          description: whether to include routines, such as functions and procedures, in the backup, defaults to false
        maxAllowedPacket:
          type: integer
          description: maximum packet size to username
        filenamePattern:
          type: string
          description: pattern for the filename
        encryption:
          $ref: '#/components/schemas/Encryption'
        targets:
          type: array
          description: list of targets to send the backup, must reference one of the named targets in the config
          items:
            type: string
        parallelism:
          type: integer
          description: level of parallelism to use for the backup, defaults to 1
        scripts:
          $ref: '#/components/schemas/Scripts'

    Schedule:
      type: object
      properties:
        cron:
          type: string
          description: cron expression for the schedule
        frequency:
          type: integer
          description: frequency in minutes
        begin:
          type: integer
          description: when to start the schedule, in minutes from now, default is 0
        once:
          type: boolean
          description: whether to run the schedule only once, default is false

    Scripts:
      type: object
      properties:
        preBackup:
          type: string
          description: directory where to find scripts to run before the backup
        postBackup:
          type: string
          description: directory where to find scripts to run after the backup
    
    Encryption:
      type: object
      properties:
        algorithm:
          type: string
          enum: [aes256-cbc,chacha20-poly1305,smime-aes256-cbc,pbkdf2-aes256-cbc,age-chacha20-poly1305]
          description: algorithm to use for encryption
        key:
          type: string
          description: encryption key or certificate, depending on algorithm, base64-encoded
        keyPath:
          type: string
          description: path to the encryption key or certificate, depending on algorithm
    
    RemoteSpec:
      description: details for retrieving configuration from a remote server
      allOf:
      - $ref: '#/components/schemas/CommonRemoteDetails'

    EncryptedSpec:
      type: object
      description: Spec that is encrypted, using the provided algorithm. The symmetric key is encrypted with the public key of the instance.
      properties:
        algorithm: 
          type: string
          description: algorithm used to encrypt the data, lower-case, with the key derived using NaCL key agreement
          enum: [aes256-gcm,chacha20-poly1305]
        recipientPublicKey:
          type: string
          description: public key of the recipient, base64-encoded
        senderPublicKey:
          type: string
          description: public key of the recipient, base64-encoded
        data:
          description: encrypted data base64-encoded, when decrypted should be a valid Config
          type: string

    Telemetry:
      allOf:
        - $ref: '#/components/schemas/CommonRemoteDetails'
        - properties:
            bufferSize:
              type: integer
              description: size of the buffer to use for telemetry, in bytes

    Log:
      type: object
      properties:
        run:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          description: run ID as UUID
        timestamp:
          type: string
          description: timestamp for the date and time of a message, in RFC3339 format
        level:
          type: string
          description: log level of the message, one of debug, info, warn, error, fatal
        fields:
          type: object
          additionalProperties: true
          description: key-value pairs for descriptive fields for the log message
        message:
          type: string
          description: actual message

    LogSummary:
      type: object
      properties:
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        date:
          type: integer
          description: timestamp for start of backup run
        completion:
          type: integer
          description: completion code, using a subset of http codes
        size:
          type: integer
          description: size of logs in bytes

    Target:
      type: object
      description: individual backup target
      discriminator:
        propertyName: type
      properties:
        type:
          type: string
          enum: [s3,smb,file]
        url:
          type: string
          description: url to send the backup to
        spec:
          type: object
          discriminator:
            propertyName: kind
            mapping:
              s3: '#/components/schemas/S3'
              smb: '#/components/schemas/SMB'
              file: '#/components/schemas/File'
      required:
        - type
        - url
    S3:
      type: object
      properties:
        region:
          type: string
          description: region of the bucket
        endpoint:
          type: string
          description: endpoint URL
        pathStyle:
          type: boolean
          description: whether to use path-style addressing instead of virtual-host-style, defaults to false
        accessKeyID:
          type: string
          description: access key ID
        secretAccessKey:
          type: string
          description: secret access key
    SMB:
      type: object
      properties:
        domain:
          type: string
          description: domain for the username
        username:
          type: string
          description: username for the target
        password:
          type: string
          description: password for the target
    File:
      type: object
      properties: {}

    # ---------------------------------------------------------------------------
    # Backup Trace Semantic Convention
    # ---------------------------------------------------------------------------
    # These types define the agreed-upon OTEL span names and attribute keys that
    # backup engines MUST emit and that the cloud service uses to derive
    # BackupTimelineEvent records from stored OpenTelemetry spans.
    # ---------------------------------------------------------------------------

    BackupSpanName:
      type: string
      description: |
        Stable OTEL span names for backup and restore engine traces.
        Engines MUST use one of these names when creating spans.
        Each span name corresponds to a distinct phase in the backup/restore lifecycle.

        Note: prune-target spans are dynamic. The emitted span name is
        "pruneTarget <url>" where <url> is the target URL. The constant
        BackupSpanPruneTarget holds the static prefix "pruneTarget".
      enum:
      - run
      - connect
      - snapshot
      - dump
      - upload
      - verify
      - cleanup
      - startup
      - database_dump
      - output_tar
      - pre-backup
      - post-backup
      - pre-restore
      - post-restore
      - restore
      - pull file
      - input_tar
      - database_restore
      - prune
      - pruneTarget
      x-enum-varnames:
      - BackupSpanRun
      - BackupSpanConnect
      - BackupSpanSnapshot
      - BackupSpanDump
      - BackupSpanUpload
      - BackupSpanVerify
      - BackupSpanCleanup
      - BackupSpanStartup
      - BackupSpanDatabaseDump
      - BackupSpanOutputTar
      - BackupSpanPreBackup
      - BackupSpanPostBackup
      - BackupSpanPreRestore
      - BackupSpanPostRestore
      - BackupSpanRestore
      - BackupSpanPullFile
      - BackupSpanInputTar
      - BackupSpanDatabaseRestore
      - BackupSpanPrune
      - BackupSpanPruneTarget

    BackupPhase:
      type: string
      description: |
        Value for the backup.phase span attribute.
        Indicates which phase of the backup or restore this span represents.
        "complete" is used only on the root "run" span once all phases finish.
        For prune-target spans, use "pruneTarget" regardless of the dynamic span name suffix.
      enum:
      - run
      - connect
      - snapshot
      - dump
      - upload
      - verify
      - cleanup
      - complete
      - startup
      - database_dump
      - output_tar
      - pre-backup
      - post-backup
      - pre-restore
      - post-restore
      - restore
      - pull file
      - input_tar
      - database_restore
      - prune
      - pruneTarget
      x-enum-varnames:
      - BackupPhaseRun
      - BackupPhaseConnect
      - BackupPhaseSnapshot
      - BackupPhaseDump
      - BackupPhaseUpload
      - BackupPhaseVerify
      - BackupPhaseCleanup
      - BackupPhaseComplete
      - BackupPhaseStartup
      - BackupPhaseDatabaseDump
      - BackupPhaseOutputTar
      - BackupPhasePreBackup
      - BackupPhasePostBackup
      - BackupPhasePreRestore
      - BackupPhasePostRestore
      - BackupPhaseRestore
      - BackupPhasePullFile
      - BackupPhaseInputTar
      - BackupPhaseDatabaseRestore
      - BackupPhasePrune
      - BackupPhasePruneTarget

    BackupStatus:
      type: string
      description: |
        Value for the backup.status span attribute.
        Indicates the outcome of a span or phase.
        "running" is set when the span begins; "ok" or "error" when it ends.
      enum:
      - running
      - ok
      - error
      x-enum-varnames:
      - BackupStatusRunning
      - BackupStatusOK
      - BackupStatusError

    OtelStatusCode:
      type: string
      description: |
        OTEL span status code per the OpenTelemetry specification.
        Set via the otel.status_code span attribute.
        "ERROR" should be accompanied by otel.status_description.
      enum:
      - OK
      - ERROR
      - UNSET
      x-enum-varnames:
      - OtelStatusCodeOK
      - OtelStatusCodeError
      - OtelStatusCodeUnset

    BackupProtectedTargetSelectionMode:
      type: string
      description: |
        Describes how databases are selected for protection by the backup engine.

        all     — the engine is configured to back up all databases on the server or cluster.
                  Individual database names MAY still be reported via
                  backup.protected_target.databases if known at runtime.
                  backup.protected_target.configured_databases has no meaning for this mode.
        include — the engine is configured to back up a named subset of databases.
                  The configured list SHOULD be reported via
                  backup.protected_target.configured_databases; the actual databases backed
                  up SHOULD be reported via backup.protected_target.databases.
        exclude — the engine is configured to back up all databases except a named subset.
                  The excluded list SHOULD be reported via
                  backup.protected_target.configured_databases; the actual databases backed
                  up SHOULD be reported via backup.protected_target.databases.
      enum:
      - all
      - include
      - exclude
      x-enum-varnames:
      - BackupProtectedTargetSelectionModeAll
      - BackupProtectedTargetSelectionModeInclude
      - BackupProtectedTargetSelectionModeExclude

    BackupAttributeKey:
      type: string
      description: |
        Stable OTEL span attribute key names for backup engine traces.
        These are the agreed-upon attribute keys that engines MUST emit on each
        relevant span, and that the cloud service uses to derive
        BackupTimelineEvent records.

        Attribute key reference:
          backup.run_id           — stable UUID identifying the backup run
          backup.phase            — one of the BackupPhase enum values
          backup.status           — one of the BackupStatus enum values
          backup.bytes            — bytes processed in this phase (when applicable)
          backup.object_count     — objects (tables/files) processed (when applicable)
          backup.exit_code        — engine process/result exit code (when applicable)
          backup.event.label      — optional short user-facing label
          backup.event.message    — optional user-facing status or error message
          db.system               — database system (e.g. postgresql, mysql) per OTEL semconv
          db.name                 — name of the database being backed up
          network.transport       — transport protocol per OTEL semconv (e.g. tcp)
          server.address          — hostname/IP of the database server
          server.port             — port number of the database server
          otel.status_code        — OTEL span status: OK, ERROR, or UNSET
          otel.status_description — human-readable status description, set on error

          Target identity attributes (upload spans):
          backup.target.name      — target key/name from the engine config, e.g. "daily-s3", "local-dev"
          backup.target.type      — target type matching the engine config, e.g. "file", "s3", "smb"
          backup.target.url       — safe display URL identifying the destination, e.g.
                                    "file:///var/lib/databacker/dev/database1",
                                    "s3://bucket/path", "smb://server/share/path".
                                    MUST NOT contain credentials, access keys, tokens,
                                    signed URLs, or any other secrets.

          Protected target identity attributes (connect, snapshot, dump spans):
          backup.protected_target.selection_mode — one of the BackupProtectedTargetSelectionMode
                                                   enum values; describes how databases are selected
                                                   for protection (all, include, or exclude).
          backup.protected_target.identity       — engine-computed, deterministic string that stably
                                                   identifies the protected target across runs.
                                                   Derived from: db.system, selection mode,
                                                   db.server.native_id or db.provider.resource_id
                                                   when available, and the sorted configured members
                                                   (for include/exclude modes). Engines MUST
                                                   produce the same value for the same logical
                                                   target on every run.
          backup.protected_target.database_count — number of logical databases in scope; MAY be
                                                   present even when the full list is omitted or
                                                   truncated.
          backup.protected_target.configured_databases — JSON array of database names from the engine
                                                   config: the include list (for include mode) or the
                                                   exclude list (for exclude mode). Use stable
                                                   (sorted) ordering. Has no meaning for all mode.
          backup.protected_target.databases      — JSON array of logical database names actually
                                                   backed up, when known. Use stable (sorted)
                                                   ordering. MAY be omitted or truncated for all
                                                   mode with very large database counts.
          db.server.native_id                    — DB-native server or cluster identifier, stable
                                                   across restarts. Examples: PostgreSQL
                                                   system_identifier (from pg_control), MySQL
                                                   server_uuid (@@global.server_uuid).
          db.provider.resource_id                — managed-service resource identity assigned by the
                                                   cloud provider. Examples: AWS RDS ARN
                                                   (arn:aws:rds:…), Cloud SQL resource name
                                                   (projects/…/instances/…).

          Engine-observed diagnostic attributes (various spans):
          timestamp               — ISO 8601 / RFC 3339 timestamp recorded by the engine within a span
          source-filename         — source file path being read or processed
          target-filename         — destination file path being written
          provided-schemas        — schema list supplied to the operation (string or JSON array)
          actual-schemas          — schema list actually found or used (string or JSON array)
          copied                  — number of items (rows, files, bytes) copied in the span
          target                  — generic target identifier string for the current operation
          targetfile              — file path of the current target artifact
          tmpfile                 — path of a temporary file used during the operation
          files                   — count or list of files involved in the operation
          candidates              — count or list of prune/restore candidates evaluated
          ignored                 — count or list of items skipped or ignored
          invalidDate             — a date value that failed validation during prune evaluation
      enum:
      - backup.run_id
      - backup.phase
      - backup.status
      - backup.bytes
      - backup.object_count
      - backup.exit_code
      - backup.event.label
      - backup.event.message
      - db.system
      - db.name
      - network.transport
      - server.address
      - server.port
      - otel.status_code
      - otel.status_description
      - backup.target.name
      - backup.target.type
      - backup.target.url
      - backup.protected_target.selection_mode
      - backup.protected_target.identity
      - backup.protected_target.database_count
      - backup.protected_target.configured_databases
      - backup.protected_target.databases
      - db.server.native_id
      - db.provider.resource_id
      - timestamp
      - source-filename
      - target-filename
      - provided-schemas
      - actual-schemas
      - copied
      - target
      - targetfile
      - tmpfile
      - files
      - candidates
      - ignored
      - invalidDate
      x-enum-varnames:
      - BackupAttrRunID
      - BackupAttrPhase
      - BackupAttrStatus
      - BackupAttrBytes
      - BackupAttrObjectCount
      - BackupAttrExitCode
      - BackupAttrEventLabel
      - BackupAttrEventMessage
      - BackupAttrDBSystem
      - BackupAttrDBName
      - BackupAttrNetworkTransport
      - BackupAttrServerAddress
      - BackupAttrServerPort
      - BackupAttrOtelStatusCode
      - BackupAttrOtelStatusDescription
      - BackupAttrTargetName
      - BackupAttrTargetType
      - BackupAttrTargetURL
      - BackupAttrProtectedTargetSelectionMode
      - BackupAttrProtectedTargetIdentity
      - BackupAttrProtectedTargetDatabaseCount
      - BackupAttrProtectedTargetConfiguredDatabases
      - BackupAttrProtectedTargetDatabases
      - BackupAttrDBServerNativeID
      - BackupAttrDBProviderResourceID
      - BackupAttrTimestamp
      - BackupAttrSourceFilename
      - BackupAttrTargetFilename
      - BackupAttrProvidedSchemas
      - BackupAttrActualSchemas
      - BackupAttrCopied
      - BackupAttrTarget
      - BackupAttrTargetFile
      - BackupAttrTmpFile
      - BackupAttrFiles
      - BackupAttrCandidates
      - BackupAttrIgnored
      - BackupAttrInvalidDate

  securitySchemes:
    # note that we could explicitly use the "type: oauth2" with flows, but that would
    # require stating the endpoints, which are an implementation detail, and would not
    # let us restrict it to JWT, as oauth does not declare the token format.
    # The endpoints and how the JWT bearer token is retrieved should be an implementation detail.
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT