Allow HH:MM format in z.string().datetime() and z.string().time() (#4315)

timorthi · web-flow · commit a429256d5999 · 2025-05-04T15:15:48.000-07:00
* feat: allow omitting seconds in time string

* docs: include examples of omitted seconds

* docs: remove whitespace
diff --git a/README.md b/README.md
@@ -53,7 +53,7 @@
 <!-- <hr/> -->
 <br/>
 <br/>
- 
+
 ## Table of contents
 
 > These docs have been translated into [Chinese](./README_ZH.md) and [Korean](./README_KO.md).
@@ -216,7 +216,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="CodeRabbit logo" height="80px" src="https://github.com/user-attachments/assets/d791bc7d-dc60-4d55-9c31-97779839cb74">
         </picture>
       </a>
-      <br  />   
+      <br  />
       Cut code review time & bugs in half
       <br/>
       <a href="https://www.coderabbit.ai/" style="text-decoration:none;">coderabbit.ai</a>
@@ -241,7 +241,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="Courier logo" height="62px" src="https://github.com/user-attachments/assets/6b09506a-78de-47e8-a8c1-792efe31910a">
         </picture>
       </a>
-      <br  />   
+      <br  />
       The API platform for sending notifications
       <br/>
       <a href="https://www.courier.com/?utm_source=zod&utm_campaign=osssponsors" style="text-decoration:none;">courier.com</a>
@@ -257,7 +257,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="LibLab" height="62px" src="https://github.com/user-attachments/assets/3de0b617-5137-49c4-b72d-a033cbe602d8">
         </picture>
       </a>
-      <br  />   
+      <br  />
       Generate better SDKs for your APIs
       <br/>
       <a href="https://liblab.com/?utm_source=zod" style="text-decoration:none;">liblab.com</a>
@@ -275,7 +275,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="Neon" height="68px" src="https://github.com/user-attachments/assets/b5799fc8-81ff-4053-a1c3-b29adf85e7a1">
         </picture>
       </a>
-      <br  />   
+      <br  />
       Serverless Postgres — Ship faster
       <br/>
       <a href="https://neon.tech" style="text-decoration:none;">neon.tech</a>
@@ -291,7 +291,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="Retool" height="45px" src="https://github.com/colinhacks/zod/assets/3084745/5ef4c11b-efeb-4495-90a8-41b83f798600">
         </picture>
       </a>
-      <br  />   
+      <br  />
       Build AI apps and workflows with <a href="https://retool.com/products/ai?utm_source=github&utm_medium=referral&utm_campaign=zod">Retool AI</a>
       <br/>
       <a href="https://retool.com/?utm_source=github&utm_medium=referral&utm_campaign=zod" style="text-decoration:none;">retool.com</a>
@@ -309,7 +309,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="stainless" height="45px" src="https://github.com/colinhacks/zod/assets/3084745/e9444e44-d991-4bba-a697-dbcfad608e47">
         </picture>
       </a>
-      <br  />   
+      <br  />
       Generate best-in-class SDKs
       <br/>
       <a href="https://stainless.com" style="text-decoration:none;">stainless.com</a>
@@ -325,7 +325,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="speakeasy" height="40px" src="https://github.com/colinhacks/zod/assets/3084745/647524a4-22bb-4199-be70-404207a5a2b5">
         </picture>
       </a>
-      <br  />   
+      <br  />
       SDKs & Terraform providers for your API
       <br/>
       <a href="https://speakeasy.com/?utm_source=zod+docs" style="text-decoration:none;">speakeasy.com</a>
@@ -847,7 +847,7 @@ z.string().toUpperCase(); // toUpperCase
 
 // added in Zod 3.23
 z.string().date(); // ISO date format (YYYY-MM-DD)
-z.string().time(); // ISO time format (HH:mm:ss[.SSSSSS])
+z.string().time(); // ISO time format (HH:mm:ss[.SSSSSS] or HH:mm)
 z.string().duration(); // ISO 8601 duration
 z.string().base64();
 ```
@@ -887,14 +887,15 @@ z.string().cidr({ message: "Invalid CIDR" });
 
 As you may have noticed, Zod string includes a few date/time related validations. These validations are regular expression based, so they are not as strict as a full date/time library. However, they are very convenient for validating user input.
 
-The `z.string().datetime()` method enforces ISO 8601; default is no timezone offsets and arbitrary sub-second decimal precision.
+The `z.string().datetime()` method enforces ISO 8601; default is no timezone offsets and arbitrary sub-second decimal precision. Seconds may be omitted if precision is not set.
 
 ```ts
 const datetime = z.string().datetime();
 
 datetime.parse("2020-01-01T00:00:00Z"); // pass
 datetime.parse("2020-01-01T00:00:00.123Z"); // pass
 datetime.parse("2020-01-01T00:00:00.123456Z"); // pass (arbitrary precision)
+datetime.parse("2020-01-01T00:00Z"); // pass (hours and minutes only)
 datetime.parse("2020-01-01T00:00:00+02:00"); // fail (no offsets allowed)
 ```
 
@@ -904,6 +905,7 @@ Timezone offsets can be allowed by setting the `offset` option to `true`.
 const datetime = z.string().datetime({ offset: true });
 
 datetime.parse("2020-01-01T00:00:00+02:00"); // pass
+datetime.parse("2020-01-01T00:00+02:00"); // pass
 datetime.parse("2020-01-01T00:00:00.123+02:00"); // pass (millis optional)
 datetime.parse("2020-01-01T00:00:00.123+0200"); // pass (millis optional)
 datetime.parse("2020-01-01T00:00:00.123+02"); // pass (only offset hours)
@@ -915,6 +917,7 @@ Allow unqualified (timezone-less) datetimes with the `local` flag.
 ```ts
 const schema = z.string().datetime({ local: true });
 schema.parse("2020-01-01T00:00:00"); // pass
+schema.parse("2020-01-01T00:00"); // pass
 ```
 
 You can additionally constrain the allowable `precision`. By default, arbitrary sub-second precision is supported (but optional).
@@ -924,6 +927,7 @@ const datetime = z.string().datetime({ precision: 3 });
 
 datetime.parse("2020-01-01T00:00:00.123Z"); // pass
 datetime.parse("2020-01-01T00:00:00Z"); // fail
+datetime.parse("2020-01-01T00:00Z"); // fail
 datetime.parse("2020-01-01T00:00:00.123456Z"); // fail
 ```
 
@@ -945,13 +949,14 @@ date.parse("2020-01-32"); // fail
 
 > Added in Zod 3.23
 
-The `z.string().time()` method validates strings in the format `HH:MM:SS[.s+]`. The second can include arbitrary decimal precision. It does not allow timezone offsets of any kind.
+The `z.string().time()` method validates strings in the format `HH:MM` or `HH:MM:SS[.s+]`. The second can include arbitrary decimal precision. It does not allow timezone offsets of any kind.
 
 ```ts
 const time = z.string().time();
 
 time.parse("00:00:00"); // pass
 time.parse("09:52:31"); // pass
+time.parse("09:52"); // pass
 time.parse("23:59:59.9999999"); // pass (arbitrary precision)
 
 time.parse("00:00:00.123Z"); // fail (no `Z` allowed)
@@ -966,6 +971,7 @@ const time = z.string().time({ precision: 3 });
 time.parse("00:00:00.123"); // pass
 time.parse("00:00:00.123456"); // fail
 time.parse("00:00:00"); // fail
+time.parse("00:00"); // fail
 ```
 
 ### IP addresses
diff --git a/deno/lib/README.md b/deno/lib/README.md
@@ -53,7 +53,7 @@
 <!-- <hr/> -->
 <br/>
 <br/>
- 
+
 ## Table of contents
 
 > These docs have been translated into [Chinese](./README_ZH.md) and [Korean](./README_KO.md).
@@ -216,7 +216,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="CodeRabbit logo" height="80px" src="https://github.com/user-attachments/assets/d791bc7d-dc60-4d55-9c31-97779839cb74">
         </picture>
       </a>
-      <br  />   
+      <br  />
       Cut code review time & bugs in half
       <br/>
       <a href="https://www.coderabbit.ai/" style="text-decoration:none;">coderabbit.ai</a>
@@ -241,7 +241,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="Courier logo" height="62px" src="https://github.com/user-attachments/assets/6b09506a-78de-47e8-a8c1-792efe31910a">
         </picture>
       </a>
-      <br  />   
+      <br  />
       The API platform for sending notifications
       <br/>
       <a href="https://www.courier.com/?utm_source=zod&utm_campaign=osssponsors" style="text-decoration:none;">courier.com</a>
@@ -257,7 +257,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="LibLab" height="62px" src="https://github.com/user-attachments/assets/3de0b617-5137-49c4-b72d-a033cbe602d8">
         </picture>
       </a>
-      <br  />   
+      <br  />
       Generate better SDKs for your APIs
       <br/>
       <a href="https://liblab.com/?utm_source=zod" style="text-decoration:none;">liblab.com</a>
@@ -275,7 +275,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="Neon" height="68px" src="https://github.com/user-attachments/assets/b5799fc8-81ff-4053-a1c3-b29adf85e7a1">
         </picture>
       </a>
-      <br  />   
+      <br  />
       Serverless Postgres — Ship faster
       <br/>
       <a href="https://neon.tech" style="text-decoration:none;">neon.tech</a>
@@ -291,7 +291,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="Retool" height="45px" src="https://github.com/colinhacks/zod/assets/3084745/5ef4c11b-efeb-4495-90a8-41b83f798600">
         </picture>
       </a>
-      <br  />   
+      <br  />
       Build AI apps and workflows with <a href="https://retool.com/products/ai?utm_source=github&utm_medium=referral&utm_campaign=zod">Retool AI</a>
       <br/>
       <a href="https://retool.com/?utm_source=github&utm_medium=referral&utm_campaign=zod" style="text-decoration:none;">retool.com</a>
@@ -309,7 +309,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="stainless" height="45px" src="https://github.com/colinhacks/zod/assets/3084745/e9444e44-d991-4bba-a697-dbcfad608e47">
         </picture>
       </a>
-      <br  />   
+      <br  />
       Generate best-in-class SDKs
       <br/>
       <a href="https://stainless.com" style="text-decoration:none;">stainless.com</a>
@@ -325,7 +325,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
           <img alt="speakeasy" height="40px" src="https://github.com/colinhacks/zod/assets/3084745/647524a4-22bb-4199-be70-404207a5a2b5">
         </picture>
       </a>
-      <br  />   
+      <br  />
       SDKs & Terraform providers for your API
       <br/>
       <a href="https://speakeasy.com/?utm_source=zod+docs" style="text-decoration:none;">speakeasy.com</a>
@@ -847,7 +847,7 @@ z.string().toUpperCase(); // toUpperCase
 
 // added in Zod 3.23
 z.string().date(); // ISO date format (YYYY-MM-DD)
-z.string().time(); // ISO time format (HH:mm:ss[.SSSSSS])
+z.string().time(); // ISO time format (HH:mm:ss[.SSSSSS] or HH:mm)
 z.string().duration(); // ISO 8601 duration
 z.string().base64();
 ```
@@ -887,14 +887,15 @@ z.string().cidr({ message: "Invalid CIDR" });
 
 As you may have noticed, Zod string includes a few date/time related validations. These validations are regular expression based, so they are not as strict as a full date/time library. However, they are very convenient for validating user input.
 
-The `z.string().datetime()` method enforces ISO 8601; default is no timezone offsets and arbitrary sub-second decimal precision.
+The `z.string().datetime()` method enforces ISO 8601; default is no timezone offsets and arbitrary sub-second decimal precision. Seconds may be omitted if precision is not set.
 
 ```ts
 const datetime = z.string().datetime();
 
 datetime.parse("2020-01-01T00:00:00Z"); // pass
 datetime.parse("2020-01-01T00:00:00.123Z"); // pass
 datetime.parse("2020-01-01T00:00:00.123456Z"); // pass (arbitrary precision)
+datetime.parse("2020-01-01T00:00Z"); // pass (hours and minutes only)
 datetime.parse("2020-01-01T00:00:00+02:00"); // fail (no offsets allowed)
 ```
 
@@ -904,6 +905,7 @@ Timezone offsets can be allowed by setting the `offset` option to `true`.
 const datetime = z.string().datetime({ offset: true });
 
 datetime.parse("2020-01-01T00:00:00+02:00"); // pass
+datetime.parse("2020-01-01T00:00+02:00"); // pass
 datetime.parse("2020-01-01T00:00:00.123+02:00"); // pass (millis optional)
 datetime.parse("2020-01-01T00:00:00.123+0200"); // pass (millis optional)
 datetime.parse("2020-01-01T00:00:00.123+02"); // pass (only offset hours)
@@ -915,6 +917,7 @@ Allow unqualified (timezone-less) datetimes with the `local` flag.
 ```ts
 const schema = z.string().datetime({ local: true });
 schema.parse("2020-01-01T00:00:00"); // pass
+schema.parse("2020-01-01T00:00"); // pass
 ```
 
 You can additionally constrain the allowable `precision`. By default, arbitrary sub-second precision is supported (but optional).
@@ -924,6 +927,7 @@ const datetime = z.string().datetime({ precision: 3 });
 
 datetime.parse("2020-01-01T00:00:00.123Z"); // pass
 datetime.parse("2020-01-01T00:00:00Z"); // fail
+datetime.parse("2020-01-01T00:00Z"); // fail
 datetime.parse("2020-01-01T00:00:00.123456Z"); // fail
 ```
 
@@ -945,13 +949,14 @@ date.parse("2020-01-32"); // fail
 
 > Added in Zod 3.23
 
-The `z.string().time()` method validates strings in the format `HH:MM:SS[.s+]`. The second can include arbitrary decimal precision. It does not allow timezone offsets of any kind.
+The `z.string().time()` method validates strings in the format `HH:MM` or `HH:MM:SS[.s+]`. The second can include arbitrary decimal precision. It does not allow timezone offsets of any kind.
 
 ```ts
 const time = z.string().time();
 
 time.parse("00:00:00"); // pass
 time.parse("09:52:31"); // pass
+time.parse("09:52"); // pass
 time.parse("23:59:59.9999999"); // pass (arbitrary precision)
 
 time.parse("00:00:00.123Z"); // fail (no `Z` allowed)
@@ -966,6 +971,7 @@ const time = z.string().time({ precision: 3 });
 time.parse("00:00:00.123"); // pass
 time.parse("00:00:00.123456"); // fail
 time.parse("00:00:00"); // fail
+time.parse("00:00"); // fail
 ```
 
 ### IP addresses
diff --git a/deno/lib/__tests__/string.test.ts b/deno/lib/__tests__/string.test.ts
@@ -594,15 +594,18 @@ test("datetime parsing", () => {
   datetime.parse("2022-10-13T09:52:31.8162314Z");
   datetime.parse("1970-01-01T00:00:00Z");
   datetime.parse("2022-10-13T09:52:31Z");
+  datetime.parse("2022-10-13T09:52Z");
   expect(() => datetime.parse("")).toThrow();
   expect(() => datetime.parse("foo")).toThrow();
   expect(() => datetime.parse("2020-10-14")).toThrow();
   expect(() => datetime.parse("T18:45:12.123")).toThrow();
   expect(() => datetime.parse("2020-10-14T17:42:29+00:00")).toThrow();
+  expect(() => datetime.parse("2020-10-14T17:42.123+00:00")).toThrow();
 
   const datetimeNoMs = z.string().datetime({ precision: 0 });
   datetimeNoMs.parse("1970-01-01T00:00:00Z");
   datetimeNoMs.parse("2022-10-13T09:52:31Z");
+  datetimeNoMs.parse("2022-10-13T09:52Z");
   expect(() => datetimeNoMs.parse("tuna")).toThrow();
   expect(() => datetimeNoMs.parse("1970-01-01T00:00:00.000Z")).toThrow();
   expect(() => datetimeNoMs.parse("1970-01-01T00:00:00.Z")).toThrow();
@@ -615,6 +618,7 @@ test("datetime parsing", () => {
   expect(() => datetime3Ms.parse("1970-01-01T00:00:00.1Z")).toThrow();
   expect(() => datetime3Ms.parse("1970-01-01T00:00:00.12Z")).toThrow();
   expect(() => datetime3Ms.parse("2022-10-13T09:52:31Z")).toThrow();
+  expect(() => datetime3Ms.parse("2022-10-13T09:52Z")).toThrow();
 
   const datetimeOffset = z.string().datetime({ offset: true });
   datetimeOffset.parse("1970-01-01T00:00:00.000Z");
@@ -624,6 +628,7 @@ test("datetime parsing", () => {
   datetimeOffset.parse("2020-10-14T17:42:29+00:00");
   datetimeOffset.parse("2020-10-14T17:42:29+03:15");
   datetimeOffset.parse("2020-10-14T17:42:29+0315");
+  datetimeOffset.parse("2020-10-14T17:42+0315");
   expect(() => datetimeOffset.parse("2020-10-14T17:42:29+03"));
   expect(() => datetimeOffset.parse("tuna")).toThrow();
   expect(() => datetimeOffset.parse("2022-10-13T09:52:31.Z")).toThrow();
@@ -635,6 +640,7 @@ test("datetime parsing", () => {
   datetimeOffsetNoMs.parse("2022-10-13T09:52:31Z");
   datetimeOffsetNoMs.parse("2020-10-14T17:42:29+00:00");
   datetimeOffsetNoMs.parse("2020-10-14T17:42:29+0000");
+  datetimeOffsetNoMs.parse("2020-10-14T17:42+0000");
   expect(() => datetimeOffsetNoMs.parse("2020-10-14T17:42:29+00")).toThrow();
   expect(() => datetimeOffsetNoMs.parse("tuna")).toThrow();
   expect(() => datetimeOffsetNoMs.parse("1970-01-01T00:00:00.000Z")).toThrow();
@@ -656,6 +662,7 @@ test("datetime parsing", () => {
   expect(() =>
     datetimeOffset4Ms.parse("2020-10-14T17:42:29.124+00:00")
   ).toThrow();
+  expect(() => datetimeOffset4Ms.parse("2020-10-14T17:42+00:00")).toThrow();
 });
 
 test("date", () => {
@@ -731,6 +738,7 @@ test("time parsing", () => {
   time.parse("23:59:59");
   time.parse("09:52:31");
   time.parse("23:59:59.9999999");
+  time.parse("23:59");
   expect(() => time.parse("")).toThrow();
   expect(() => time.parse("foo")).toThrow();
   expect(() => time.parse("00:00:00Z")).toThrow();
@@ -743,6 +751,7 @@ test("time parsing", () => {
   expect(() => time.parse("00:60:00")).toThrow();
   expect(() => time.parse("00:00:60")).toThrow();
   expect(() => time.parse("24:60:60")).toThrow();
+  expect(() => time.parse("24:60")).toThrow();
 
   const time2 = z.string().time({ precision: 2 });
   time2.parse("00:00:00.00");
@@ -755,6 +764,7 @@ test("time parsing", () => {
   expect(() => time2.parse("00:00:00.0")).toThrow();
   expect(() => time2.parse("00:00:00.000")).toThrow();
   expect(() => time2.parse("00:00:00.00+00:00")).toThrow();
+  expect(() => time2.parse("23:59")).toThrow();
 
   // const time3 = z.string().time({ offset: true });
   // time3.parse("00:00:00Z");
diff --git a/deno/lib/types.ts b/deno/lib/types.ts
@@ -696,16 +696,17 @@ const dateRegexSource = `((\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[0246
 const dateRegex = new RegExp(`^${dateRegexSource}$`);
 
 function timeRegexSource(args: { precision?: number | null }) {
-  // let regex = `\\d{2}:\\d{2}:\\d{2}`;
-  let regex = `([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d`;
-
+  let secondsRegexSource = `[0-5]\\d`;
   if (args.precision) {
-    regex = `${regex}\\.\\d{${args.precision}}`;
+    secondsRegexSource = `${secondsRegexSource}\\.\\d{${args.precision}}`;
   } else if (args.precision == null) {
-    regex = `${regex}(\\.\\d+)?`;
+    secondsRegexSource = `${secondsRegexSource}(\\.\\d+)?`;
   }
-  return regex;
+
+  const secondsQuantifier = args.precision ? "+" : "?"; // require seconds if precision is nonzero
+  return `([01]\\d|2[0-3]):[0-5]\\d(:${secondsRegexSource})${secondsQuantifier}`;
 }
+
 function timeRegex(args: {
   offset?: boolean;
   local?: boolean;
diff --git a/src/__tests__/string.test.ts b/src/__tests__/string.test.ts
diff --git a/src/types.ts b/src/types.ts
