RHIDP-8066: time syntax

artifacts/rhdh-plugins-reference/aap-backend/aap-backend-plugin-readme.adoc

@@ -28,11 +28,11 @@ The AAP backend plugin is pre-loaded in {product-short} with basic configuration
 
 [source,yaml]
 ----
-global: 
-  dynamic: 
-    includes: 
+global:
+  dynamic:
+    includes:
       - dynamic-plugins.default.yaml
-    plugins: 
+    plugins:
       - package: ./dynamic-plugins/dist/janus-idp-backstage-plugin-aap-backend-dynamic
         disabled: false
 ----
@@ -60,9 +60,9 @@ To enable the AAP plugin, you must set the following environment variables:
            owner: <owner>
            system: <system>
            schedule: # optional; same options as in TaskScheduleDefinition
-             # supports cron, ISO duration, "human duration" as used in code
+             # supports cron, ISO 8601 duration strings, and duration objects
              frequency: { minutes: 1 }
-             # supports ISO duration, "human duration" as used in code
+             # supports ISO 8601 duration strings and duration objects
              timeout: { minutes: 1 }
 ----
 --

artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc

@@ -53,9 +53,9 @@ You can configure a schedule in the `app-config.yaml` file, as follows:
              # ...
              # highlight-add-start
              schedule: # optional; same options as in TaskScheduleDefinition
-               # supports cron, ISO duration, "human duration" as used in code
+               # supports cron, ISO 8601 duration strings, and duration objects
                frequency: { minutes: 1 }
-               # supports ISO duration, "human duration" as used in code
+               # supports ISO 8601 duration strings and duration objects
                timeout: { minutes: 1 }
                initialDelay: { seconds: 15 }
                # highlight-add-end

artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-readme.adoc

@@ -1,5 +1,5 @@
 [id="rhdh-keycloak_{context}"]
-= Installation and configuration of Keycloak 
+= Installation and configuration of Keycloak
 
 The Keycloak backend plugin, which integrates Keycloak into {product-short}, has the following capabilities:
 
@@ -12,11 +12,11 @@ The Keycloak plugin is pre-loaded in {product-short} with basic configuration pr
 
 [source,yaml]
 ----
-global: 
-  dynamic: 
-    includes: 
+global:
+  dynamic:
+    includes:
       - dynamic-plugins.default.yaml
-    plugins: 
+    plugins:
       - package: ./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic
         disabled: false
 ----
@@ -48,9 +48,9 @@ You can configure a schedule in the `app-config.yaml` file, as follows:
              # ...
              # highlight-add-start
              schedule: # optional; same options as in TaskScheduleDefinition
-               # supports cron, ISO duration, "human duration" as used in code
+               # supports cron, ISO 8601 duration strings, and duration objects
                frequency: { minutes: 1 }
-               # supports ISO duration, "human duration" as used in code
+               # supports ISO 8601 duration strings and duration objects
                timeout: { minutes: 1 }
                initialDelay: { seconds: 15 }
                # highlight-add-end

artifacts/rhdh-plugins-reference/ocm/ocm-plugin-readme.adoc

@@ -25,15 +25,15 @@ The Red Hat Plug-ins for Backstage (RHPIB) packages are hosted in a separate NPM
 ----
 # update your .npmrc or .yarnrc file
 yarn config set "@redhat:registry" https://npm.registry.redhat.com
-# then pull a package 
+# then pull a package
 yarn add @redhat/backstage-plugin-quay
 ----
 
-For more information, see link:https://docs.npmjs.com/cli/v9/configuring-npm/npmrc[npm docs]. 
+For more information, see link:https://docs.npmjs.com/cli/v9/configuring-npm/npmrc[npm docs].
 
-Creating a `.npmrc` file ensures that all the packages are scoped under `@redhat` and are fetched from link:https://npm.registry.redhat.com/[Red Hat's NPM registry], while the rest dependencies remain sourced from other link:registry.npmjs.org[registry]. 
+Creating a `.npmrc` file ensures that all the packages are scoped under `@redhat` and are fetched from link:https://npm.registry.redhat.com/[Red Hat's NPM registry], while the rest dependencies remain sourced from other link:registry.npmjs.org[registry].
 
-Using this configuration, you can proceed with the installation of the individual packages. 
+Using this configuration, you can proceed with the installation of the individual packages.
 
 The OCM plugin is composed of two packages, including:
 
@@ -204,9 +204,9 @@ For more information about the configuration, see https://backstage.io/docs/feat
               # ...
               # highlight-add-start
               schedule: # optional; same options as in TaskScheduleDefinition
-                # supports cron, ISO duration, "human duration" as used in code
+                # supports cron, ISO 8601 duration strings, and duration objects
                 frequency: { minutes: 1 }
-                # supports ISO duration, "human duration" as used in code
+                # supports ISO 8601 duration strings and duration objects
                 timeout: { minutes: 1 }
               # highlight-add-end
 +
@@ -295,7 +295,7 @@ yarn workspace app add @redhat/backstage-plugin-ocm
 --
 
 . Select the components that you want to use, such as:
- 
+
 ** `OcmPage`: This is a standalone page or dashboard displaying all clusters as tiles. You can add `OcmPage` to `packages/app/src/App.tsx` file as follows:
 +
 --

assemblies/assembly-rhdh-default-configuration.adoc

@@ -19,4 +19,6 @@ include::modules/configuring-external-databases/con-mounts-for-default-secret-pv
 
 include::modules/configuring-external-databases/proc-configuring-mount-paths.adoc[leveloffset=+2]
 
-include::modules/configuring-external-databases/proc-mounting-to-specific-containers.adoc[leveloffset=+2]
+include::modules/configuring-external-databases/proc-mounting-to-specific-containers.adoc[leveloffset=+2]
+
+include::modules/configuring/ref-time-syntax.adoc[leveloffset=1]

modules/configuring/ref-time-syntax.adoc

@@ -0,0 +1,58 @@
+:_mod-docs-content-type: REFERENCE
+
+[id="ref-time-syntax_{context}"]
+= Time syntax in {product}
+
+Learn about time duration formats supported by {product}.
+
+.Generally supported time formats
+[cols="1, 1, 1, 1"]
+|===
+|*Format*
+|*Description*
+|*Example*
+|*Compound values*
+
+|*Human-readable strings*
+|Simple strings compatible with the `ms` library.
+|`30m`
+|No
+
+|*Duration objects*
+|A structured object specifying time units. Matches the `HumanDuration` TypeScript interface.
+a|[source,yaml]
+----
+  timeout:
+    minutes: 30
+----
+|Yes
+
+|*ISO 8601 duration strings*
+|Standard ISO 8601 duration strings.
+|`PT30M`
+|Yes
+|===
+
+
+.Context-dependent time formats
+[cols="1, 1, 1"]
+|===
+|*Format*
+|*Description*
+|*Example*
+
+|*Cron*
+|An object containing a `cron` key with a crontab-style string. Used primarily by Scheduler services for tasks such as `frequency`).
+a|[source,yaml]
+----
+  frequency:
+    cron: '*/30 * * * *'
+----
+|===
+
+[WARNING]
+====
+{product-very-short} configuration reader `readDurationFromConfig` explicitly **disallows** plain numbers to prevent ambiguity.
+
+However, specific raw configuration fields, such as direct Node.js HTTP server settings, might strictly require numbers. Always check the specific documentation for the field you are configuring.
+====