v2026.07

bin/generate-input-parameter-schema.pl

@@ -49,8 +49,19 @@ sub munge_schema {
         $schema->{example} = $schema->{default};
     }
 
-    if ('url' eq $schema->{format}) {
-        $schema->{'x-field-extra-annotation'} = '@org.icann.rst.commons.annotations.ValidUrl';
+    if ('string' eq $schema->{type}) {
+        if ('url' eq $schema->{format}) {
+            $schema->{'x-field-extra-annotation'} = '@org.icann.rst.commons.annotations.ValidUrl';
+
+        } elsif ('hostname' eq $schema->{format}) {
+            $schema->{'x-field-extra-annotation'} = '@org.icann.rst.commons.annotations.ValidHostname';
+
+        }
+
+    } elsif ('object' eq $schema->{type}) {
+        foreach my $property (keys(%{$schema->{properties}})) {
+            munge_schema($schema->{properties}->{$property});
+        }
 
     } elsif ('array' eq $schema->{type}) {
         if ('ipv4' eq $schema->{items}->{format}) {
@@ -59,14 +70,12 @@ sub munge_schema {
         } elsif ('ipv6' eq $schema->{items}->{format}) {
             $schema->{'x-field-extra-annotation'} = '@org.icann.rst.commons.annotations.ValidIpv6List';
 
+        } elsif ('hostname' eq $schema->{items}->{format}) {
+            $schema->{'x-field-extra-annotation'} = '@org.icann.rst.commons.annotations.ValidHostnameList';
+
         } else {
             munge_schema($schema->{items}) if ($schema->{items});
 
         }
-
-    } elsif ('object' eq $schema->{type}) {
-        foreach my $property (keys(%{$schema->{properties}})) {
-            munge_schema($schema->{properties}->{$property});
-        }
     }
 }

inc/idn-table-request-base-properties.yaml

@@ -6,6 +6,7 @@ rsp:
     and will be populated using the FQDN of the first `TLSA` record
     which matches the certificate presented by the client.
   type: string
+  maxLength: 256
   example: RSPI2404-M51
 
 tag:

inc/test-request-base-properties.yaml

@@ -13,6 +13,7 @@ rsp:
     In OT&E, this **MUST** contain the Fully-Qualified Domain Name where a TLSA
     record that validates the client certificate is published.
   type: string
+  maxLength: 256
   example: RSPI2404-M51
 
 tlds:
@@ -112,6 +113,7 @@ clientIDs:
     record that validates the client certificate is published, and **MAY**
     contain other IDs.
   type: array
+  x-field-extra-annotation: "@org.icann.rst.commons.annotations.ValidHostnameList"
   minItems: 1
   items:
     type: string

rst-api-spec.yaml.in

@@ -36,6 +36,9 @@ info:
 
     ### Change Log
 
+    * v2026.6 (2026-07-30):
+      * Add annotations and restrictions on various API parameters ([#71](https://github.com/icann/rst-api-spec/issues/71))
+
     * v2026.6 (2026-06-16):
       * Add `testPlanVersion` to test runs
         ([#62](https://github.com/icann/rst-api-spec/issues/62))
@@ -390,7 +393,8 @@ paths:
         in: path
         required: true
         schema:
-          type: string
+          type: integer
+          minimum: 1
     get:
       tags:
         - Retrieving test information
@@ -487,6 +491,8 @@ paths:
           required: false
           schema:
             type: string
+            format: hostname
+            x-field-extra-annotation: "@org.icann.rst.commons.annotations.ValidHostname"
         - name: applicationID
           description: |
             limit results to specific a application ID (internal users only).
@@ -644,6 +650,7 @@ paths:
           required: false
           schema:
             type: string
+            x-field-extra-annotation: "@org.icann.rst.commons.annotations.ValidLanguageTag"
       responses:
 #exec gpp -x inc/http-errors.yaml | sed 's/^/        /'
         '200':
@@ -816,6 +823,7 @@ components:
           description: The TLD (or equivalent registry-class domain name).
           type: string
           format: hostname
+          x-field-extra-annotation: "@org.icann.rst.commons.annotations.ValidHostname"
           example: example
         idnTables:
           description: The IDN tables(s) for the TLD.
@@ -885,6 +893,7 @@ components:
           items:
             type: string
             format: hostname
+            x-field-extra-annotation: "@org.icann.rst.commons.annotations.ValidHostname"
             example: example
 
     testRequestSubmitted:
@@ -1017,8 +1026,8 @@ components:
             properties:
               runID:
                 description: unique ID for this test run.
-                type: string
-                example: 3ed892dd-2b29-4f59-b024-653345067547
+                type: integer
+                minimum: 1
               dateStarted:
                 description: The date and time the run started.
                 type: string
@@ -1061,8 +1070,8 @@ components:
       properties:
         runID:
           description: unique ID for this test run.
-          type: string
-          example: 3ed892dd-2b29-4f59-b024-653345067547
+          type: integer
+          minimum: 1
         dateStarted:
           description: The date and time the run started.
           type: string