Use examples instead of example in Schema Objects with OpenAPI 3.1.x

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.27.0
+
+### Changed
+
+- OpenAPI 3.1.x: use `examples` in Schema Objects instead of the deprecated `example`
+
 ## 0.26.1 - 2024-07-09
 
 ### Fixed

lib/cli.js

@@ -1,35 +1,36 @@
 #!/usr/bin/env node
 "use strict";
 
-const csdl = require("odata-csdl");
-const lib = require("./csdl2openapi");
-const fs = require("fs");
+const { csdl2openapi } = require("./csdl2openapi");
+const { xml2json } = require("odata-csdl");
+const { createWriteStream, existsSync, readFileSync } = require("node:fs");
+const { Readable } = require("node:stream");
 const { parseArguments } = require("./cliParts");
-const { stringifyStream } = require("@discoveryjs/json-ext");
+const { stringifyChunked } = require("@discoveryjs/json-ext");
 
 const args = parseArguments(process.argv.slice(2));
 if (args.unknown) console.error(args.unknown);
 if (args.usage) console.log(args.usage);
 else convert(args);
 
 function convert(args) {
-  if (!fs.existsSync(args.source)) {
+  if (!existsSync(args.source)) {
     console.error("Source file not found: " + args.source);
     return;
   }
 
-  const text = fs.readFileSync(args.source, "utf8");
-  const json = text.startsWith("<") ? csdl.xml2json(text) : JSON.parse(text);
+  const text = readFileSync(args.source, "utf8");
+  const json = text.startsWith("<") ? xml2json(text) : JSON.parse(text);
 
   console.log(args.target);
 
   const messages = [];
 
-  const openapi = lib.csdl2openapi(json, { messages, ...args.options });
+  const openapi = csdl2openapi(json, { messages, ...args.options });
 
-  stringifyStream(openapi, null, args.options.pretty ? 4 : 0).pipe(
-    fs.createWriteStream(args.target),
-  );
+  Readable.from(
+    stringifyChunked(openapi, null, args.options.pretty ? 4 : 0),
+  ).pipe(createWriteStream(args.target));
 
   if (messages.length > 0) console.dir(messages);
 }

lib/csdl2openapi.js

@@ -632,17 +632,22 @@ module.exports.csdl2openapi = function (
       const deltaSupported =
         element[voc.Capabilities.ChangeTracking] &&
         element[voc.Capabilities.ChangeTracking].Supported;
-      if (!byKey && deltaSupported) {
-        operation.responses[200].content["application/json"].schema.properties[
-          "@odata.deltaLink"
-        ] = {
+      if (collection && deltaSupported) {
+        const deltaLinkSchema = {
           type: "string",
           example:
             basePath +
             "/" +
             name +
             "?$deltatoken=opaque server-generated token for fetching the delta",
         };
+        if (oas31) {
+          deltaLinkSchema.examples = [deltaLinkSchema.example];
+          delete deltaLinkSchema.example;
+        }
+        operation.responses[200].content["application/json"].schema.properties[
+          "@odata.deltaLink"
+        ] = deltaLinkSchema;
       }
       if (target && sourceName != targetName) operation.tags.push(targetName);
 
@@ -2724,6 +2729,11 @@ module.exports.csdl2openapi = function (
       }
     }
 
+    if (oas31 && s.example !== undefined) {
+      s.examples = [s.example];
+      delete s.example;
+    }
+
     if (typeof element[voc.Validation.Maximum] === "number") {
       if (s.$ref) s = { allOf: [s] };
       s.maximum = element[voc.Validation.Maximum];

package.json

@@ -1,6 +1,6 @@
 {
   "name": "odata-openapi",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "Convert OData CSDL XML or CSDL JSON to OpenAPI",
   "homepage": "https://github.com/oasis-tcs/odata-openapi/blob/master/lib/README.md",
   "bugs": "https://github.com/oasis-tcs/odata-openapi/issues",
@@ -20,16 +20,16 @@
   "main": "./lib/csdl2openapi.js",
   "exports": "./lib/csdl2openapi.js",
   "dependencies": {
-    "@discoveryjs/json-ext": "^0.5.7",
+    "@discoveryjs/json-ext": "^0.6.0",
     "odata-csdl": "^0.10.1"
   },
   "devDependencies": {
     "@apidevtools/openapi-schemas": "^2.1.0",
-    "ajv": "^8.16.0",
+    "ajv": "^8.17.1",
     "ajv-draft-04": "^1.0.0",
     "ajv-formats": "^3.0.1",
     "c8": "^10.1.2",
-    "eslint": "^9.6.0",
+    "eslint": "^9.7.0",
     "mocha": "^10.6.0"
   },
   "scripts": {

test/csdl2openapi.test.js

@@ -1845,6 +1845,7 @@ describe("Edge cases", function () {
       $Reference: {
         dummy: {
           $Include: [
+            { $Namespace: "Org.OData.Capabilities.V1", $Alias: "Capabilities" },
             { $Namespace: "Org.OData.Core.V1", $Alias: "Core" },
             { $Namespace: "Org.OData.Validation.V1", $Alias: "Validation" },
           ],
@@ -1853,7 +1854,15 @@ describe("Edge cases", function () {
       $EntityContainer: "oas31.Container",
       oas31: {
         Container: {
-          sing: { $Type: "oas31.single" },
+          set: {
+            $Type: "oas31.single",
+            $Collection: true,
+            "@Capabilities.ChangeTracking": { Supported: true },
+          },
+          sing: {
+            $Type: "oas31.single",
+            "@Capabilities.ChangeTracking": { Supported: true }, // has currently no effect
+          },
         },
         single: {
           $Kind: "EntityType",
@@ -1904,7 +1913,7 @@ describe("Edge cases", function () {
     const properties = {
       binary: { type: "string", contentEncoding: "base64url" },
       stream: { type: "string", contentEncoding: "base64url" },
-      date: { type: "string", format: "date", example: "2017-04-13" }, // example is deprecated but still allowed
+      date: { type: "string", format: "date", examples: ["2017-04-13"] },
       nullableString: { type: ["string", "null"] },
       primitive: { type: ["boolean", "number", "string"] },
       ref: { $ref: "#/components/schemas/oas31.typeDef" },
@@ -1922,7 +1931,7 @@ describe("Edge cases", function () {
       },
       refEx: {
         allOf: [{ $ref: "#/components/schemas/oas31.typeDef" }],
-        example: 11,
+        examples: [11],
       },
       refMax: {
         allOf: [{ $ref: "#/components/schemas/oas31.typeDef" }],
@@ -1942,19 +1951,19 @@ describe("Edge cases", function () {
       exclusiveMin: {
         type: ["integer", "string"],
         format: "int64",
-        example: "42",
+        examples: ["42"],
         exclusiveMinimum: 0,
       },
       max: {
         type: ["number", "string", "null"],
         format: "decimal",
-        example: 0,
+        examples: [0],
         maximum: 42,
       },
       exclusiveMax: {
         type: "number",
         format: "double",
-        example: 3.14,
+        examples: [3.14],
         exclusiveMaximum: 42,
       },
     };
@@ -1967,5 +1976,16 @@ describe("Edge cases", function () {
       properties,
       "Schemas",
     );
+    assert.deepStrictEqual(
+      openapi.paths["/set"].get.responses[200].content["application/json"]
+        .schema.properties["@odata.deltaLink"],
+      {
+        type: "string",
+        examples: [
+          "/service-root/set?$deltatoken=opaque server-generated token for fetching the delta",
+        ],
+      },
+      "delta link",
+    );
   });
 });