Feature: Add @dateFormat decorator

common/changes/@typespec/compiler/feature-date-format-decorator_2023-04-05-22-45.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "**Added** New `@dateFormat` decorator",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/compiler"
+}

common/changes/@typespec/openapi3/feature-date-format-decorator_2023-04-05-22-45.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/openapi3",
+      "comment": "**Added** Support for new `@dateFormat` decorator",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/openapi3"
+}

docs/standard-library/built-in-decorators.md

@@ -531,6 +531,23 @@ model Dog extends Pet  {kind: "dog", bark: boolean}
 ```
 
 
+### `@dateFormat` {#@dateFormat}
+
+
+```typespec
+dec dateFormat(target: zonedDateTime | ModelProperty, format: rfc1123 | rfc7231 | unixTimeStamp | string)
+```
+
+#### Target
+
+`union zonedDateTime | ModelProperty`
+
+#### Parameters
+| Name | Type | Description |
+|------|------|-------------|
+| format | `union rfc1123 \| rfc7231 \| unixTimeStamp \| string` |  |
+
+
 ### `@visibility` {#@visibility}
 
 Indicates that a property is only considered to be present or applicable ("visible") with

packages/compiler/lib/decorators.ts

@@ -533,6 +533,31 @@ export function isSecret(program: Program, target: Type): boolean | undefined {
   return program.stateMap(secretTypesKey).get(target);
 }
 
+// -- @dateFormat decorator ---------------------
+export type KnownDateFormat = "rfc3339" | "rfc7231" | "unixTimeStamp";
+
+const dateFormatKey = createStateSymbol("dateFormat");
+export function $dateFormat(
+  context: DecoratorContext,
+  target: Scalar | ModelProperty,
+  format: string
+) {
+  validateDecoratorUniqueOnNode(context, target, $dateFormat);
+
+  if (!validateDecoratorTargetIntrinsic(context, target, "@zonedDateTime", ["zonedDateTime"])) {
+    return;
+  }
+
+  context.program.stateMap(dateFormatKey).set(target, format);
+}
+
+export function getDateFormat(
+  program: Program,
+  target: Scalar | ModelProperty
+): KnownDateFormat | string | undefined {
+  return program.stateMap(dateFormatKey).get(target);
+}
+
 // -- @visibility decorator ---------------------
 
 const visibilitySettingsKey = createStateSymbol("visibilitySettings");

packages/compiler/lib/decorators.tsp

@@ -337,6 +337,9 @@ extern dec projectedName(target: unknown, targetName: string, projectedName: str
  */
 extern dec discriminator(target: object | Union, propertyName: string);
 
+alias KnownDateFormat = "rfc1123" | "rfc7231" | "unixTimeStamp";
+extern dec dateFormat(target: zonedDateTime | ModelProperty, format: KnownDateFormat | string);
+
 /**
  * Indicates that a property is only considered to be present or applicable ("visible") with
  * the in the given named contexts ("visibilities"). When a property has no visibilities applied

packages/compiler/test/decorators/decorators.test.ts

@@ -1,6 +1,14 @@
 import { deepStrictEqual, ok, strictEqual } from "assert";
-import { getVisibility, isSecret, Model, Operation, Scalar } from "../../core/index.js";
 import {
+  getVisibility,
+  isSecret,
+  Model,
+  ModelProperty,
+  Operation,
+  Scalar,
+} from "../../core/index.js";
+import {
+  getDateFormat,
   getDoc,
   getFriendlyName,
   getKeyName,
@@ -357,6 +365,46 @@ describe("compiler: built-in decorators", () => {
     });
   });
 
+  describe("@dateFormat", () => {
+    it("assign the known values to zonedDateTime property", async () => {
+      const { dob } = (await runner.compile(`
+
+        model Foo {
+          @dateFormat("rfc1123")
+          @test
+          dob: zonedDateTime;
+        }
+
+      `)) as { dob: ModelProperty };
+
+      strictEqual(getDateFormat(runner.program, dob), "rfc1123");
+    });
+
+    it("assign the known values to zonedDateTime extended scalar", async () => {
+      const { Bar } = (await runner.compile(`
+        @test
+        @dateFormat("rfc1123")
+        scalar Bar extends zonedDateTime;
+      `)) as { Bar: Scalar };
+
+      ok(Bar.kind);
+      strictEqual(getDateFormat(runner.program, Bar), "rfc1123");
+    });
+
+    it("emit diagnostics when used on non scalar", async () => {
+      const diagnostics = await runner.diagnose(`
+        @dateFormat("rfc1123")
+        enum Bar {}
+      `);
+
+      expectDiagnostics(diagnostics, {
+        code: "decorator-wrong-target",
+        message:
+          "Cannot apply @dateFormat decorator to Bar since it is not assignable to zonedDateTime | ModelProperty",
+      });
+    });
+  });
+
   describe("@withoutOmittedProperties", () => {
     it("removes a model property when given a string literal", async () => {
       const { TestModel } = await runner.compile(

packages/openapi3/src/openapi.ts

@@ -8,6 +8,7 @@ import {
   EnumMember,
   getAllTags,
   getAnyExtensionFromPath,
+  getDateFormat,
   getDiscriminatedUnion,
   getDiscriminator,
   getDoc,
@@ -1307,6 +1308,16 @@ function createOAPIEmitter(program: Program, options: ResolvedOpenAPI3EmitterOpt
       newTarget.format = "password";
     }
 
+    const dateFormat = getDateFormat(program, typespecType);
+    if (dateFormat) {
+      if (dateFormat === "unixTimeStamp") {
+        newTarget.type = "integer";
+        newTarget.format = "timestamp";
+      } else {
+        newTarget.format = `date-time-${dateFormat}`;
+      }
+    }
+
     if (isString) {
       const values = getKnownValues(program, typespecType);
       if (values) {

packages/openapi3/test/primitive-types.test.ts

@@ -189,4 +189,56 @@ describe("openapi3: primitives", () => {
       });
     });
   });
+
+  describe("date format", () => {
+    it("set format to 'date-time' by default", async () => {
+      const res = await oapiForModel(
+        "MyDate",
+        `
+      scalar MyDate extends zonedDateTime;
+      `
+      );
+      deepStrictEqual(res.schemas.MyDate, { type: "string", format: "date-time" });
+    });
+
+    it("set format to 'timestamp' and type to 'ingeger' for 'unixtimestamp' format", async () => {
+      const res = await oapiForModel(
+        "MyDate",
+        `
+      @dateFormat("unixTimeStamp")
+      scalar MyDate extends zonedDateTime;
+      `
+      );
+      deepStrictEqual(res.schemas.MyDate, { type: "integer", format: "timestamp" });
+    });
+
+    it("set format to 'date-time-{date-format}' when set on scalar", async () => {
+      const res = await oapiForModel(
+        "MyDate",
+        `
+      @dateFormat("rfc1123")
+      scalar MyDate extends zonedDateTime;
+      `
+      );
+      deepStrictEqual(res.schemas.MyDate, { type: "string", format: "date-time-rfc1123" });
+    });
+
+    it("set format to 'date-time-{date-format}' when set on model property", async () => {
+      const res = await oapiForModel(
+        "MyDate",
+        `
+      model MyDate {
+        @dateFormat("rfc1123")
+        foo: zonedDateTime;
+      }
+
+      op test(): MyDate;
+      `
+      );
+      deepStrictEqual(res.schemas.MyDate.properties.foo, {
+        type: "string",
+        format: "date-time-rfc1123",
+      });
+    });
+  });
 });