Missing decorators..

.chronus/changes/MissingDecorators-2024-10-22-15-39-24.md

@@ -0,0 +1,8 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi"
+  - "@typespec/openapi3"
+---
+
+@extension decorator supports multipleOf, uniqueItems, maxProperties, and minProperties, apply to properties in the Schema Object.

packages/openapi/README.md

@@ -59,10 +59,10 @@ Attach some custom data to the OpenAPI element generated from this type.
 
 ##### Parameters
 
-| Name  | Type             | Description                         |
-| ----- | ---------------- | ----------------------------------- |
-| key   | `valueof string` | Extension key. Must start with `x-` |
-| value | `unknown`        | Extension value.                    |
+| Name  | Type             | Description                                                                                                 |
+| ----- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| key   | `valueof string` | minProperties/maxProperties/uniqueItems/multipleOf or Extension key. The extension key must start with `x-` |
+| value | `unknown`        | Extension value.                                                                                            |
 
 ##### Examples
 
@@ -77,6 +77,42 @@ Attach some custom data to the OpenAPI element generated from this type.
 op read(): string;
 ```
 
+###### A schema can ensure that each of the items in an array is unique.
+
+```typespec
+model Foo {
+  @extension("uniqueItems", true)
+  x: unknown[];
+}
+```
+
+###### Numbers can be restricted to a multiple of a given number, using the multipleOf keyword. It may be set to any positive number.
+
+```typespec
+model Foo {
+  @extension("multipleOf", 1)
+  x: int32;
+}
+```
+
+###### The number of properties on an object can be restricted using the maxProperties keyword.
+
+```typespec
+model Foo {
+  @extension("maxProperties", 1)
+  x: int32;
+}
+```
+
+###### The number of properties on an object can be restricted using the minProperties keyword.
+
+```typespec
+model Foo {
+  @extension("minProperties", 1)
+  x: int32;
+}
+```
+
 #### `@externalDocs`
 
 Specify the OpenAPI `externalDocs` property for this type.

packages/openapi/generated-defs/TypeSpec.OpenAPI.ts

@@ -31,14 +31,42 @@ export type OperationIdDecorator = (
 /**
  * Attach some custom data to the OpenAPI element generated from this type.
  *
- * @param key Extension key. Must start with `x-`
+ * @param key minProperties/maxProperties/uniqueItems/multipleOf or Extension key. The extension key must start with `x-`
  * @param value Extension value.
  * @example
  * ```typespec
  * @extension("x-custom", "My value")
  * @extension("x-pageable", {nextLink: "x-next-link"})
  * op read(): string;
  * ```
+ * @example A schema can ensure that each of the items in an array is unique.
+ * ```typespec
+ * model Foo {
+ *  @extension("uniqueItems", true)
+ *  x: unknown[];
+ * };
+ * ```
+ * @example Numbers can be restricted to a multiple of a given number, using the multipleOf keyword. It may be set to any positive number.
+ * ```typespec
+ * model Foo {
+ *  @extension("multipleOf", 1)
+ *  x: int32;
+ * };
+ * ```
+ * @example The number of properties on an object can be restricted using the maxProperties keyword.
+ * ```typespec
+ * model Foo {
+ *  @extension("maxProperties", 1)
+ *  x: int32;
+ * };
+ * ```
+ * @example The number of properties on an object can be restricted using the minProperties keyword.
+ * ```typespec
+ * model Foo {
+ *  @extension("minProperties", 1)
+ *  x: int32;
+ * };
+ * ```
  */
 export type ExtensionDecorator = (
   context: DecoratorContext,

packages/openapi/lib/decorators.tsp

@@ -19,16 +19,47 @@ extern dec operationId(target: Operation, operationId: valueof string);
 /**
  * Attach some custom data to the OpenAPI element generated from this type.
  *
- * @param key Extension key. Must start with `x-`
+ * @param key minProperties/maxProperties/uniqueItems/multipleOf or Extension key. The extension key must start with `x-`
  * @param value Extension value.
  *
  * @example
- *
  * ```typespec
  * @extension("x-custom", "My value")
  * @extension("x-pageable", {nextLink: "x-next-link"})
  * op read(): string;
  * ```
+ *
+ * @example A schema can ensure that each of the items in an array is unique.
+ * ```typespec
+ * model Foo {
+ *  @extension("uniqueItems", true)
+ *  x: unknown[];
+ * };
+ * ```
+ *
+ * @example Numbers can be restricted to a multiple of a given number, using the multipleOf keyword. It may be set to any positive number.
+ * ```typespec
+ * model Foo {
+ *  @extension("multipleOf", 1)
+ *  x: int32;
+ * };
+ * ```
+ *
+ * @example The number of properties on an object can be restricted using the maxProperties keyword.
+ * ```typespec
+ * model Foo {
+ *  @extension("maxProperties", 1)
+ *  x: int32;
+ * };
+ * ```
+ *
+ * @example The number of properties on an object can be restricted using the minProperties keyword.
+ * ```typespec
+ * model Foo {
+ *  @extension("minProperties", 1)
+ *  x: int32;
+ * };
+ * ```
  */
 extern dec extension(target: unknown, key: valueof string, value: unknown);
 

packages/openapi/src/decorators.ts

@@ -4,6 +4,7 @@ import {
   getDoc,
   getService,
   getSummary,
+  isArrayModelType,
   Model,
   Namespace,
   Operation,
@@ -25,7 +26,8 @@ import {
 } from "../generated-defs/TypeSpec.OpenAPI.js";
 import { isOpenAPIExtensionKey, validateAdditionalInfoModel, validateIsUri } from "./helpers.js";
 import { createStateSymbol, OpenAPIKeys, reportDiagnostic } from "./lib.js";
-import { AdditionalInfo, ExtensionKey, ExternalDocs } from "./types.js";
+import { AdditionalInfo, ExtensionKey, ExternalDocs, SchemaExtensionKey } from "./types.js";
+const schemaExtensions = ["minProperties", "maxProperties", "uniqueItems", "multipleOf"];
 
 const operationIdsKey = createStateSymbol("operationIds");
 /**
@@ -58,19 +60,89 @@ export const $extension: ExtensionDecorator = (
   extensionName: string,
   value: TypeSpecValue,
 ) => {
+  // Convert the TypeSpec value to JSON and collect any diagnostics
+  const [data, diagnostics] = typespecTypeToJson(value, entity);
+  const isModelProperty = entity.kind === "ModelProperty";
+
+  // Handle the "uniqueItems" extension
+  if (extensionName === "uniqueItems") {
+    // Check invalid target
+    if (
+      !(
+        isModelProperty &&
+        entity.type.kind === "Model" &&
+        isArrayModelType(context.program, entity.type)
+      )
+    ) {
+      // Report diagnostic if the target is invalid for "uniqueItems"
+      reportDiagnostic(context.program, {
+        code: "invalid-extension-target",
+        messageId: "uniqueItems",
+        format: { paramName: entity.kind },
+        target: entity,
+      });
+      return;
+    }
+
+    // Check invalid data, Report diagnostic if the extension value is not a boolean
+    if (data !== true && data !== false) {
+      reportDiagnostic(context.program, {
+        code: "invalid-extension-value",
+        messageId: "uniqueItems",
+        format: { extensionName: extensionName },
+        target: entity,
+      });
+      return;
+    }
+    // Set the extension for "uniqueItems"
+    setExtension(context.program, entity, extensionName, data);
+    return;
+  }
+
+  // Handle other schema extensions
+  if (schemaExtensions.includes(extensionName) && extensionName !== "uniqueItems") {
+    // Check invalid target, Report diagnostic if the target is invalid for the schema extension
+    if (!isModelProperty) {
+      reportDiagnostic(context.program, {
+        code: "invalid-extension-target",
+        format: { paramName: entity.kind },
+        target: entity,
+      });
+      return;
+    }
+    // Check invalid data, Report diagnostic if the extension value is not a number
+    if (isNaN(Number(data))) {
+      reportDiagnostic(context.program, {
+        code: "invalid-extension-value",
+        format: { extensionName: extensionName },
+        target: entity,
+      });
+      return;
+    }
+    // Set the extension for the schema extension
+    setExtension(context.program, entity, extensionName as SchemaExtensionKey, Number(data));
+    return;
+  }
+
+  // Check if the extensionName is a valid OpenAPI extension
   if (!isOpenAPIExtensionKey(extensionName)) {
     reportDiagnostic(context.program, {
       code: "invalid-extension-key",
+      messageId: "decorator",
       format: { value: extensionName },
       target: entity,
     });
+    return;
   }
 
-  const [data, diagnostics] = typespecTypeToJson(value, entity);
+  // Report diagnostics if invalid data is found
   if (diagnostics.length > 0) {
     context.program.reportDiagnostics(diagnostics);
+    return;
   }
-  setExtension(context.program, entity, extensionName as ExtensionKey, data);
+
+  // Set the extension for valid OpenAPI extensions
+  setExtension(context.program, entity, extensionName, data);
 };
 
 /**
@@ -97,7 +169,7 @@ export function setInfo(
 export function setExtension(
   program: Program,
   entity: Type,
-  extensionName: ExtensionKey,
+  extensionName: ExtensionKey | SchemaExtensionKey,
   data: unknown,
 ) {
   const openApiExtensions = program.stateMap(openApiExtensionKey);
@@ -112,7 +184,38 @@ export function setExtension(
  * @param entity Type
  */
 export function getExtensions(program: Program, entity: Type): ReadonlyMap<ExtensionKey, any> {
-  return program.stateMap(openApiExtensionKey).get(entity) ?? new Map<ExtensionKey, any>();
+  const allExtensions = program.stateMap(openApiExtensionKey).get(entity);
+  return allExtensions
+    ? filterSchemaExtensions<ExtensionKey>(allExtensions, false)
+    : new Map<ExtensionKey, any>();
+}
+
+/**
+ * Get schema extensions set for the given type.
+ * @param program Program
+ * @param entity Type
+ */
+export function getSchemaExtensions(
+  program: Program,
+  entity: Type,
+): ReadonlyMap<SchemaExtensionKey, any> {
+  const allExtensions = program.stateMap(openApiExtensionKey).get(entity);
+  return allExtensions
+    ? filterSchemaExtensions<SchemaExtensionKey>(allExtensions, true)
+    : new Map<SchemaExtensionKey, any>();
+}
+
+function filterSchemaExtensions<T>(
+  extensions: Map<ExtensionKey | SchemaExtensionKey, any>,
+  isSchema: boolean,
+): ReadonlyMap<T, any> {
+  const result = new Map<T, any>();
+  for (const [key, value] of extensions) {
+    if (schemaExtensions.includes(key) === isSchema) {
+      result.set(key as T, value);
+    }
+  }
+  return result;
 }
 
 /**

packages/openapi/src/index.ts

@@ -14,6 +14,7 @@ export {
   getExternalDocs,
   getInfo,
   getOperationId,
+  getSchemaExtensions,
   getTagsMetadata,
   isDefaultResponse,
   resolveInfo,

packages/openapi/src/lib.ts

@@ -7,6 +7,21 @@ export const $lib = createTypeSpecLibrary({
       severity: "error",
       messages: {
         default: paramMessage`OpenAPI extension must start with 'x-' but was '${"value"}'`,
+        decorator: paramMessage`Extension decorator only support minProperties/maxProperties/uniqueItems/multipleOf/'x-' but was '${"value"}'`,
+      },
+    },
+    "invalid-extension-value": {
+      severity: "error",
+      messages: {
+        default: paramMessage`'${"extensionName"}' must number.'`,
+        uniqueItems: paramMessage`${"extensionName"}' must boolean.`,
+      },
+    },
+    "invalid-extension-target": {
+      severity: "error",
+      messages: {
+        default: paramMessage`'minProperties/maxProperties/multipleOf' can only apply to property, but ${"paramName"} is not`,
+        uniqueItems: paramMessage`'uniqueItems' can only be apply to properties that are arrays, but ${"paramName"} is not`,
       },
     },
     "duplicate-type-name": {

packages/openapi/src/types.ts

@@ -4,6 +4,7 @@
  */
 export type ExtensionKey = `x-${string}`;
 
+export type SchemaExtensionKey = "minProperties" | "maxProperties" | "uniqueItems" | "multipleOf";
 /**
  * OpenAPI additional information
  */