ProjectSchemaExtension

Расширение JSON Schema для валидации конфигурации проекта.

Свойства

Наименование	Тип	Обязательное
project	ProjectSchemaExtensionCommon	Нет
tasks	ProjectSchemaExtensionTasks	Нет
actions	ProjectSchemaExtensionActions	Нет
triggers	ProjectSchemaExtensionTriggers	Нет
definitions	Record<string, unknown>	Нет

Вспомогательные типы

ProjectSchemaExtensionCommon

Наименование	Тип	Обязательное
properties	unknown	Да
required	string[]	Нет

ProjectSchemaExtensionTask

Наименование	Тип	Обязательное
type	string	Да
options	unknown	Да

ProjectSchemaExtensionAction

Наименование	Тип	Обязательное
type	string	Да
options	unknown	Нет

ProjectSchemaExtensionTrigger

Наименование	Тип	Обязательное
type	string	Да
options	unknown	Нет

ProjectSchemaExtensionTasks

Объект расширений задач.

Значения содержат ProjectSchemaExtensionTask, а значение по специальному ключу "*" содержит ProjectSchemaExtensionCommon - описание свойств, общих для задач всех типов.

ProjectSchemaExtensionActions

Объект расширений действий.

Значения содержат ProjectSchemaExtensionAction, а значение по специальному ключу "*" содержит ProjectSchemaExtensionCommon - описание свойств, общих для всех действий.

ProjectSchemaExtensionTriggers

Объект расширений триггеров.

Значения содержат ProjectSchemaExtensionTrigger, а значение по специальному ключу "*" содержит ProjectSchemaExtensionCommon - описание свойств, общих для триггеров всех типов.

Описание

ProjectSchemaExtension позволяет плагинам расширять схему валидации конфигурации проекта, добавляя:

• пользовательские поля в корневую конфигурацию проекта
• новые типы задач с их параметрами
• новые типы действий с их параметрами
• новые типы триггеров с их параметрами
• дополнительные определения схемы (definitions)

Схема валидации основана на JSON Schema Draft 2020-12.

Описание свойств

project

Тип: ProjectSchemaExtensionCommon

Обязательное: Нет

Расширяет корневую схему проекта, добавляя пользовательские поля.

Пример:

{
  validationSchema: {
    project: {
      properties: {
        customField: {
          type: "string",
          description: "Пользовательское поле"
        },
        version: {
          type: "string",
          pattern: "^\\d+\\.\\d+\\.\\d+$"
        }
      },
      required: ["customField"]
    }
  }
}

tasks

Тип: ProjectSchemaExtensionTasks

Обязательное: Нет

Регистрирует валидацию типов задач. Ключ - имя определения схемы, значение - описание типа задачи и её опций.

Ключ "*" задает дополнительные свойства конфигурации, применяемые ко всем типам задач.

Пример:

{
  validationSchema: {
    tasks: {
      "*": {
        properties: {
          timeout: {
            type: "number",
            minimum: 0
          }
        }
      },
      "SomePlugin_SomeTask": {
        type: "some-task",
        options: {
          type: "object",
          properties: {
            url: { type: "string" }
          },
          required: ["url"],
          additionalProperties: false
        }
      }
    }
  }
}

Использование в конфигурации проекта:

{
  "tasks": [
    {
      "id": "task1",
      "type": "some-task",
      "timeout": 5000,
      "options": {
        "url": "https://example.com"
      }
    }
  ]
}

actions

Тип: ProjectSchemaExtensionActions

Обязательное: Нет

Регистрирует валидацию типов действий. Ключ - имя определения схемы, значение - описание типа действия и его опций.

Ключ "*" задает дополнительные свойства конфигурации, применяемые ко всем действиям.

Пример:

{
  validationSchema: {
    actions: {
      "*": {
        properties: {
          retryCount: {
            type: "number",
            minimum: 0
          }
        }
      },
      "SomePlugin_SomeAction": {
        type: "some-action",
        options: {
          type: "object",
          properties: {
            message: { type: "string" }
          },
          required: ["message"],
          additionalProperties: false
        }
      }
    }
  }
}

Использование в конфигурации проекта:

{
  "triggers": [
    {
      "id": "trigger1",
      "type": "interval",
      "action": {
        "type": "some-action",
        "retryCount": 3,
        "options": {
          "message": "Hello World"
        }
      },
      "options": {
        "interval": 1000
      }
    }
  ]
}

triggers

Тип: ProjectSchemaExtensionTriggers

Обязательное: Нет

Регистрирует валидацию типов триггеров. Ключ - имя определения схемы, значение - описание типа триггера и его параметров.

Ключ "*" задает дополнительные свойства конфигурации, применяемые ко всем типам триггеров.

Пример:

{
  validationSchema: {
    triggers: {
      "*": {
        properties: {
          delay: {
            type: "number"
          }
        }
      },
      "SomePlugin_FileWatcherTrigger": {
        type: "file-watcher",
        options: {
          type: "object",
          properties: {
            path: { type: "string" },
            pattern: { type: "string" }
          },
          required: ["path"],
          additionalProperties: false
        }
      }
    }
  }
}

Использование в конфигурации проекта:

{
  "triggers": [
    {
      "id": "watcher1",
      "type": "file-watcher",
      "delay": 100,
      "action": {
        "type": "emit-event",
        "options": {
          "event": "file-changed"
        }
      },
      "options": {
        "path": "./src",
        "pattern": "**/*.ts"
      }
    }
  ]
}

definitions

Тип: Record<string, unknown>

Обязательное: Нет

Добавляет дополнительные определения схемы, которые могут быть использованы через $ref в других частях схемы.

Пример:

{
  validationSchema: {
    definitions: {
      "CustomType": {
        type: "object",
        properties: {
          name: { type: "string" },
          value: { type: "number" }
        },
        required: ["name", "value"]
      }
    },
    project: {
      properties: {
        customConfig: {
          $ref: "#/$defs/CustomType"
        }
      }
    }
  }
}

Полный пример

{
  validationSchema: {
    // расширение корневой схемы проекта
    project: {
      properties: {
        apiKey: {
          type: "string",
          minLength: 32
        },
        environment: {
          type: "string",
          enum: ["development", "staging", "production"]
        }
      },
      required: ["apiKey"]
    },
    // новый тип задачи + допонительное свойство для всех типов задач
    tasks: {
      "*": {
        properties: {
          timeout: {
            type: "number",
            minimum: 0
          }
        }
      },
      "SomePlugin_HttpRequestTask": {
        type: "http-request",
        options: {
          type: "object",
          properties: {
            url: { type: "string", format: "uri" },
            method: {
              type: "string",
              enum: ["GET", "POST", "PUT", "DELETE"]
            },
            headers: {
              type: "object",
              additionalProperties: { type: "string" }
            }
          },
          required: ["url", "method"],
          additionalProperties: false
        }
      }
    },
    // новый тип действия + дополнительное свойство для всех действий
    actions: {
      "*": {
        properties: {
          retryCount: {
            type: "number",
            minimum: 0
          }
        }
      },
      "SomePlugin_SendNotification": {
        type: "send-notification",
        options: {
          type: "object",
          properties: {
            channel: { type: "string" },
            message: { type: "string" }
          },
          required: ["channel", "message"],
          additionalProperties: false
        }
      }
    },
    // новый тип триггера + дополнительное свойство для всех типов триггров
    triggers: {
      "*": {
        properties: {
          delay: {
            type: "number"
          }
        }
      },
      "SomePlugin_CronTrigger": {
        type: "cron",
        options: {
          type: "object",
          properties: {
            schedule: {
              type: "string",
              pattern: "^(@(annually|yearly|monthly|weekly|daily|hourly|reboot))|(@every (\\d+(ns|us|µs|ms|s|m|h))+)|((((\\d+,)+\\d+|(\\d+([/\\-])\\d+)|\\d+|\\*) ?){5,7})$"
            }
          },
          required: ["schedule"],
          additionalProperties: false
        }
      }
    },
    // дополнительные определения
    definitions: {
      "SomePlugin_Credentials": {
        type: "object",
        properties: {
          username: { type: "string" },
          password: { type: "string" }
        },
        required: ["username", "password"]
      }
    }
  }
}

Ограничения

• типы задач, действий и триггеров должны быть уникальными в рамках всего проекта
• при попытке зарегистрировать уже существующий тип будет выброшена ошибка RuniumError
• схема валидации должна соответствовать спецификации JSON Schema Draft 2020-12

TIP

Для создания уникальных имен типов рекомендуется использовать префикс в виде имени плагина.