rst-test-spec-schema.yaml

openapi: 3.1.0

info:
  title: Schema for the RST Test Specifications
  version: 1.15.0
  description: |
    This file contains a schema which describes the RST Test Specifications YAML
    format.

components:
  schemas:
    rstTestSpec:
      additionalProperties: false
      description: |
        The `rstTestSpec` schema describes the format of the RST Test
        Specifications YAML format.
      type: object
      required:
        - RST-Test-Plan-Schema-Version
        - Version
        - Preamble
        - ChangeLog
        - Contact
        - Configuration
        - Test-Plans
        - Test-Suites
        - Test-Cases
        - Input-Parameters
        - Resources
        - Errors
        - Data-Providers

      properties:
        RST-Test-Plan-Schema-Version:
          description: |
            This property conforms to the [Semantic Versioning](https://semver.org)
            convention, and tracks the version of **this** document, and is
            updated whenever a material change to the schema is made. Its value
            is always equal to the value of the `info.version` property of
            *this* schema.
          type: string
          pattern: ^\d+\.\d+\.\d+$

        Version:
          description: |
            A string containing the semantic version number for the
            specification itself.
          type: string
          pattern: ^\d+\.\d+\.\d+$

        Preamble:
          description: |
            A description of the contents of the file, in Markdown format.
          type: string

        ChangeLog:
          description: |
            A log of all changes made to the specification. The object property
            names are dates in `YYYY-MM-DD` format, and the values are arrays
            of Markdown text.
          type: object
          patternProperties:
            "^[0-9]{4}-[0-9]{2}-[0-9]{2}$":
              type: array
              items:
                type: string

        Contact:
          description: A `rstTestSpecContact` object.
          type: object
          schema:
            $ref: "#/components/schemas/rstTestSpecContact"

        Configuration:
          description: |
            A collection of configuration parameters for the RST test system
            itself.
          type: array
          items:
            type: object
            required:
              - Name
              - Value
            properties:
              Name:
                description: The name of the parameter.
                type: string
              Value:
                description: The value of the parameter.
                type: string

        Test-Plans:
          description: An object containing Test Plan objects.
          type: object
          patternProperties:
            "^.+$":
              type: object
              schema:
                $ref: "#/components/schemas/rstTestPlan"
        Test-Suites:
          description: An object containing Test Suite objects.
          type: object
          patternProperties:
            "^.+$":
              type: object
              schema:
                $ref: "#/components/schemas/rstTestSuite"
        Test-Cases:
          description: An object containing Test Suite objects.
          type: object
          patternProperties:
            "^.+$":
              type: object
              schema:
                $ref: "#/components/schemas/rstTestCase"
        Input-Parameters:
          description: An object containing Input Parameter objects.
          type: object
          patternProperties:
            "^.+$":
              type: object
              schema:
                $ref: "#/components/schemas/rstInputParameter"
        Resources:
          description: An object containing Resource objects.
          type: object
          patternProperties:
            "^.+$":
              type: object
              schema:
                $ref: "#/components/schemas/rstResource"
        Errors:
          description: An object containing Error objects.
          type: object
          patternProperties:
            "^.+$":
              type: object
              schema:
                $ref: "#/components/schemas/rstError"
        Data-Providers:
          description: An object containing Data Provider objects.
          type: object
          patternProperties:
            "^.+$":
              type: object
              schema:
                $ref: "#/components/schemas/rstDataProvider"

    rstTestSpecContact:
      additionalProperties: false
      description: |
        An object containing contact information for the maintainer of the RST
        Test Specifications YAML file.
      type: object
      required:
        - Name
        - Organization
        - Email
      properties:
        Name:
          description: Contact name.
          type: string
        Organization:
          description: Contact organization.
          type: string
        Email:
          description: Contact email.
          type: string
          format: email

    rstTestPlan:
      additionalProperties: false
      description: An object describing a test plan.
      type: object
      required:
        - Name
        - Order
        - Description
        - Test-Suites
        - Environments
      properties:
        Name:
          description: The name of the plan.
          type: string
        Order:
          description: |
            The canonical order of the plan (only used to generate the HTML
            representation).
          type: integer
          format: uint8
        Description:
          description: A description of the plan in Markdown format.
          type: string
        Test-Suites:
          description: An array of Test Suite IDs.
          type: array
          items:
            type: string
        OTE-Only:
          description: |
            A boolean indicating that this test plan is only available in OT&E.
            If `false`, then this test plan is available in both production and
            OT&E.
          type: boolean

    rstTestSuite:
      additionalProperties: false
      description: An object describing a test suite.
      type: object
      required:
        - Name
        - Description
        - Test-Cases
        - Input-Parameters
      properties:
        Name:
          description: The name of the suite.
          type: string
        Order:
          description: |
            The canonical order of the suite (only used to generate the HTML
            representation).
          type: integer
          format: uint8
        Description:
          description: A description of the suite in Markdown format.
          type: string
        Test-Cases:
          description: |
            Either an array of test case IDs, or a regular expression used
            to filter them.
          type:
          - array
          - string
        Input-Parameters:
          description: |
            An array of input parameter IDs which must be provided in
            addition to the input parameters specified by the test cases for
            the suite.
          type: array
        Resources:
          description: |
            An array of resource IDs which may be used to prepare for the
            tests in this test suite, in addition to those specified by the
            test cases for the suite.
          type: array

    rstTestCase:
      additionalProperties: false
      description: An object describing a test case.
      type: object
      required:
        - Summary
        - Description
      properties:
        Summary:
          description: A short description of the test case.
          type: string
        Description:
          description: A description of the case in Markdown format.
          type: string
        Dependencies:
          description: An array of dependencies.
          type: array
          items:
            type: string
        Input-Parameters:
          description: |
            An array of input parameter IDs which must be provided in
            addition to the input parameters specified by the test suite(s)
            that use this test case.
          type: array
        Resources:
          description: |
            an array of resource IDs which may be used to prepare for the
            tests in this test suite, in addition to those specified by the
            test suite(s) that use this test case.
          type: array
        Errors:
          description: |
            an array of error IDs which may be produced by this test suite,
            in addition to those specified by the test suite(s) that use
            this test case.
          type: array
        Data-Providers:
          description: |
            An array of Data Provider IDs which identify the Data Provider(s)
            that will be used to perform tests for this test case.
          type: array
      description: An object describing an input parameter.
      type: object
      required:
        - Description
        - Type
      properties:
        Description:
          description: A description of the parameter in Markdown format.
          type: string
        Type:
          description: |
            The type of the parameter, one of `file` or `input`.
          enum:
            - "file"
            - "input"
        Example:
          description: An example value for this parameter.
        Required:
          description: |
            Whether this input parameter is required or optional. If not set,
            then it is optional.
          type: boolean
          default: false
        Schema:
          description: |
            an [OpenAPI `Schema`
            object](https://spec.openapis.org/oas/latest.html#schemaObject)
            which can be used to validate this parameter.
          type: object

    rstResource:
      additionalProperties: false
      description: An object describing a resource.
      type: object
      required:
        - Description
        - URL
      properties:
        Description:
          description: A description of the resource in Markdown format.
          type: string
        URL:
          description: The URL where the resource may be found.
          type: string
          format: url

    rstError:
      additionalProperties: false
      description: An object describing an error message.
      type: object
      required:
        - Description
        - Severity
      properties:
        Description:
          description: A description of the error in Markdown format.
          type: string
        Severity:
          description: The severity of the error.
          enum:
            - INFO
            - NOTICE
            - WARNING
            - ERROR
            - CRITICAL

    rstInputParameter:
      additionalProperties: false
      description: An object describing an input parameter.
      type: object
      required:
        - Description
        - Schema
      properties:
        Description:
          description: A description of the input parameter in Markdown format.
          type: string
        Type:
          description: the type of the parameter.
          type: string
          enum:
            - input
            - file
        Example:
          description: An example value.
        Required:
          description: Whether it is mandatory to provide this value.
          type: boolean
          default: false
        Schema:
          $ref: "https://json-schema.org/draft/2020-12/schema"

    rstDataProvider:
      additionalProperties: false
      description: |
        An object describing a Data Provider.
      type: object
      required:
        - Description
        - Columns
        - Rows
      properties:
        Description:
          description: A description of the Data Provider in Markdown format.
          type: string
        Columns:
          description: A list of columns.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/rstDataProviderColumn"
        Rows:
          description: |
            A two-dimensional array (array of arrays) containing the data.
          type: array
          minItems: 1
          items:
            type: array
            minItems: 1

    rstDataProviderColumn:
      additionalProperties: false
      description: An object describing a column in a data provider.
      type: object
      required:
        - Name
        - Description
        - Type
      properties:
        Name:
          description: The name of the column.
          type: string
        Description:
          description: A description of the column in Markdown format.
          type: string
        Type:
          description: |
            The type of the column. The possible values are a subset of the
            basic JSON Schema types found at
            <https://json-schema.org/understanding-json-schema/reference/type>.
            The permitted values are:

            * `string` - a sequence of Unicode text.
            * `integer` - a positive or negative number with no fractional part.
            * `number` - a positive or negative decimal number which may
              optionally have a fractional part.
            * `boolean` - `true` or `false`.
          type: string
          enum:
            - string
            - integer
            - number
            - boolean