@scalar/oas-utils - npm Package Compare versions

Comparing version 0.2.75 to 0.2.76

CHANGELOG.md

 # @scalar/oas-utils
 
+## 0.2.76
+
+### Patch Changes
+
+- 6894b7d: feat: passes omitEmptyAndOptionalProperties from operation
+- c87353e: Add serialization back to OpenAPI spec for custom entities
+
 ## 0.2.75
@@ -4,0 +11,0 @@

dist/entities/spec/collection.d.ts

 import { z } from 'zod';
+export declare const oasCollectionSchema: z.ZodObject<{
+    /**
+     * @deprecated
+     *
+     * Needs to be remove as it is not a spec property
+     */
+    type: z.ZodDefault<z.ZodOptional<z.ZodLiteral<"collection">>>;
+    openapi: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodLiteral<"3.0.0">, z.ZodLiteral<"3.1.0">, z.ZodLiteral<"4.0.0">]>>>;
+    jsonSchemaDialect: z.ZodOptional<z.ZodString>;
+    info: z.ZodOptional<z.ZodObject<{
+        title: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        summary: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        termsOfService: z.ZodOptional<z.ZodString>;
+        contact: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            name?: string | undefined;
+            url?: string | undefined;
+            email?: string | undefined;
+        }, {
+            name?: string | undefined;
+            url?: string | undefined;
+            email?: string | undefined;
+        }>>;
+        license: z.ZodOptional<z.ZodObject<{
+            name: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            identifier: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            identifier?: string | undefined;
+            url?: string | undefined;
+        }, {
+            name?: string | undefined;
+            identifier?: string | undefined;
+            url?: string | undefined;
+        }>>;
+        version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        version: string;
+        description?: string | undefined;
+        summary?: string | undefined;
+        termsOfService?: string | undefined;
+        contact?: {
+            name?: string | undefined;
+            url?: string | undefined;
+            email?: string | undefined;
+        } | undefined;
+        license?: {
+            name: string;
+            identifier?: string | undefined;
+            url?: string | undefined;
+        } | undefined;
+    }, {
+        description?: string | undefined;
+        title?: string | undefined;
+        summary?: string | undefined;
+        termsOfService?: string | undefined;
+        contact?: {
+            name?: string | undefined;
+            url?: string | undefined;
+            email?: string | undefined;
+        } | undefined;
+        license?: {
+            name?: string | undefined;
+            identifier?: string | undefined;
+            url?: string | undefined;
+        } | undefined;
+        version?: string | undefined;
+    }>>;
+    /**
+     * A declaration of which security mechanisms can be used across the API. The list of
+     * values includes alternative security requirement objects that can be used. Only
+     * one of the security requirement objects need to be satisfied to authorize a request.
+     * Individual operations can override this definition. To make security optional, an empty
+     * security requirement ({}) can be included in the array.
+     */
+    security: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>>, "many">>>;
+    externalDocs: z.ZodOptional<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        url: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        description?: string | undefined;
+    }, {
+        description?: string | undefined;
+        url?: string | undefined;
+    }>>;
+    /** TODO: Type these */
+    components: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** TODO: Type these */
+    webhooks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** A custom icon representing the collection */
+    'x-scalar-icon': z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    'x-scalar-environment': z.ZodOptional<z.ZodString>;
+    'x-scalar-environments': z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+        variables: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+            default: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            default: string;
+            description?: string | undefined;
+        }, {
+            default?: string | undefined;
+            description?: string | undefined;
+        }>, z.ZodString]>>;
+    }, "strip", z.ZodTypeAny, {
+        variables: Record<string, string | {
+            default: string;
+            description?: string | undefined;
+        }>;
+        description?: string | undefined;
+        color?: string | undefined;
+    }, {
+        variables: Record<string, string | {
+            default?: string | undefined;
+            description?: string | undefined;
+        }>;
+        description?: string | undefined;
+        color?: string | undefined;
+    }>>>;
+    'x-scalar-secrets': z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        example: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        description?: string | undefined;
+        example?: string | undefined;
+    }, {
+        description?: string | undefined;
+        example?: string | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    type: "collection";
+    openapi: string;
+    security: Record<string, string[]>[];
+    'x-scalar-icon': string;
+    externalDocs?: {
+        url: string;
+        description?: string | undefined;
+    } | undefined;
+    jsonSchemaDialect?: string | undefined;
+    info?: {
+        title: string;
+        version: string;
+        description?: string | undefined;
+        summary?: string | undefined;
+        termsOfService?: string | undefined;
+        contact?: {
+            name?: string | undefined;
+            url?: string | undefined;
+            email?: string | undefined;
+        } | undefined;
+        license?: {
+            name: string;
+            identifier?: string | undefined;
+            url?: string | undefined;
+        } | undefined;
+    } | undefined;
+    components?: Record<string, unknown> | undefined;
+    webhooks?: Record<string, unknown> | undefined;
+    'x-scalar-environment'?: string | undefined;
+    'x-scalar-environments'?: Record<string, {
+        variables: Record<string, string | {
+            default: string;
+            description?: string | undefined;
+        }>;
+        description?: string | undefined;
+        color?: string | undefined;
+    }> | undefined;
+    'x-scalar-secrets'?: Record<string, {
+        description?: string | undefined;
+        example?: string | undefined;
+    }> | undefined;
+}, {
+    type?: "collection" | undefined;
+    externalDocs?: {
+        description?: string | undefined;
+        url?: string | undefined;
+    } | undefined;
+    openapi?: string | undefined;
+    jsonSchemaDialect?: string | undefined;
+    info?: {
+        description?: string | undefined;
+        title?: string | undefined;
+        summary?: string | undefined;
+        termsOfService?: string | undefined;
+        contact?: {
+            name?: string | undefined;
+            url?: string | undefined;
+            email?: string | undefined;
+        } | undefined;
+        license?: {
+            name?: string | undefined;
+            identifier?: string | undefined;
+            url?: string | undefined;
+        } | undefined;
+        version?: string | undefined;
+    } | undefined;
+    security?: Record<string, string[] | undefined>[] | undefined;
+    components?: Record<string, unknown> | undefined;
+    webhooks?: Record<string, unknown> | undefined;
+    'x-scalar-icon'?: string | undefined;
+    'x-scalar-environment'?: string | undefined;
+    'x-scalar-environments'?: Record<string, {
+        variables: Record<string, string | {
+            default?: string | undefined;
+            description?: string | undefined;
+        }>;
+        description?: string | undefined;
+        color?: string | undefined;
+    }> | undefined;
+    'x-scalar-secrets'?: Record<string, {
+        description?: string | undefined;
+        example?: string | undefined;
+    }> | undefined;
+}>;
 export declare const extendedCollectionSchema: z.ZodObject<{
@@ -201,2 +423,7 @@ uid: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 export declare const collectionSchema: z.ZodObject<z.objectUtil.extendShape<{
+    /**
+     * @deprecated
+     *
+     * Needs to be remove as it is not a spec property
+     */
     type: z.ZodDefault<z.ZodOptional<z.ZodLiteral<"collection">>>;
@@ -294,2 +521,41 @@ openapi: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodLiteral<"3.0.0">, z.ZodLiteral<"3.1.0">, z.ZodLiteral<"4.0.0">]>>>;
     'x-scalar-icon': z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    'x-scalar-environment': z.ZodOptional<z.ZodString>;
+    'x-scalar-environments': z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+        variables: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+            default: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            default: string;
+            description?: string | undefined;
+        }, {
+            default?: string | undefined;
+            description?: string | undefined;
+        }>, z.ZodString]>>;
+    }, "strip", z.ZodTypeAny, {
+        variables: Record<string, string | {
+            default: string;
+            description?: string | undefined;
+        }>;
+        description?: string | undefined;
+        color?: string | undefined;
+    }, {
+        variables: Record<string, string | {
+            default?: string | undefined;
+            description?: string | undefined;
+        }>;
+        description?: string | undefined;
+        color?: string | undefined;
+    }>>>;
+    'x-scalar-secrets': z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        example: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        description?: string | undefined;
+        example?: string | undefined;
+    }, {
+        description?: string | undefined;
+        example?: string | undefined;
+    }>>>;
 }, {
@@ -478,2 +744,15 @@ uid: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     webhooks?: Record<string, unknown> | undefined;
+    'x-scalar-environment'?: string | undefined;
+    'x-scalar-environments'?: Record<string, {
+        variables: Record<string, string | {
+            default: string;
+            description?: string | undefined;
+        }>;
+        description?: string | undefined;
+        color?: string | undefined;
+    }> | undefined;
+    'x-scalar-secrets'?: Record<string, {
+        description?: string | undefined;
+        example?: string | undefined;
+    }> | undefined;
     documentUrl?: string | undefined;
@@ -512,2 +791,15 @@ integration?: string | null | undefined;
     'x-scalar-icon'?: string | undefined;
+    'x-scalar-environment'?: string | undefined;
+    'x-scalar-environments'?: Record<string, {
+        variables: Record<string, string | {
+            default?: string | undefined;
+            description?: string | undefined;
+        }>;
+        description?: string | undefined;
+        color?: string | undefined;
+    }> | undefined;
+    'x-scalar-secrets'?: Record<string, {
+        description?: string | undefined;
+        example?: string | undefined;
+    }> | undefined;
     securitySchemes?: string[] | undefined;
@@ -514,0 +806,0 @@ selectedSecuritySchemeUids?: (string | undefined)[] | undefined;

dist/entities/spec/collection.js

 import { oasSecurityRequirementSchema, securitySchemeExampleValueSchema } from './security.js';
+import { xScalarEnvironmentsSchema } from './x-scalar-environments.js';
+import { xScalarSecretsSchema } from './x-scalar-secrets.js';
 import { z } from 'zod';
@@ -7,2 +9,7 @@ import { oasInfoSchema, oasExternalDocumentationSchema } from './spec-objects.js';
 const oasCollectionSchema = z.object({
+    /**
+     * @deprecated
+     *
+     * Needs to be remove as it is not a spec property
+     */
     'type': z.literal('collection').optional().default('collection'),
@@ -35,2 +42,5 @@ 'openapi': z
     'x-scalar-icon': z.string().optional().default('interface-content-folder'),
+    'x-scalar-environment': z.string().optional(),
+    'x-scalar-environments': xScalarEnvironmentsSchema.optional(),
+    'x-scalar-secrets': xScalarSecretsSchema.optional(),
     // These properties will be stripped out and mapped back as id lists
@@ -88,2 +98,2 @@ // servers
 
-export { collectionSchema, extendedCollectionSchema };
+export { collectionSchema, extendedCollectionSchema, oasCollectionSchema };

dist/entities/spec/index.js

@@ -1,7 +0,7 @@
-export { collectionSchema, extendedCollectionSchema } from './collection.js';
+export { collectionSchema, extendedCollectionSchema, oasCollectionSchema } from './collection.js';
 export { oasServerSchema, oasServerVariableSchema, serverSchema } from './server.js';
 export { oasRequestSchema, requestMethods, requestSchema } from './requests.js';
-export { createExampleFromRequest, createParamInstance, exampleRequestBodyEncoding, exampleRequestBodySchema, requestExampleParametersSchema, requestExampleSchema } from './request-examples.js';
+export { convertExampleToXScalar, createExampleFromRequest, createParamInstance, exampleBodyMime, exampleRequestBodyEncoding, exampleRequestBodySchema, requestExampleParametersSchema, requestExampleSchema, xScalarExampleBodySchema, xScalarExampleSchema, xScalarFileValueSchema, xScalarFormDataValue } from './request-examples.js';
 export { oasContactSchema, oasExternalDocumentationSchema, oasInfoSchema, oasLicenseSchema, oasTagSchema, tagSchema, xScalarNestedSchema } from './spec-objects.js';
 export { oasParameterSchema, parameterStyleSchema, parameterTypeSchema } from './parameters.js';
 export { authExampleFromSchema, oasOauthFlowSchema, oasSecurityRequirementSchema, oasSecuritySchemeSchema, pkceOptions, securityApiKeySchema, securityHttpSchema, securityOauthSchema, securityOpenIdSchema, securitySchemeApiKeyIn, securitySchemeExampleValueSchema, securitySchemeSchema } from './security.js';

dist/entities/spec/parameters.d.ts

@@ -38,6 +38,6 @@ import { z } from 'zod';
     description?: string | undefined;
+    example?: unknown;
     schema?: unknown;
     content?: unknown;
     style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-    example?: unknown;
     examples?: Record<string, {
@@ -52,2 +52,3 @@ value?: unknown;
     description?: string | undefined;
+    example?: unknown;
     deprecated?: boolean | undefined;
@@ -57,3 +58,2 @@ schema?: unknown;
     style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-    example?: unknown;
     examples?: Record<string, {
@@ -60,0 +60,0 @@ value?: unknown;

dist/entities/spec/request-examples.d.ts

@@ -5,2 +5,8 @@ import { z } from 'zod';
 import type { Server } from './server.js';
+/**
+ * TODO: Deprecate this.
+ *
+ * The request schema should be stored in the request and any
+ * parameters should be validated against that
+ */
 export declare const requestExampleParametersSchema: z.ZodObject<{
@@ -12,4 +18,2 @@ key: z.ZodDefault<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
-    /** Params are linked to parents such as path params and global headers/cookies */
-    refUid: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodString>>>;
     required: z.ZodOptional<z.ZodBoolean>;
@@ -36,3 +40,2 @@ enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     file?: any;
-    refUid?: string | undefined;
     nullable?: boolean | undefined;
@@ -52,3 +55,2 @@ }, {
     file?: any;
-    refUid?: string | undefined;
     nullable?: boolean | undefined;
@@ -58,3 +60,58 @@ }>;
 export type RequestExampleParameter = z.infer<typeof requestExampleParametersSchema>;
+export declare const xScalarFileValueSchema: z.ZodNullable<z.ZodObject<{
+    url: z.ZodString;
+    base64: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    base64?: string | undefined;
+}, {
+    url: string;
+    base64?: string | undefined;
+}>>;
 /**
+ * When files are required for an example we provide the options
+ * to provide a public URL or a base64 encoded string
+ */
+export type XScalarFileValue = z.infer<typeof xScalarFileValueSchema>;
+/**
+ * Schema for the OAS serialization of request example parameters
+ *
+ * File values can be optionally fetched on import OR inserted as a base64 encoded string
+ */
+export declare const xScalarFormDataValue: z.ZodUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"string">;
+    value: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "string";
+    value: string;
+}, {
+    type: "string";
+    value: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    file: z.ZodNullable<z.ZodObject<{
+        url: z.ZodString;
+        base64: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        base64?: string | undefined;
+    }, {
+        url: string;
+        base64?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: "file";
+    file: {
+        url: string;
+        base64?: string | undefined;
+    } | null;
+}, {
+    type: "file";
+    file: {
+        url: string;
+        base64?: string | undefined;
+    } | null;
+}>]>;
+export type XScalarFormDataValue = z.infer<typeof xScalarFormDataValue>;
+/**
  * Possible encodings for example request bodies when using text formats
@@ -66,2 +123,9 @@ *
 export type BodyEncoding = (typeof exampleRequestBodyEncoding)[number];
+export declare const exampleBodyMime: readonly ["application/json", "text/plain", "text/html", "application/javascript", "application/xml", "application/yaml", "application/edn", "application/octet-stream", "application/x-www-form-urlencoded", "multipart/form-data", "binary"];
+export type BodyMime = (typeof exampleBodyMime)[number];
+/**
+ * TODO: Migrate away from this layout to the format used in the extension
+ *
+ * If a user changes the encoding of the body we expect the content to change as well
+ */
 export declare const exampleRequestBodySchema: z.ZodObject<{
@@ -86,4 +150,2 @@ raw: z.ZodOptional<z.ZodObject<{
             description: z.ZodOptional<z.ZodString>;
-            /** Params are linked to parents such as path params and global headers/cookies */
-            refUid: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodString>>>;
             required: z.ZodOptional<z.ZodBoolean>;
@@ -110,3 +172,2 @@ enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -126,3 +187,2 @@ }, {
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -144,3 +204,2 @@ }>, "many">>;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -163,3 +222,2 @@ }[];
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -172,3 +230,3 @@ }[] | undefined;
 }, "strip", z.ZodTypeAny, {
-    activeBody: "formData" | "raw" | "binary";
+    activeBody: "formData" | "binary" | "raw";
     formData?: {
@@ -188,3 +246,2 @@ value: {
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -194,2 +251,3 @@ }[];
     } | undefined;
+    binary?: Blob | undefined;
     raw?: {
@@ -199,3 +257,2 @@ value: string;
     } | undefined;
-    binary?: Blob | undefined;
 }, {
@@ -216,3 +273,2 @@ formData?: {
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -222,2 +278,3 @@ }[] | undefined;
     } | undefined;
+    binary?: Blob | undefined;
     raw?: {
@@ -227,9 +284,44 @@ value?: string | undefined;
     } | undefined;
-    binary?: Blob | undefined;
-    activeBody?: "formData" | "raw" | "binary" | undefined;
+    activeBody?: "formData" | "binary" | "raw" | undefined;
 }>;
 export type ExampleRequestBody = z.infer<typeof exampleRequestBodySchema>;
+/** Schema for the OAS serialization of request example bodies */
+export declare const xScalarExampleBodySchema: z.ZodObject<{
+    encoding: z.ZodDefault<z.ZodEnum<["application/json", "text/plain", "text/html", "application/javascript", "application/xml", "application/yaml", "application/edn", "application/octet-stream", "application/x-www-form-urlencoded", "multipart/form-data", "binary"]>>;
+    /**
+     * Body content as an object with a separately specified encoding or a simple pre-encoded string value
+     *
+     * Ideally we would convert any objects into the proper encoding on import
+     */
+    content: z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodString]>;
+    /** When the encoding is `binary` this will be used to link to the file */
+    file: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        url: z.ZodString;
+        base64: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        base64?: string | undefined;
+    }, {
+        url: string;
+        base64?: string | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    content: string | Record<string, any>;
+    encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+    file?: {
+        url: string;
+        base64?: string | undefined;
+    } | null | undefined;
+}, {
+    content: string | Record<string, any>;
+    file?: {
+        url: string;
+        base64?: string | undefined;
+    } | null | undefined;
+    encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+}>;
+export type XScalarExampleBody = z.infer<typeof xScalarExampleBodySchema>;
 export declare const requestExampleSchema: z.ZodObject<{
+    uid: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     type: z.ZodDefault<z.ZodOptional<z.ZodLiteral<"requestExample">>>;
-    uid: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     requestUid: z.ZodDefault<z.ZodOptional<z.ZodString>>;
@@ -256,4 +348,2 @@ name: z.ZodDefault<z.ZodOptional<z.ZodString>>;
                 description: z.ZodOptional<z.ZodString>;
-                /** Params are linked to parents such as path params and global headers/cookies */
-                refUid: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodString>>>;
                 required: z.ZodOptional<z.ZodBoolean>;
@@ -280,3 +370,2 @@ enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
                 file?: any;
-                refUid?: string | undefined;
                 nullable?: boolean | undefined;
@@ -296,3 +385,2 @@ }, {
                 file?: any;
-                refUid?: string | undefined;
                 nullable?: boolean | undefined;
@@ -314,3 +402,2 @@ }>, "many">>;
                 file?: any;
-                refUid?: string | undefined;
                 nullable?: boolean | undefined;
@@ -333,3 +420,2 @@ }[];
                 file?: any;
-                refUid?: string | undefined;
                 nullable?: boolean | undefined;
@@ -342,3 +428,3 @@ }[] | undefined;
     }, "strip", z.ZodTypeAny, {
-        activeBody: "formData" | "raw" | "binary";
+        activeBody: "formData" | "binary" | "raw";
         formData?: {
@@ -358,3 +444,2 @@ value: {
                 file?: any;
-                refUid?: string | undefined;
                 nullable?: boolean | undefined;
@@ -364,2 +449,3 @@ }[];
         } | undefined;
+        binary?: Blob | undefined;
         raw?: {
@@ -369,3 +455,2 @@ value: string;
         } | undefined;
-        binary?: Blob | undefined;
     }, {
@@ -386,3 +471,2 @@ formData?: {
                 file?: any;
-                refUid?: string | undefined;
                 nullable?: boolean | undefined;
@@ -392,2 +476,3 @@ }[] | undefined;
         } | undefined;
+        binary?: Blob | undefined;
         raw?: {
@@ -397,4 +482,3 @@ value?: string | undefined;
         } | undefined;
-        binary?: Blob | undefined;
-        activeBody?: "formData" | "raw" | "binary" | undefined;
+        activeBody?: "formData" | "binary" | "raw" | undefined;
     }>>>;
@@ -408,4 +492,2 @@ parameters: z.ZodDefault<z.ZodOptional<z.ZodObject<{
             description: z.ZodOptional<z.ZodString>;
-            /** Params are linked to parents such as path params and global headers/cookies */
-            refUid: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodString>>>;
             required: z.ZodOptional<z.ZodBoolean>;
@@ -432,3 +514,2 @@ enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -448,3 +529,2 @@ }, {
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -458,4 +538,2 @@ }>, "many">>;
             description: z.ZodOptional<z.ZodString>;
-            /** Params are linked to parents such as path params and global headers/cookies */
-            refUid: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodString>>>;
             required: z.ZodOptional<z.ZodBoolean>;
@@ -482,3 +560,2 @@ enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -498,3 +575,2 @@ }, {
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -508,4 +584,2 @@ }>, "many">>;
             description: z.ZodOptional<z.ZodString>;
-            /** Params are linked to parents such as path params and global headers/cookies */
-            refUid: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodString>>>;
             required: z.ZodOptional<z.ZodBoolean>;
@@ -532,3 +606,2 @@ enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -548,3 +621,2 @@ }, {
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -558,4 +630,2 @@ }>, "many">>;
             description: z.ZodOptional<z.ZodString>;
-            /** Params are linked to parents such as path params and global headers/cookies */
-            refUid: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodString>>>;
             required: z.ZodOptional<z.ZodBoolean>;
@@ -582,3 +652,2 @@ enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -598,3 +667,2 @@ }, {
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -616,3 +684,2 @@ }>, "many">>;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -633,3 +700,2 @@ }[];
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -650,3 +716,2 @@ }[];
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -667,3 +732,2 @@ }[];
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -685,3 +749,2 @@ }[];
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -702,3 +765,2 @@ }[] | undefined;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -719,3 +781,2 @@ }[] | undefined;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -736,6 +797,6 @@ }[] | undefined;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
         }[] | undefined;
     }>>>;
+    /** TODO: Should this be deprecated? */
     serverVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
@@ -747,3 +808,3 @@ }, "strip", z.ZodTypeAny, {
     body: {
-        activeBody: "formData" | "raw" | "binary";
+        activeBody: "formData" | "binary" | "raw";
         formData?: {
@@ -763,3 +824,2 @@ value: {
                 file?: any;
-                refUid?: string | undefined;
                 nullable?: boolean | undefined;
@@ -769,2 +829,3 @@ }[];
         } | undefined;
+        binary?: Blob | undefined;
         raw?: {
@@ -774,3 +835,2 @@ value: string;
         } | undefined;
-        binary?: Blob | undefined;
     };
@@ -792,3 +852,2 @@ requestUid: string;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -809,3 +868,2 @@ }[];
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -826,3 +884,2 @@ }[];
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -843,3 +900,2 @@ }[];
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -868,3 +924,2 @@ }[];
                 file?: any;
-                refUid?: string | undefined;
                 nullable?: boolean | undefined;
@@ -874,2 +929,3 @@ }[] | undefined;
         } | undefined;
+        binary?: Blob | undefined;
         raw?: {
@@ -879,4 +935,3 @@ value?: string | undefined;
         } | undefined;
-        binary?: Blob | undefined;
-        activeBody?: "formData" | "raw" | "binary" | undefined;
+        activeBody?: "formData" | "binary" | "raw" | undefined;
     } | undefined;
@@ -898,3 +953,2 @@ requestUid?: string | undefined;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -915,3 +969,2 @@ }[] | undefined;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -932,3 +985,2 @@ }[] | undefined;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -949,3 +1001,2 @@ }[] | undefined;
             file?: any;
-            refUid?: string | undefined;
             nullable?: boolean | undefined;
@@ -956,5 +1007,113 @@ }[] | undefined;
 }>;
-/** A single set 23of params for a request example */
 export type RequestExample = z.infer<typeof requestExampleSchema>;
-export type RequestExamplePayload = z.input<typeof requestExampleSchema>;
+/** Schema for the OAS serialization of request examples */
+export declare const xScalarExampleSchema: z.ZodObject<{
+    /** TODO: Should this be required? */
+    name: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodObject<{
+        encoding: z.ZodDefault<z.ZodEnum<["application/json", "text/plain", "text/html", "application/javascript", "application/xml", "application/yaml", "application/edn", "application/octet-stream", "application/x-www-form-urlencoded", "multipart/form-data", "binary"]>>;
+        /**
+         * Body content as an object with a separately specified encoding or a simple pre-encoded string value
+         *
+         * Ideally we would convert any objects into the proper encoding on import
+         */
+        content: z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodString]>;
+        /** When the encoding is `binary` this will be used to link to the file */
+        file: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            url: z.ZodString;
+            base64: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            url: string;
+            base64?: string | undefined;
+        }, {
+            url: string;
+            base64?: string | undefined;
+        }>>>;
+    }, "strip", z.ZodTypeAny, {
+        content: string | Record<string, any>;
+        encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+        file?: {
+            url: string;
+            base64?: string | undefined;
+        } | null | undefined;
+    }, {
+        content: string | Record<string, any>;
+        file?: {
+            url: string;
+            base64?: string | undefined;
+        } | null | undefined;
+        encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+    }>>;
+    parameters: z.ZodObject<{
+        path: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cookies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        path?: Record<string, string> | undefined;
+        cookies?: Record<string, string> | undefined;
+        query?: Record<string, string> | undefined;
+        headers?: Record<string, string> | undefined;
+    }, {
+        path?: Record<string, string> | undefined;
+        cookies?: Record<string, string> | undefined;
+        query?: Record<string, string> | undefined;
+        headers?: Record<string, string> | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    parameters: {
+        path?: Record<string, string> | undefined;
+        cookies?: Record<string, string> | undefined;
+        query?: Record<string, string> | undefined;
+        headers?: Record<string, string> | undefined;
+    };
+    name?: string | undefined;
+    body?: {
+        content: string | Record<string, any>;
+        encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+        file?: {
+            url: string;
+            base64?: string | undefined;
+        } | null | undefined;
+    } | undefined;
+}, {
+    parameters: {
+        path?: Record<string, string> | undefined;
+        cookies?: Record<string, string> | undefined;
+        query?: Record<string, string> | undefined;
+        headers?: Record<string, string> | undefined;
+    };
+    name?: string | undefined;
+    body?: {
+        content: string | Record<string, any>;
+        file?: {
+            url: string;
+            base64?: string | undefined;
+        } | null | undefined;
+        encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+    } | undefined;
+}>;
+export type XScalarExample = z.infer<typeof xScalarExampleSchema>;
+/**
+ * Convert a request example to the xScalar serialized format
+ *
+ * TODO: The base format should be migrated to align MUCH closer to the serialized format
+ */
+export declare function convertExampleToXScalar(example: RequestExample): {
+    parameters: {
+        path?: Record<string, string> | undefined;
+        cookies?: Record<string, string> | undefined;
+        query?: Record<string, string> | undefined;
+        headers?: Record<string, string> | undefined;
+    };
+    name?: string | undefined;
+    body?: {
+        content: string | Record<string, any>;
+        encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+        file?: {
+            url: string;
+            base64?: string | undefined;
+        } | null | undefined;
+    } | undefined;
+};
 /** Create new instance parameter from a request parameter */
@@ -974,3 +1133,2 @@ export declare function createParamInstance(param: RequestParameter): {
     file?: any;
-    refUid?: string | undefined;
     nullable?: boolean | undefined;
@@ -977,0 +1135,0 @@ };

dist/entities/spec/request-examples.js

@@ -0,1 +1,2 @@
+import { keysOf } from '@scalar/object-utils/arrays';
 import { z } from 'zod';
@@ -7,2 +8,10 @@ import { schemaModel } from '../../helpers/schema-model.js';
 
+// ---------------------------------------------------------------------------
+// Example Parameters
+/**
+ * TODO: Deprecate this.
+ *
+ * The request schema should be stored in the request and any
+ * parameters should be validated against that
+ */
 const requestExampleParametersSchema = z.object({
@@ -14,4 +23,2 @@ key: z.string().default(''),
     description: z.string().optional(),
-    /** Params are linked to parents such as path params and global headers/cookies */
-    refUid: nanoidSchema.optional(),
     required: z.boolean().optional(),
@@ -26,3 +33,33 @@ enum: z.array(z.string()).optional(),
 });
+/** Convert the array of parameters to an object keyed by the parameter name */
+function parameterArrayToObject(params) {
+    return params.reduce((map, param) => {
+        map[param.key] = param.value;
+        return map;
+    }, {});
+}
+const xScalarFileValueSchema = z
+    .object({
+    url: z.string(),
+    base64: z.string().optional(),
+})
+    .nullable();
 /**
+ * Schema for the OAS serialization of request example parameters
+ *
+ * File values can be optionally fetched on import OR inserted as a base64 encoded string
+ */
+const xScalarFormDataValue = z.union([
+    z.object({
+        type: z.literal('string'),
+        value: z.string(),
+    }),
+    z.object({
+        type: z.literal('file'),
+        file: xScalarFileValueSchema,
+    }),
+]);
+// ---------------------------------------------------------------------------
+// Example Body
+/**
  * Possible encodings for example request bodies when using text formats
@@ -41,2 +78,30 @@ *
 ];
+const exampleBodyMime = [
+    'application/json',
+    'text/plain',
+    'text/html',
+    'application/javascript',
+    'application/xml',
+    'application/yaml',
+    'application/edn',
+    'application/octet-stream',
+    'application/x-www-form-urlencoded',
+    'multipart/form-data',
+    /** Used for direct files */
+    'binary',
+];
+const contentMapping = {
+    json: 'application/json',
+    text: 'text/plain',
+    html: 'text/html',
+    javascript: 'application/javascript',
+    xml: 'application/xml',
+    yaml: 'application/yaml',
+    edn: 'application/edn',
+};
+/**
+ * TODO: Migrate away from this layout to the format used in the extension
+ *
+ * If a user changes the encoding of the body we expect the content to change as well
+ */
 const exampleRequestBodySchema = z.object({
@@ -62,5 +127,19 @@ raw: z
 });
+/** Schema for the OAS serialization of request example bodies */
+const xScalarExampleBodySchema = z.object({
+    encoding: z.enum(exampleBodyMime).default('application/json'),
+    /**
+     * Body content as an object with a separately specified encoding or a simple pre-encoded string value
+     *
+     * Ideally we would convert any objects into the proper encoding on import
+     */
+    content: z.union([z.record(z.string(), z.any()), z.string()]),
+    /** When the encoding is `binary` this will be used to link to the file */
+    file: xScalarFileValueSchema.optional(),
+});
+// ---------------------------------------------------------------------------
+// Example Schema
 const requestExampleSchema = z.object({
+    uid: nanoidSchema,
     type: z.literal('requestExample').optional().default('requestExample'),
-    uid: nanoidSchema,
     requestUid: nanoidSchema,
@@ -78,4 +157,77 @@ name: z.string().optional().default('Name'),
         .default({}),
+    /** TODO: Should this be deprecated? */
     serverVariables: z.record(z.string(), z.array(z.string())).optional(),
 });
+/** For OAS serialization we just store the simple key/value pairs */
+const xScalarExampleParameterSchema = z
+    .record(z.string(), z.string())
+    .optional();
+/** Schema for the OAS serialization of request examples */
+const xScalarExampleSchema = z.object({
+    /** TODO: Should this be required? */
+    name: z.string().optional(),
+    body: xScalarExampleBodySchema.optional(),
+    parameters: z.object({
+        path: xScalarExampleParameterSchema,
+        query: xScalarExampleParameterSchema,
+        headers: xScalarExampleParameterSchema,
+        cookies: xScalarExampleParameterSchema,
+    }),
+});
+/**
+ * Convert a request example to the xScalar serialized format
+ *
+ * TODO: The base format should be migrated to align MUCH closer to the serialized format
+ */
+function convertExampleToXScalar(example) {
+    const active = example.body?.activeBody;
+    const xScalarBody = {
+        encoding: 'text/plain',
+        content: '',
+    };
+    if (example.body?.activeBody === 'binary') {
+        xScalarBody.encoding = 'binary';
+        // TODO: Need to allow users to set these properties
+        xScalarBody.file = null;
+    }
+    if (active === 'formData' && example.body?.[active]) {
+        const body = example.body[active];
+        xScalarBody.encoding =
+            body.encoding === 'form-data'
+                ? 'multipart/form-data'
+                : 'application/x-www-form-urlencoded';
+        // TODO: Need to allow users to set these properties
+        xScalarBody.content = body.value.reduce((map, param) => {
+            /** TODO: We need to ensure only file or value is set */
+            map[param.key] = param.file
+                ? {
+                    type: 'file',
+                    file: null,
+                }
+                : {
+                    type: 'string',
+                    value: param.value,
+                };
+            return map;
+        }, {});
+    }
+    if (example.body?.activeBody === 'raw') {
+        xScalarBody.encoding =
+            contentMapping[example.body.raw?.encoding ?? 'text'] ?? 'text/plain';
+        xScalarBody.content = example.body.raw?.value ?? '';
+    }
+    const parameters = {};
+    keysOf(example.parameters ?? {}).forEach((key) => {
+        if (example.parameters?.[key].length) {
+            parameters[key] = parameterArrayToObject(example.parameters[key]);
+        }
+    });
+    return xScalarExampleSchema.parse({
+        /** Only add the body if we have content or the body should be a file */
+        body: xScalarBody.content || xScalarBody.encoding === 'binary'
+            ? xScalarBody
+            : undefined,
+        parameters,
+    });
+}
 // ---------------------------------------------------------------------------
@@ -207,2 +359,2 @@ // Example Helpers
 
-export { createExampleFromRequest, createParamInstance, exampleRequestBodyEncoding, exampleRequestBodySchema, requestExampleParametersSchema, requestExampleSchema };
+export { convertExampleToXScalar, createExampleFromRequest, createParamInstance, exampleBodyMime, exampleRequestBodyEncoding, exampleRequestBodySchema, requestExampleParametersSchema, requestExampleSchema, xScalarExampleBodySchema, xScalarExampleSchema, xScalarFileValueSchema, xScalarFormDataValue };

dist/entities/spec/requests.d.ts

 import { z } from 'zod';
-import type { RequestExample } from './request-examples.js';
+import { type RequestExample } from './request-examples.js';
 export declare const requestMethods: readonly ["connect", "delete", "get", "head", "options", "patch", "post", "put", "trace"];
@@ -93,6 +93,6 @@ export type RequestMethod = (typeof requestMethods)[number];
         description?: string | undefined;
+        example?: unknown;
         schema?: unknown;
         content?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
@@ -107,2 +107,3 @@ value?: unknown;
         description?: string | undefined;
+        example?: unknown;
         deprecated?: boolean | undefined;
@@ -112,3 +113,2 @@ schema?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
@@ -135,2 +135,82 @@ value?: unknown;
     responses: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    /** xScalar examples */
+    'x-scalar-examples': z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodObject<{
+            encoding: z.ZodDefault<z.ZodEnum<["application/json", "text/plain", "text/html", "application/javascript", "application/xml", "application/yaml", "application/edn", "application/octet-stream", "application/x-www-form-urlencoded", "multipart/form-data", "binary"]>>;
+            content: z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodString]>;
+            file: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                url: z.ZodString;
+                base64: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                url: string;
+                base64?: string | undefined;
+            }, {
+                url: string;
+                base64?: string | undefined;
+            }>>>;
+        }, "strip", z.ZodTypeAny, {
+            content: string | Record<string, any>;
+            encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+        }, {
+            content: string | Record<string, any>;
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+            encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+        }>>;
+        parameters: z.ZodObject<{
+            path: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cookies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        }, {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        parameters: {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        };
+        name?: string | undefined;
+        body?: {
+            content: string | Record<string, any>;
+            encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+        } | undefined;
+    }, {
+        parameters: {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        };
+        name?: string | undefined;
+        body?: {
+            content: string | Record<string, any>;
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+            encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+        } | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
@@ -153,6 +233,6 @@ description?: string | undefined;
         description?: string | undefined;
+        example?: unknown;
         schema?: unknown;
         content?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
@@ -165,2 +245,19 @@ value?: unknown;
     responses?: Record<string, any> | undefined;
+    'x-scalar-examples'?: Record<string, {
+        parameters: {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        };
+        name?: string | undefined;
+        body?: {
+            content: string | Record<string, any>;
+            encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+        } | undefined;
+    }> | undefined;
 }, {
@@ -182,2 +279,3 @@ description?: string | undefined;
         description?: string | undefined;
+        example?: unknown;
         deprecated?: boolean | undefined;
@@ -187,3 +285,2 @@ schema?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
@@ -196,5 +293,22 @@ value?: unknown;
     responses?: Record<string, any> | undefined;
+    'x-scalar-examples'?: Record<string, {
+        parameters: {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        };
+        name?: string | undefined;
+        body?: {
+            content: string | Record<string, any>;
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+            encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+        } | undefined;
+    }> | undefined;
 }>;
 /** Unified request schema for client usage */
-export declare const requestSchema: z.ZodObject<z.objectUtil.extendShape<{
+export declare const requestSchema: z.ZodObject<z.objectUtil.extendShape<Omit<{
     /**
@@ -261,6 +375,6 @@ * A list of tags for API documentation control. Tags can be used for logical
         description?: string | undefined;
+        example?: unknown;
         schema?: unknown;
         content?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
@@ -275,2 +389,3 @@ value?: unknown;
         description?: string | undefined;
+        example?: unknown;
         deprecated?: boolean | undefined;
@@ -280,3 +395,2 @@ schema?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
@@ -303,3 +417,83 @@ value?: unknown;
     responses: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
-}, {
+    /** xScalar examples */
+    'x-scalar-examples': z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodObject<{
+            encoding: z.ZodDefault<z.ZodEnum<["application/json", "text/plain", "text/html", "application/javascript", "application/xml", "application/yaml", "application/edn", "application/octet-stream", "application/x-www-form-urlencoded", "multipart/form-data", "binary"]>>;
+            content: z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodString]>;
+            file: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                url: z.ZodString;
+                base64: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                url: string;
+                base64?: string | undefined;
+            }, {
+                url: string;
+                base64?: string | undefined;
+            }>>>;
+        }, "strip", z.ZodTypeAny, {
+            content: string | Record<string, any>;
+            encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+        }, {
+            content: string | Record<string, any>;
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+            encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+        }>>;
+        parameters: z.ZodObject<{
+            path: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cookies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        }, {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        parameters: {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        };
+        name?: string | undefined;
+        body?: {
+            content: string | Record<string, any>;
+            encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+        } | undefined;
+    }, {
+        parameters: {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        };
+        name?: string | undefined;
+        body?: {
+            content: string | Record<string, any>;
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+            encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+        } | undefined;
+    }>>>;
+}, "x-scalar-examples">, {
     type: z.ZodDefault<z.ZodOptional<z.ZodLiteral<"request">>>;
@@ -344,6 +538,6 @@ uid: z.ZodDefault<z.ZodOptional<z.ZodString>>;
         description?: string | undefined;
+        example?: unknown;
         schema?: unknown;
         content?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
@@ -380,2 +574,3 @@ value?: unknown;
         description?: string | undefined;
+        example?: unknown;
         deprecated?: boolean | undefined;
@@ -385,3 +580,2 @@ schema?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
@@ -388,0 +582,0 @@ value?: unknown;

dist/entities/spec/requests.js

 import { z } from 'zod';
 import { oasParameterSchema } from './parameters.js';
+import { xScalarExampleSchema } from './request-examples.js';
 import { oasSecurityRequirementSchema } from './security.js';
@@ -27,7 +28,7 @@ import { oasExternalDocumentationSchema } from './spec-objects.js';
      */
-    tags: z.string().array().optional(),
+    'tags': z.string().array().optional(),
     /** A short summary of what the operation does. */
-    summary: z.string().optional(),
+    'summary': z.string().optional(),
     /** A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation. */
-    description: z.string().optional(),
+    'description': z.string().optional(),
     /**
@@ -38,3 +39,3 @@ * Unique string used to identify the operation. The id MUST be unique among all operations described in the API.
      */
-    operationId: z.string().optional(),
+    'operationId': z.string().optional(),
     /**
@@ -47,3 +48,3 @@ * A declaration of which security mechanisms can be used across the API. The list of
      */
-    security: z.array(oasSecurityRequirementSchema).optional(),
+    'security': z.array(oasSecurityRequirementSchema).optional(),
     /**
@@ -55,14 +56,16 @@ * The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the
      */
-    requestBody: requestBodySchema.optional(),
+    'requestBody': requestBodySchema.optional(),
     /**
      * Request parameters
      */
-    parameters: oasParameterSchema.array().optional(),
+    'parameters': oasParameterSchema.array().optional(),
     /**
      * External documentation object
      */
-    externalDocs: oasExternalDocumentationSchema.optional(),
-    deprecated: z.boolean().optional(),
+    'externalDocs': oasExternalDocumentationSchema.optional(),
+    'deprecated': z.boolean().optional(),
     /** Response formats */
-    responses: z.record(z.string(), z.any()).optional(),
+    'responses': z.record(z.string(), z.any()).optional(),
+    /** xScalar examples */
+    'x-scalar-examples': z.record(z.string(), xScalarExampleSchema).optional(),
 });
@@ -93,4 +96,6 @@ /**
 /** Unified request schema for client usage */
-const requestSchema = oasRequestSchema.merge(extendedRequestSchema);
+const requestSchema = oasRequestSchema
+    .omit({ 'x-scalar-examples': true })
+    .merge(extendedRequestSchema);
 
 export { oasRequestSchema, requestMethods, requestSchema };

dist/entities/spec/server.d.ts

@@ -40,6 +40,6 @@ import type { OpenAPIV3_1 } from '@scalar/openapi-types';
     description?: string | undefined;
-    url?: string | undefined;
     variables?: Record<string, Omit<OpenAPIV3_1.ServerVariableObject, "enum"> & {
         enum?: [string, ...string[]];
     }> | undefined;
+    url?: string | undefined;
 }>;
@@ -76,6 +76,6 @@ export declare const serverSchema: z.ZodObject<z.objectUtil.extendShape<{
     description?: string | undefined;
-    url?: string | undefined;
     variables?: Record<string, Omit<OpenAPIV3_1.ServerVariableObject, "enum"> & {
         enum?: [string, ...string[]];
     }> | undefined;
+    url?: string | undefined;
 }>;
@@ -82,0 +82,0 @@ export type Server = z.infer<typeof serverSchema>;

dist/entities/spec/spec-objects.d.ts

@@ -173,2 +173,7 @@ import { z } from 'zod';
 export declare const oasTagSchema: z.ZodObject<{
+    /**
+     * @deprecated
+     *
+     * Needs to be remove as it is not a spec property
+     */
     type: z.ZodDefault<z.ZodOptional<z.ZodLiteral<"tag">>>;
@@ -192,3 +197,3 @@ /** REQUIRED. The name of the tag. */
     }>>;
-    'x-scalar-children': z.ZodDefault<z.ZodArray<z.ZodObject<{
+    'x-scalar-children': z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
         tagName: z.ZodString;
@@ -199,9 +204,6 @@ }, "strip", z.ZodTypeAny, {
         tagName: string;
-    }>, "many">>;
+    }>, "many">>>;
 }, "strip", z.ZodTypeAny, {
     type: "tag";
     name: string;
-    'x-scalar-children': {
-        tagName: string;
-    }[];
     description?: string | undefined;
@@ -212,2 +214,5 @@ externalDocs?: {
     } | undefined;
+    'x-scalar-children'?: {
+        tagName: string;
+    }[] | undefined;
 }, {
@@ -226,2 +231,7 @@ name: string;
 export declare const tagSchema: z.ZodObject<z.objectUtil.extendShape<{
+    /**
+     * @deprecated
+     *
+     * Needs to be remove as it is not a spec property
+     */
     type: z.ZodDefault<z.ZodOptional<z.ZodLiteral<"tag">>>;
@@ -245,3 +255,3 @@ /** REQUIRED. The name of the tag. */
     }>>;
-    'x-scalar-children': z.ZodDefault<z.ZodArray<z.ZodObject<{
+    'x-scalar-children': z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
         tagName: z.ZodString;
@@ -252,3 +262,3 @@ }, "strip", z.ZodTypeAny, {
         tagName: string;
-    }>, "many">>;
+    }>, "many">>>;
 }, {
@@ -261,5 +271,2 @@ uid: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     name: string;
-    'x-scalar-children': {
-        tagName: string;
-    }[];
     children: string[];
@@ -271,2 +278,5 @@ description?: string | undefined;
     } | undefined;
+    'x-scalar-children'?: {
+        tagName: string;
+    }[] | undefined;
 }, {
@@ -273,0 +283,0 @@ name: string;

dist/entities/spec/spec-objects.js

@@ -85,2 +85,7 @@ import { z } from 'zod';
 const oasTagSchema = z.object({
+    /**
+     * @deprecated
+     *
+     * Needs to be remove as it is not a spec property
+     */
     'type': z.literal('tag').optional().default('tag'),
@@ -93,3 +98,3 @@ /** REQUIRED. The name of the tag. */
     'externalDocs': oasExternalDocumentationSchema.optional(),
-    'x-scalar-children': xScalarNestedSchema.default([]),
+    'x-scalar-children': xScalarNestedSchema.default([]).optional(),
 });
@@ -96,0 +101,0 @@ const tagSchema = oasTagSchema.extend({

dist/migrations/v-2.1.0/migration.d.ts

@@ -203,6 +203,6 @@ import type { v_0_0_0 } from '../../migrations/v-0.0.0/types.generated';
             description?: string | undefined;
+            example?: unknown;
             schema?: unknown;
             content?: unknown;
             style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-            example?: unknown;
             examples?: Record<string, {
@@ -209,0 +209,0 @@ value?: unknown;

dist/spec-getters/getExampleFromSchema.d.ts

@@ -26,2 +26,3 @@ /**
      * Whether to omit empty and optional properties.
+     * @default false
      */
@@ -28,0 +29,0 @@ omitEmptyAndOptionalProperties?: boolean;

dist/spec-getters/getRequestBodyFromOperation.d.ts

@@ -6,3 +6,3 @@ import type { TransformedOperation } from '@scalar/types/legacy';
  */
-export declare function getRequestBodyFromOperation(operation: Omit<TransformedOperation, 'httpVerb'>, selectedExampleKey?: string | number): {
+export declare function getRequestBodyFromOperation(operation: Omit<TransformedOperation, 'httpVerb'>, selectedExampleKey?: string | number, omitEmptyAndOptionalProperties?: boolean): {
     headers?: {
@@ -9,0 +9,0 @@ name: string;

dist/spec-getters/getRequestBodyFromOperation.js

@@ -32,3 +32,3 @@ import { json2xml } from '../helpers/json2xml.js';
  */
-function getRequestBodyFromOperation(operation, selectedExampleKey) {
+function getRequestBodyFromOperation(operation, selectedExampleKey, omitEmptyAndOptionalProperties) {
     // Get the content object from the operation
@@ -131,3 +131,3 @@ const originalContent = operation.information?.requestBody?.content;
                 mode: 'write',
-                omitEmptyAndOptionalProperties: true,
+                omitEmptyAndOptionalProperties: omitEmptyAndOptionalProperties,
             })
@@ -150,3 +150,2 @@ : null;
                 mode: 'write',
-                omitEmptyAndOptionalProperties: true,
             })
@@ -178,3 +177,2 @@ : null;
                 mode: 'write',
-                omitEmptyAndOptionalProperties: true,
             })
@@ -197,3 +195,2 @@ : null;
                 mode: 'write',
-                omitEmptyAndOptionalProperties: true,
             })
@@ -200,0 +197,0 @@ : null;

dist/spec-getters/getRequestFromOperation.d.ts

@@ -9,3 +9,3 @@ import type { HarRequestWithPath, TransformedOperation } from '@scalar/types/legacy';
     requiredOnly?: boolean;
-}, selectedExampleKey?: string | number) => Partial<HarRequestWithPath>;
+}, selectedExampleKey?: string | number, omitEmptyAndOptionalProperties?: boolean) => Partial<HarRequestWithPath>;
 //# sourceMappingURL=getRequestFromOperation.d.ts.map

dist/spec-getters/getRequestFromOperation.js

@@ -5,3 +5,3 @@ import { getParametersFromOperation } from './getParametersFromOperation.js';
 
-const getRequestFromOperation = (operation, options, selectedExampleKey) => {
+const getRequestFromOperation = (operation, options, selectedExampleKey, omitEmptyAndOptionalProperties) => {
     // Replace all variables of the format {something} with the uppercase variable name without the brackets
@@ -35,3 +35,3 @@ let path = operation.path;
     }
-    const requestBody = getRequestBodyFromOperation(operation, selectedExampleKey);
+    const requestBody = getRequestBodyFromOperation(operation, selectedExampleKey, omitEmptyAndOptionalProperties);
     return {
@@ -38,0 +38,0 @@ method: operation.httpVerb.toUpperCase(),

dist/transforms/export-spec.d.ts

@@ -1,74 +0,17 @@
-import { type Collection, type Request } from '../entities/spec/index.js';
-export declare function exportSpecFromWorkspace({ collection, requests, }: {
+import { type Collection, type Request, type RequestExample, type SecurityScheme, type Tag } from '../entities/spec/index.js';
+import type { OpenAPIV3_1 } from '@scalar/types';
+type WithRequired<T, K extends keyof T> = T & {
+    [P in K]-?: T[P];
+};
+/**
+ * Convert a workspace collection into an OpenAPI document
+ */
+export declare function exportSpecFromWorkspace({ collection, requests, requestExamples, tags, securitySchemes, }: {
     collection: Collection;
     requests: Record<string, Request>;
-}): {
-    type: "collection";
-    uid: string;
-    children: string[];
-    openapi: string;
-    security: Record<string, string[]>[];
-    'x-scalar-icon': string;
-    securitySchemes: string[];
-    selectedSecuritySchemeUids: string[];
-    selectedServerUid: string;
-    servers: string[];
-    requests: string[];
-    tags: string[];
-    auth: Record<string, {
-        type: "apiKey";
-        value: string;
-        name: string;
-    } | {
-        type: "http";
-        username: string;
-        password: string;
-        token: string;
-    } | {
-        type: "oauth-implicit";
-        token: string;
-    } | {
-        type: "oauth-password";
-        username: string;
-        password: string;
-        token: string;
-        clientSecret: string;
-    } | {
-        type: "oauth-clientCredentials";
-        token: string;
-        clientSecret: string;
-    } | {
-        type: "oauth-authorizationCode";
-        token: string;
-        clientSecret: string;
-    }>;
-    watchMode: boolean;
-    watchModeStatus: "IDLE" | "WATCHING" | "ERROR";
-    externalDocs?: {
-        url: string;
-        description?: string | undefined;
-    } | undefined;
-    jsonSchemaDialect?: string | undefined;
-    info?: {
-        title: string;
-        version: string;
-        description?: string | undefined;
-        summary?: string | undefined;
-        termsOfService?: string | undefined;
-        contact?: {
-            name?: string | undefined;
-            url?: string | undefined;
-            email?: string | undefined;
-        } | undefined;
-        license?: {
-            name: string;
-            identifier?: string | undefined;
-            url?: string | undefined;
-        } | undefined;
-    } | undefined;
-    components?: Record<string, unknown> | undefined;
-    webhooks?: Record<string, unknown> | undefined;
-    documentUrl?: string | undefined;
-    integration?: string | null | undefined;
-};
+    requestExamples: Record<string, RequestExample>;
+    tags: Record<string, Tag>;
+    securitySchemes: Record<string, SecurityScheme>;
+}): WithRequired<OpenAPIV3_1.Document<{}>, "paths" | "components" | "tags">;
+export {};
 //# sourceMappingURL=export-spec.d.ts.map

dist/transforms/import-spec.js

@@ -119,3 +119,3 @@ import { securitySchemeSchema, authExampleFromSchema } from '../entities/spec/security.js';
     // Grab the base server URL for relative servers
-    const backupBaseServerUrl = typeof window !== 'undefined' ? window.location.origin : 'http://localhost';
+    const backupBaseServerUrl = typeof window === 'undefined' ? 'http://localhost' : window.location.origin;
     const _baseServerUrl = baseServerURL ?? backupBaseServerUrl;
@@ -122,0 +122,0 @@ // Add the base server url to any relative servers

dist/transforms/index.d.ts

 export * from './import-spec.js';
+export * from './export-spec.js';
 //# sourceMappingURL=index.d.ts.map

dist/transforms/index.js

 export { getBaseAuthValues, importSpecToWorkspace, parseSchema } from './import-spec.js';
+export { exportSpecFromWorkspace } from './export-spec.js';

package.json

@@ -19,3 +19,3 @@ {
   ],
-  "version": "0.2.75",
+  "version": "0.2.76",
   "engines": {
@@ -110,5 +110,5 @@ "node": ">=18"
     "zod": "^3.23.8",
-    "@scalar/object-utils": "1.1.12",
     "@scalar/openapi-types": "0.1.5",
     "@scalar/themes": "0.9.48",
+    "@scalar/object-utils": "1.1.12",
     "@scalar/types": "0.0.19"
@@ -121,5 +121,5 @@ },
     "zod-to-ts": "^1.2.0",
+    "@scalar/build-tooling": "0.1.12",
     "@scalar/openapi-types": "0.1.5",
-    "@scalar/openapi-parser": "0.8.9",
-    "@scalar/build-tooling": "0.1.12"
+    "@scalar/openapi-parser": "0.8.9"
   },
@@ -126,0 +126,0 @@ "scripts": {

No alert changes

Improved metrics

Total package byte prevSize

429796

increased by11.2%

Number of package files

204

increased by3.55%

Lines of code

9032

increased by11.98%

No dependency changes