rst-api-spec.yaml.in

openapi: 3.0.3

#mode quote
#define EXTERNAL_USER_ACCESS_CONTROL_POLICY Users can only perform this operation if their certificate matches a `TLSA` record published in the DNS at one of the hostnames specified in the `clientIDs` property of the test request object.
#define INTERNAL_USER_ACCESS_CONTROL_POLICY Internal users can perform this operation on any object.

tags:
  - name: Checking that the server is up
  - name: Creating test request objects
  - name: Providing input parameters & files
  - name: Retrieving test information
  - name: Starting test runs
  - name: Test administration
  - name: IDN table management

info:
  version: "1.#date %Y%j"

  title: ICANN Registry System Testing (RST) API
  contact:
    name: ICANN Global Support
    email: globalsupport@icann.org

  description: |
    The Registry System Testing (RST-API) provides a
    [RESTful](https://en.wikipedia.org/wiki/REST) interface to ICANN's [Registry
    System Testing](https://www.icann.org/resources/registry-system-testing-v2.0)
    platform, which is used to conduct conformance tests of [critical registry
    functions](https://www.icann.org/registry-transition-processes-en#:~:text=Critical%20Functions:,registry%20data%20escrow)
    at various points during the lifecycle of a gTLD (before initial delegation,
    before the [transition to a new Registry Service
    Provider](https://www.icann.org/resources/material-subcontracting-arrangement),
    before the approval of new [registry
    services](https://www.icann.org/resources/pages/rsep-2014-02-19-en)), and
    during [RSP evaluation](https://newgtldprogram.icann.org/en/application-rounds/round2/rsp).

    _Last updated: #date %Y-%m-%d_.

    ### Change Log

    * 2025-02-14:
      * The `testResult` type has been changed to remove the `nullable` setting
        as this was found to cause problems with code generators. Instead, a
        new (and default) value of `not-started` has been added to the enum.
    * 2025-02-12:
      * The `eppSafeCodePoints` property in `idnTable` and `idnTableRequest`
        objects has been updated to allow a sequence of code points, to support
        scripts such as Thaana which have context rules that mean that random
        selection of code points could result in invalid labels.
    * 2025-01-28:
      * The `result` property of test objects is now nullable.
    * 2024-12-11:
      * Fixed the regular expression used to validate members of the
        `eppSafeCodePoints` property of IDN table objects.
    * 2024-11-27:
      * Added the `files-needed` status to test requests to indicate that one or
        more files that must be uploaded before a test run can be started.
      * Added the `missingFiles` property to test objects to provide a list of
        any files that must be uploaded before a test run can be started.
    * 2024-11-13:
      * The `eppSafeCodePoints` property has been added to the `idnTable` and
        `idnTableRequest` object types, to faciliate EPP testing in TLDs which
        have an `idnOnly` property of `true`.
      * The requirement that the `isReferenceLGR` property of IDN table objects
        **MUST** be `true` has been removed.
    * 2024-09-17: The following endpoints responded with a `201` HTTP status,
      when `204` should have been used:
      * `GET /v1/heartbeat`
      * `POST /v1/test/{id}/inputs`
      * `POST /v1/test/{id}/files`
      * `POST /v1/test/{id}/result`
      * `PUT /v1/table/{id}`
      * `DELETE /v1/table/{id}`
    * 2024-09-12: Clarified access control rules for IDN table objects so users
      can always access the objects they created.
    * 2024-09-04:
      * Full test run information is no longer in responses to `GET /v1/test/{id}`
        requests, which will instead include a link to a `GET /v1/test/{id}/{runID}`
        sub-resource.
      * added `cancelled` to the `testResult` enum.
      * allow administrators to change the status of a test to `cancelled`.
      * added the `INFO` severity to the enum of allowed values for the
        `severity` property of `testCaseLogMessage` objects.
      * the `context` property of `testCaseLog` objects has been removed, the
        information will be included in the `log` property instead.
    * 2024-08-07:
      * The response to `GET /v1/tests` and `GET /v1/tables` requests now
        include summaries of the matching objects (`testRequestSearchResult`
        and `idnTableSearchResult`), rather than the full objects.
    * 2024-07-31:
      * Fixed the JSON examples in the description of the `tlds` property of
        `testRequest` and `testRequestSubmitted` objects.
    * 2024-07-03:
      * `x-constraints` properties have been added to input parameter schemas,
        where appropriate, to facilitate automated validation in Java
        applications.
      * When creating tests in the OT&E environment, the `rsp` and `clientIDs`
        **MUST** now be specified and **MUST** contain the FQDN at which a TLSA
        record that validates the client certificate is published.
    * 2024-06-26:
      * added the `/v1/resource/{file}` endpoint.
    * 2024-06-05:
      * added the `errorCode` property to `rstError` objects.
      * As per Public Comment feedback, clarified that for TLDs that are not
        subject to rules relating to the allocatability of IDN variants, the
        `variants` property of `idnTestLabel` objects **MUST** be empty.
    * 2024-05-16:
      * Significant overhaul of the structure of the `idnTableRef`,
        `idnTableRequest` and `idnTable` schemas, based on internal discussions
        regarding requirements for IDN variants. A reference implementation of
        the algorithm for computing lists of test domains is also [available in
        the GitHub repository](/~https://github.com/icann/rst-api-spec/blob/dev/etc/idn-test-reference.js).
      * Added the `idnOnly` property to `tldInfo` objects.
      * Defined a new `rstError` object type which describes the response body
        used whenever there is an error.
      * Clarified that input parameters can still be submitted when a test
        has the `inputs-complete` status.
      * Added the `heartbeat` operation to test that the service is up.
      * Moved the `/v1` prefix from the `servers` part of the spec into the
        individual `paths`.
      * Extract the schema for files included in `testRequestSubmitted` into
        `fileRef`.
    * 2024-03-20:
      * The `id` property of `testRequestSubmitted` objects is now a string, not
        and integer.
    * 2024-03-13:
      * Variant labels in an IDN table may have exceptional allocation policies
        when allocated in the same TLD as the primary label, or in a variant
        TLD.
    * 2024-03-06:
      * the `caseId` property of the `testCaseLog` object, and the `code`
        property of the `testCaseLogMessage` object are now enums, which are
        generated from the test specs.
    * 2024-02-28:
      * As per the last release, only a single YAML file is now built from the
        source file, that contains both "internal" and "external" endpoints. The
        "internal" view is no longer published.
      * To work better with code generators, the following changes have been
        made:
        * The specification now conforms to [v3.0.3](https://spec.openapis.org/oas/v3.0.3)
          of the OpenAPI specification instead of v3.1.0. This means that many
          aspects of the API specification and object schemas (including those
          of input parameters) have been changed to avoid using features only
          available in v3.1.0 of the OpenAPI spec. This includes the `examples`
          property for all JSON types, which means that the examples shown in
          the HTML representation of the API spec are now less useful than they
          were previously.
        * The following changes have been made to `testCaseLog` objects:
          * The `code` and `codeRef` properties are now optional instead of
            nullable.
          * The `context` property has been changed so that property values are
            always strings.
        * The `securitySchemes` property has been removed, since code generators
          don't seem to offer good support for mutual TLS. The requirement for
          client TLS authentication has not changed, however.
        * All usages of the `patternProperties`  feature of JSON Schema have
          been changed to avoid their use. Some may still be present in the
          input parameters.
      * Changes to IDN table objects:
        * The `variants` property of entries in the `validLabels` property of
          `idnTable` objects has been changed to an array of objects, so the
          corresponding language tag can be included.
        * The `lgrXML` property of `idnTable` object has been removed.
        * Renamed the `supportLevel` property to `variantSupportLevel`.
        * The operation to create a new IDN table object uses `idnTableRequest`
          as the request body payload, which does not allow for inclusion of
          server-generated object properties.
        * In OT&E, only Reference Second-Level LGRs can be used.
      * `type` properties for `enum` types have been reinstated.
    * 2024-02-21:
      * Test properties (such as `applicationId` and `rsp`) that were previously
        ignored in OT&E now **MUST** be omitted.
      * When IDN table objects are created in OT&E, they **MUST** have a
        `isReferenceLGR` property that is `true`.
      * Simplified object schemas by marking properties as required (and others
        as therefore optional) avoiding the need to have nullable properties.
      * IDN tables are now referenced by a unique ID rather than the `{rsp, tag,
        version}` triple.
      * The internal and external views are now identical. The separate files
        will be removed in the next release.
      * Added the `supportLevel` property to the `idnTableRef` type.
      * Some IDN table management endpoints are now accessible to external
        clients.
      * Make access control policies clearer and more consistent.
      * Remove `DELETE /tests/{id}` endpoint.
      * Fix schema definition for the `Location` header in `POST /test`
        responses.
      * Changes only relevant to internal users:
        * Change the `client` parameter to `GET /tests` to `rsp`.
        * Reinstate query parameters for `GET /tables`.
        * The `PATCH /test/{id}` endpoint has been replaced with `POST
          /test/{id}/run` and `POST /test/{id}/result`.
        * Simplified IDN table management, so that test labels are provided when
          the table object is created.

    * 2024-02-14:
      * Switch to a weekly release cycle.
      * Use a date-based version number instead of a commit-based version, ahead
        of switching to a weekly release cycle.

    * 2024-01-31:
      * Add this change log.
      * Minimise the delta between the internal and external view.

    ### Authentication

    All access to the API is authenticated using TLS certificates that are
    authenticated using `TLSA` records published in the DNS. For more
    information, please consult [the RST v2.0 page on the ICANN
    website](https://www.icann.org/resources/registry-system-testing-v2.0/#authentication-and-access-control).

    _Copyright #date %Y ICANN. All rights reserved._

    _[RST-API Specification Home Page](https://icann.github.io/rst-api-spec/)_

servers:
  - url: https://rst-api.icann.org
    description: Production server address
  - url: https://rst-api-ote.icann.org
    description: OT&E server address

paths:
  /v1/heartbeat:
    get:
      tags:
        - Checking that the server is up
      description: |
        This operation can be used to determine if the server is up.
      operationId: heartbeat
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '204':
          description: A successful result.

  /v1/test:
    post:
      tags:
        - Creating test request objects
      description: |
        This operation creates a new test request object.

        This operation is not available to external users in production, but may
        be used in OT&E.
      operationId: createTest
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/testRequest"
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '200':
          description: A successful result.
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/testRequestSubmitted"
          headers:
            location:
              description: The URL of the newly created test request object.
              schema:
                type: string
                format: url
                x-constraints: "@ValidUrl"

  /v1/test/{id}:
    parameters:
      - name: id
        description: The test ID
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Retrieving test information
      description: |
        This operation returns information about a specific test request object.

        EXTERNAL_USER_ACCESS_CONTROL_POLICY

        INTERNAL_USER_ACCESS_CONTROL_POLICY
      operationId: getTestInfo
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '200':
          description: A successful result.
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/testRequestSubmitted"

  /v1/test/{id}/inputs:
    post:
      tags:
        - Providing input parameters & files
      description: |
        This operation submits test input parameters. Parameters in the payload
        will previously submitted values. Values that are present in the object
        but not present in the payload will not be modified.

        Input parameters can only be submitted for test request objects that
        have the status of `inputs-needed`.

        EXTERNAL_USER_ACCESS_CONTROL_POLICY

        INTERNAL_USER_ACCESS_CONTROL_POLICY

        Once all required input parameters have been submitted (and any files
        referenced in those parameters have been uploaded), the status of
        the test request object will change from `input-needed` to
        `inputs-complete`.
      operationId: setTestInputParameters
      parameters:
        - name: id
          description: The test ID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/inputParameters"
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '204':
          description: A successful result.

  /v1/test/{id}/files:
    post:
      tags:
        - Providing input parameters & files
      description: |
        This resource may be used to upload files. Multiple files may
        be uploaded in a single request. If a filename matches a previously
        submitted file, that file will be replaced.

        All files MUST be referenced in an input parameter **before** being
        uploaded.

        EXTERNAL_USER_ACCESS_CONTROL_POLICY

        INTERNAL_USER_ACCESS_CONTROL_POLICY
      operationId: uploadFile
      parameters:
        - name: id
          description: The test ID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '204':
          description: A successful result.

  /v1/test/{id}/file/{file}:
    get:
      tags:
        - Retrieving test information
      description: |
        This retrieves an uploaded file.

        EXTERNAL_USER_ACCESS_CONTROL_POLICY

        INTERNAL_USER_ACCESS_CONTROL_POLICY
      operationId: getFile
      parameters:
        - name: id
          description: The test ID
          in: path
          required: true
          schema:
            type: string
        - name: file
          description: The file name
          in: path
          required: true
          schema:
            type: string
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '200':
          description: A successful result.
          content:
            "*":
              schema:
                type: string
                format: binary

  /v1/test/{id}/run:
    parameters:
      - name: id
        description: The test ID
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Starting test runs
      operationId: startTestRun
      description: |
        This operation asks the test system to start a new test run. If test
        object's status property is `inputs-complete`, a `201` status will be
        returned; otherwise a `400` status will be returned.
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '201':
          description: A succesful result.

  /v1/test/{id}/run/{runID}:
    parameters:
      - name: id
        description: The test ID
        in: path
        required: true
        schema:
          type: string
      - name: runID
        description: The test run ID
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Retrieving test information
      operationId: getTestRun
      description: This operation retrieves details of a test run.
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '200':
          description: A successful result.
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/testRunLog"

  /v1/test/{id}/result:
    parameters:
      - name: id
        description: The test ID
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Test administration
      operationId: setTestResult
      description: |
        **Internal users only**

        This operation allows the `result` property of a test request to be
        overridden. The current value of this propert **MUST** be either
        `exception` or `fail`.
      requestBody:
        content:
          'application/x-www-form-urlencoded':
            schema:
              type: object
              required:
                - result
              properties:
                result:
                  description: The new result for the test.
                  type: string
                  enum:
                    - pass
                    - cancelled
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '204':
          description: A succesful result.

  /v1/tests:
    get:
      tags:
        - Retrieving test information
      description: |
        This operation performs a search on the database and returns all
        matching results.

        External users will only see results where their certificate
        matches a `TLSA` record published in the DNS at one of the hostnames
        specified in the `clientIDs` property of the test request object.

        Internal users will see results for all users.
      operationId: getTests
      parameters:
        - name: rsp
          description: limit results to a specific RSP (internal users only).
          in: query
          required: false
          schema:
            type: string
        - name: tld
          description: limit results to a specific TLD (internal users only).
          in: query
          required: false
          schema:
            type: string
        - name: applicationID
          description: |
            limit results to specific a application ID (internal users only).
          in: query
          required: false
          schema:
            type: string
        - name: status
          description: limit results to those with the given status.
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/testStatus"
        - name: result
          description: limit results to those with the given result.
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/testResult"
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '200':
          description: A successful result.
          content:
            "application/json":
              schema:
                type: array
                minItems: 0
                items:
                  $ref: "#/components/schemas/testRequestSearchResult"

  /v1/table:
    post:
      tags:
        - IDN table management
      operationId: createIDNTable
      description: |
        This operation creates a new IDN table object.

        IDN table objects must be created before they can be referenced in a
        test request.

        This operation is not available to external users in production, but may
        be used in OT&E.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/idnTableRequest"
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '201':
          description: A successful result.
          headers:
            location:
              description: The URL of the newly created IDN table object.
              schema:
                type: string
                format: url
                x-constraints: "@ValidUrl"

  /v1/table/{id}:
    parameters:
      - name: id
        description: The table ID.
        in: path
        required: true
        schema:
          type: string

    get:
      tags:
        - IDN table management
      operationId: getIDNTable
      description: |
        This operation returns information about an IDN table object.

        External users can only access IDN tables that are linked to test
        objects associated with their credentials, or which they created.

        INTERNAL_USER_ACCESS_CONTROL_POLICY
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '200':
          description: A successful result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/idnTable"

    put:
      tags:
        - IDN table management
      operationId: updateIDNTable
      description: |
        This operation updates an existing IDN table object.

        External users can only access IDN tables that are linked to test
        objects associated with their credentials.

        This operation is not available to external users in production, but may
        be used in OT&E.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/idnTableRequest"
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '204':
          description: A successful result.

    delete:
      tags:
        - IDN table management
      operationId: deleteIDNTable
      description: |
        This operation deletes an IDN table object.

        External users can only access IDN tables that are linked to test
        objects associated with their credentials.

        This operation is not available to external users in production, but may
        be used in OT&E.

        INTERNAL_USER_ACCESS_CONTROL_POLICY
      responses:
        '204':
          description: A successful result.

  /v1/tables:
    get:
      tags:
        - IDN table management
      operationId: getIDNTables
      description: |
        This operation returns the IDN tables matching the provided query
        parameters.

        External users can only access IDN tables that are linked to test
        objects associated with their credentials, or which they created.

        INTERNAL_USER_ACCESS_CONTROL_POLICY
      parameters:
        - name: rsp
          description: The RSP ID (internal users only).
          in: query
          required: false
          schema:
            type: string
        - name: tag
          description: The language tag.
          in: query
          required: false
          schema:
            type: string
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '200':
          description: A successful result.
          content:
            "application/json":
              schema:
                type: array
                minItems: 0
                items:
                  $ref: "#/components/schemas/idnTableSearchResult"

  /v1/resource/{file}:
    get:
      tags:
        - Providing input parameters & files
      operationId: getResource
      description: |
        This endpoint allows users to download [resources](https://icann.github.io/rst-test-specs/rst-test-specs.html#resources)
        which may be useful in preparing registry systems for testing.

        There is no authentication on this endpoint.
      parameters:
        - name: file
          description: The name of the resource.
          in: path
          required: true
          schema:
            type: string
            enum:
#exec bin/generate-resource-names.pl | sed 's/^/              /'
      responses:
#exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
        '200':
          description: A successful result.
          content:
            "*":
              schema:
                type: string
                format: binary

components:

  schemas:

    rstError:
      description: |
        This object type represents error messages returned in responses to
        requests that could not be successfully completed.
      type: object
      required:
        - status
        - message
      properties:
        status:
          description: The HTTP status.
          type: integer
          enum:
#exec gpp -x inc/http-errors.yaml | yq -r '. | keys' | tr -d "'" | sed 's/^/            /'
        errorCode:
          description: The application-specific error code.
          type: integer
          example: 1400
        message:
          description: A human-readable description of the error.
          type: string
          example: "Bad request"

    testRequest:
      description: |
        This object type is used to define the properties of a new test request
        object. The `testRequestSubmitted` type inherits from it.
      type: object
      required:
        - tlds
        - rsp
        - clientIDs
        - testPlan
      properties:
#exec gpp -x inc/test-request-base-properties.yaml | sed 's/^/        /'

    testStatus:
      description: |
        A string indicating the status of a test request object.

        1. The `inputs-needed` value indicates that the request has been
           received, but one or more input parameters are needed before a test
           run can begin. The `missingInputs` property of the test indicates
           which input parameters are missing.
        2. The `files-needed` value indicates that the request has been
           received, but one or more files are needed before the a test run can
           begin. The `missingFiles` property of the test indicates which files
           are missing.
        3. The `inputs-complete` value indicates that all the required
           input parameters and files have been provided. The test is therefore
           ready to start. It is still possible to update input parameters if
           the test has this status.
        4. The `in-progress` value indicates that a test run is in progress.
        5. The `completed` value indicates that the test run has completed. If
           a test object has this status, then its `result` property will
           indicate the outcome of the test.
        6. The `expired` value indicates that the test did not have a status
           of `completed` when the `dueDate` was reached.

        * [State diagram](etc/test-object-state-machine.svg)
      type: string
      enum:
        - inputs-needed
        - files-needed
        - inputs-complete
        - in-progress
        - completed
        - expired

    testResult:
      description: |
        A string indicating the result of a test run.

        1. If no test run has been requested for a test object, this property
           will be `not-started`.
        2. The `in-progress` value indicates that the test run has not yet
           finished.
        3. The `pass` value indicates that the test run completed with no
           errors.
        4. The `fail` value indicates that at least one test case failed.
        5. The `exception` value indicates that an internal issue prevented
           the test run from completing.
        6. The `cancelled` value indicates that the test was cancelled by an
           administrator.
      type: string
      enum:
        - not-started
        - in-progress
        - pass
        - fail
        - exception
        - cancelled

    idnTableRef:
      description: |
        An `idnTableRef` object provides a reference to an IDN table object. IDN
        table objects must be created prior to being referenced in a test
        request.
      type: object
      required:
        - id
        - variantPolicy
      properties:
        id:
          description: The unique ID of the table.
          type: string
          example: c76e47a4-b1c5-40a8-94ae-30f0f60f7ec4
        variantPolicy:
          $ref: "#/components/schemas/variantPolicy"

    tldInfo:
      description: |
        A top-level domain (or equivalent registry-class domain name) and its
        associated IDN tables.
      type: object
      required:
        - name
        - idnTables
      properties:
        name:
          description: The TLD (or equivalent registry-class domain name).
          type: string
          format: hostname
          example: example
        idnTables:
          description: The IDN tables(s) for the TLD.
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/idnTableRef"
        idnOnly:
          description: |
            A boolean vaue that indicates whether only IDN domains may be
            registered under this TLD. If the value is `false` then domains that
            only use the ASCII range are also permitted.
          type: boolean
          default: false

    testRequestSearchResult:
      description: |
        An abbreviated representation of a test object that is included in
        search result.
      type: object
      required:
        - testID
        - status
        - result
        - tlds
        - href
      properties:
        testID:
          description: The unique ID for this test request object.
          type: string
          example: 3aebd167-c275-45b6-842a-2680ed80422b
        rsp:
          description: The RSP's unique ID.
          type: string
          example: RSPI2404-M51
        status:
          $ref: "#/components/schemas/testStatus"
        result:
          $ref: "#/components/schemas/testResult"
        href:
          description: The URL for this test request object.
          type: string
          format: url
          x-constraints: "@ValidUrl"
          example: /v1/test/3aebd167-c275-45b6-842a-2680ed80422b
        tlds:
          description: A flat list of the TLD(s) for this test.
          type: array
          minItems: 1
          items:
            type: string
            format: hostname
            example: example

    testRequestSubmitted:
      description: |
        This type describes a test request object that has been successfully
        submitted. It inherits all the properties defined in the
        `testRequest` type.
      type: object
      required:
        - tlds
        - rsp
        - createdBy
        - clientIDs
        - testPlan
        - testPlanVersion
        - dateRequested
        - status
        - result
        - inputs
      properties:
#exec gpp -x inc/test-request-base-properties.yaml | sed 's/^/        /'

        createdBy:
          description: The ID of the client that created this object.
          type: string
          format: hostname
          x-constraints: "@ValidHostname"
          example: tlsa.rsp.example

        testID:
          description: The unique ID for this test request object.
          type: string
          example: 3aebd167-c275-45b6-842a-2680ed80422b

        testPlanVersion:
          description: |
            The version of the Test Plan that will be used for the test. This
            will be determined using the `Version` property of the [RST Test
            Specifications](https://icann.github.io/rst-test-specs/rst-test-specs.html)
            and follows the [Semantic Versioning](https://semver.org)
            convention.
          type: string
          pattern: "^\\d+(\\.\\d+)+$"
          example: "3.1.2024096"

        dateRequested:
          description: date/time when this request was submitted.
          type: string
          format: date-time

        dateUpdated:
          description: date/time when this request was last updated.
          type: string
          format: date-time

        dateStarted:
          description: date/time when the test run (if any) started.
          type: string
          format: date-time

        dateCompleted:
          description: date/time when the test run (if any) completed.
          type: string
          format: date-time

        status:
          $ref: "#/components/schemas/testStatus"

        result:
          $ref: "#/components/schemas/testResult"

        errorCodes:
          description: |
            If the result of the test is a fail or an error, then this property
            will contain any `ERROR` or `CRITICAL` error codes generated by the
            test run. Otherwise it will be omitted.
          type: array
          minItems: 0
          items:
            type: string
            enum:
#exec sed 's/^/              /' tmp/error-codes.yaml

        inputs:
          $ref: "#/components/schemas/inputParameters"

        missingInputs:
          description: |
            An array listing any required input parameters that have not yet
            been provided.
          type: array
          minItems: 0
          items:
            type: string
            enum:
#exec yq '. | keys' tmp/input-parameters.yaml | sed 's/^/              /'

        files:
          description: A list of any files uploaded.
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/fileRef"

        missingFiles:
          description: A list of any files that have not yet been uploaded.
          type: array
          minItems: 0
          items:
            type: string

        results:
          description: |
            The `results` property is an array of objects. It property will
            initially be an empty array, until a test run is started.
          type: array
          minItems: 0
          items:
            type: object
            description: |
             An abbreviated representation of a test run.
            required:
              - runID
              - dateStarted
              - dateCompleted
              - result
              - href
            properties:
              runID:
                description: unique ID for this test run.
                type: string
                example: 3ed892dd-2b29-4f59-b024-653345067547
              dateStarted:
                description: The date and time the run started.
                type: string
                format: date-time
              dateCompleted:
                description: The date and time the run started.
                type: string
                format: date-time
              result:
                $ref: "#/components/schemas/testResult"
              href:
                description: The URL of the test run log.
                type: string
                format: url
                x-constraints: "@ValidUrl"
                example: /v1/test/3aebd167-c275-45b6-842a-2680ed80422b/run/3ed892dd-2b29-4f59-b024-653345067547

    inputParameters:
      description: |
        Users must provide various input parameters to be used within test
        cases. An `inputParameters` object is used when users submit these
        parameters after a test request object is created, and is also used when
        returning test request object information.
      type: object
      properties:
#exec sed 's/^/        /' tmp/input-parameters.yaml
      required: []

    testRunLog:
      description: An object representing a discrete test run.
      type: object
      required:
        - runID
        - dateStarted
        - result
        - log
      properties:
        runID:
          description: unique ID for this test run.
          type: string
          example: 3ed892dd-2b29-4f59-b024-653345067547
        dateStarted:
          description: The date and time the run started.
          type: string
          format: date-time
        dateCompleted:
          description: |
            The date and time the run finished. For `in-progress` runs, this
            property will be omitted.
          type: string
          format: date-time
        result:
          $ref: "#/components/schemas/testResult"
        log:
          description: an array of test case log objects.
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/testCaseLog"

    testCaseLog:
      description: A detailed log of an individual test case.
      type: object
      required:
        - caseID
        - caseRef
        - result
        - description
        - dateStarted
        - dateCompleted
        - log
      properties:
        caseID:
          description: The Test Case ID.
          type: string
          enum:
#exec sed 's/^/            /' tmp/test-cases.yaml

        caseRef:
          description: A link to the test case specification.
          type: string
          format: url
          x-constraints: "@ValidUrl"
          example: https://icann.github.io/rst-test-specs/rst-test-specs.html#Test-Case-dns-address01

        result:
          description: |
            The result of the test. The possible values are:
            * `pass` - the test passed.
            * `fail` - the test was not passed.
            * `exception` - an error occurred which meant a result could not be
              determined. This indicates an issue on the RST test system side,
              not the test subject's.
            * `skipped` - the test case was not applicable and was not carried
              out.
            * `aborted` - the test case was aborted before it could complete.
          type: string
          enum:
            - pass
            - fail
            - exception
            - skipped
            - aborted
        description:
          description: A short description of the outcome of the test.
          type: string
          example: All nameserver IP addresses are globally routable.
        dateStarted:
          description: date/time when the test case started.
          type: string
          format: date-time
        dateCompleted:
          description: date/time when the test case finished.
          type: string
          format: date-time
        log:
          description: detailed test logs
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/testCaseLogMessage"

    testCaseLogMessage:
      description: A log message.
      type: object
      required:
        - severity
        - timestamp
        - message
      properties:
        code:
          description: The error code (if any).
          type: string
          enum:
#exec sed 's/^/            /' tmp/error-codes.yaml

        codeRef:
          description: a link to a description for the error code (if any).
          type: string
          format: url
          x-constraints: "@ValidUrl"
          example: https://icann.github.io/rst-test-specs/rst-test-specs.html#Error-DNSSEC_DNS_QUERY_ERROR

        severity:
          description: |
            The log level of the message, a subset of the values defined in
            RFC5424.
          type: string
          enum:
            - INFO
            - WARNING
            - ERROR
            - CRITICAL
        timestamp:
          description: The timestamp when the message was generated.
          type: string
          format: date-time
        message:
          description: The message.
          type: string
          example: An error occurred while performing DNS query(s).

    idnTableRequest:
      description: |
        This object describes an IDN table, or more specifically, an RSP's
        implementation of such a table.

        In OT&E, the `isReferenceLGR` property **MUST** be `true`, and the
        `testLabels` property **MUST** be omitted.
      type: object
      required:
        - tag
        - version
        - isReferenceLGR
        - permittedVariantPolicies
      properties:
#exec gpp -x inc/idn-table-request-base-properties.yaml | sed 's/^/        /'

    idnTable:
      description: |
        This object describes an IDN table, or more specifically, an RSP's
        implementation of such a table.
      type: object
      required:
        - tableID
        - active
        - rsp
        - tag
        - version
        - isReferenceLGR
        - permittedVariantPolicies
      properties:
        tableID:
          description: A unique ID for this table.
          type: string
          example: 3f07afce-cc4c-4cd8-b1ca-391167b7c6f4

#exec gpp -x inc/idn-table-request-base-properties.yaml | sed 's/^/        /'

    idnTableSearchResult:
      description: |
        An abbreviated representation of an IDN table object that is included in
        search result.
      required:
        - tableID
        - href
        - rsp
        - tag
        - version
      properties:
        tableID:
          description: A unique ID for this table.
          type: string
          example: 3f07afce-cc4c-4cd8-b1ca-391167b7c6f4
        href:
          description: The URL for this object.
          type: string
          format: url
          x-constraints: "@ValidUrl"
          example: /v1/table/3f07afce-cc4c-4cd8-b1ca-391167b7c6f4
        rsp:
          description: The RSP ID.
          type: string
          example: RSPI2404-M51
        tag:
          description: The language tag.
          type: string
          example: ar-Arab
        version:
          description: The version number.
          type: string
          example: "1.0"

    idnTestLabels:
      description: An object containing IDN test labels.
      type: object
      required:
        - allocatableLabels
        - unallocatableLabels
      properties:
        allocatableLabels:
          description: |
            A list of **allocatable** IDN labels, and any variant labels
            thereof.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/idnTestLabel"

        unallocatableLabels:
          description: |
            A list of **unallocatable** IDN labels that it should not be
            possible to register.
          type: array
          minItems: 1
          items:
            description: An IDN label in either A-label or U-label format.
            type: string
            example: xn--g28h

    idnTestLabel:
      description: |
        An object describing an allocatable IDN test label and any variants.
      type: object
      required:
        - label
        - variantTLDAllocatability
        - variants

      properties:
        label:
          description: The primary label in either A-label or U-label format.
          type: string
          example: "اِختِصاص"

        remark:
          description: Useful remarks about the label.
          type: string
          example: This is an illustrative example.

        variantTLDAllocatability:
          description: |
            A list of language tags that this label is valid in, in addition to
            the table in question. In the context of a set of variant TLDs, this
            property may be used to determine which other TLDs in the set this
            label may be allocated in.
          type: array
          minItems: 0
          items:
            type: string
            example: und-Arab

        variants:
          description: |
            A list of variant labels (if any).

            If a TLD is not subject to rules relating to the allocatability of
            IDN variants, then this array **MUST** be empty.
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/idnVariantLabel"

    idnVariantLabel:
      description: A variant label.
      type: object
      required:
        - label
        - variantTLDAllocatability
      properties:
        label:
          description: The variant label in either A-label or U-label format.
          type: string
          example: "دامنه"

        remark:
          description: Useful remarks about the label.
          type: string
          example: This is an illustrative example.

        variantTLDAllocatability:
          description: |
            The language tags that the label is allocatable in. This may include
            the IDN table in which the primary label is allocatable. In the
            context of a set of variant TLDs, this property may be used to
            determine the other TLDs in the set this label may be allocated in
            (otherwise it MUST be blocked). This array MAY be empty, in which
            case the variant label MUST be blocked in all TLDs in the set.
          type: array
          minItems: 0
          items:
            type: string
            example: fa-Arab

    variantPolicy:
      description: indicates the policy that should be applied to IDN variants.
      type: string
      enum:
        - novar
        - allblockvar
        - mayallocatevar

    fileRef:
      description: An object providing a hyperlink to an uploaded file.
      type: object
      properties:
        name:
          description: The file name.
          type: string
          example: example.txt
        type:
          description: The media type of the file.
          type: string
          example: text/plain
        uploaded:
          description: when the file was uploaded.
          type: string
          format: date-time
        href:
          description: The URL of the file.
          type: string
          format: url
          example: /v1/test/3aebd167-c275-45b6-842a-2680ed80422b/files/example.txt
          x-constraints: "@ValidUrl"