ProjectSchemaExtension

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

Свойства

Наименование	Тип	Обязательное
project	ProjectSchemaExtensionProject	Нет
tasks	Record<string, ProjectSchemaExtensionTask>	Нет
actions	Record<string, ProjectSchemaExtensionAction>	Нет
triggers	Record<string, ProjectSchemaExtensionTrigger>	Нет
definitions	Record<string, unknown>	Нет

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

ProjectSchemaExtensionProject

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

ProjectSchemaExtensionTask

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

ProjectSchemaExtensionAction

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

ProjectSchemaExtensionTrigger

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

Описание

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

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

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

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

project

Тип: ProjectSchemaExtensionProject

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

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

Пример:

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

tasks

Тип: Record<string, ProjectSchemaExtensionTask>

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

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

Пример:

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

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

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

actions

Тип: Record<string, ProjectSchemaExtensionAction>

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

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

Пример:

{
  validationSchema: {
    actions: {
      "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",
        "options": {
          "message": "Hello World"
        }
      },
      "options": {
        "interval": 1000
      }
    }
  ]
}

triggers

Тип: Record<string, ProjectSchemaExtensionTrigger>

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

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

Пример:

{
  validationSchema: {
    triggers: {
      "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",
      "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: {
      "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: {
      "SomePlugin_SendNotification": {
        type: "send-notification",
        options: {
          type: "object",
          properties: {
            channel: { type: "string" },
            message: { type: "string" }
          },
          required: ["channel", "message"],
          additionalProperties: false
        }
      }
    },
    // новый тип триггера
    triggers: {
      "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

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