$id: https://documentation.noumenadigital.com/schemas/migration-schema-v2.yml
$schema: https://json-schema.org/draft/2020-12/schema
title: Migration descriptor schema
type: object
properties:
  additionalProperties: false
  changesets:
    type: array
    items:
      $ref: '#/$defs/changeSet'
$defs:
  changeSet:
    description: A set of system changes that make up a migration
    type: object
    required:
      - name
      - changes
    properties:
      name:
        description: Unique identifier of the change.
        type:
          - string
          - number
        pattern: '^[a-zA-Z0-9._-]+$'
      changes:
        description: List of changes to be executed in the given order.
        type: array
        minItems: 1
        items:
          $ref: '#/$defs/change'
    additionalProperties: false

  change:
    type: object
    additionalProperties: false
    anyOf:
      - required: [ npl-run ]
      - required: [ migrate ]
      - required: [ run-only ]

    properties:
      npl-run:
        $ref: '#/$defs/nplRun'
      migrate:
        $ref: '#/$defs/migrate'

  nplRun:
    description: Directive indicating execution of a protocol permission.
    type: object
    required:
      - protocol
      - action
    additionalProperties: false

    properties:
      action:
        description: Name of the permission to execute.
        type: string
      protocol:
        description: Name of the protocol to which the permission belongs.
        type: string
      arguments:
        description: Permission arguments, in order.
        type: array
        items:
          type: string
      run-only:
        $ref: '#/$defs/runOnly'

  migrate:
    description: >
      Executes a migration composed of one or more actions, such as loading new sources,
      applying party rules, or performing state migrations.
    type: object
    additionalProperties: false

    anyOf:
      - required: [ rules ]
      - required: [ sources ]
      - required: [ migrations ]

    properties:
      rules:
        description: Path to the party automation rule descriptor file, relative to the migration.yml file.
        type: string
      contrib-libraries:
        description: >
          Paths to zip files containing contribution libraries, relative to the migration.yml file.
        type: array
        items:
          type: string
      sources:
        description: A list of npl source directories. Directories are relative to the migration.yml file.
        type: array
        items:
          type: string
      migrations:
        description: >
          A list of migration state transformation files, expressed in kotlin script. File locations are
          relative to the migration.yml file.
        type: array
        items:
          type: string
      run-only:
        $ref: '#/$defs/runOnly'

  runOnly:
    description: >
      Determines whether the given change will be executed. If no values are provided, or if any listed value matches
      the user-specified value, the change will be executed. This can be used to support different scenarios in
      different environments using the same descriptor file.
    type: array
    items:
      type:
        - string