OpenAPI 3.1 Types

/**
 * Root OpenAPI 3.1 document object with webhook support
 */
interface OpenAPIObject extends ISpecificationExtension {
  openapi: string;
  info: InfoObject;
  servers?: ServerObject[];
  paths?: PathsObject; // Optional in OpenAPI 3.1
  components?: ComponentsObject;
  security?: SecurityRequirementObject[];
  tags?: TagObject[];
  externalDocs?: ExternalDocumentationObject;
  webhooks?: PathsObject; // New in OpenAPI 3.1
}

/**
 * API metadata information (same as 3.0)
 */
interface InfoObject extends ISpecificationExtension {
  title: string;
  description?: string;
  termsOfService?: string;
  contact?: ContactObject;
  license?: LicenseObject;
  version: string;
}

/**
 * Contact information for the API (same as 3.0)
 */
interface ContactObject extends ISpecificationExtension {
  name?: string;
  url?: string;
  email?: string;
}

/**
 * License information with optional identifier (enhanced in 3.1)
 */
interface LicenseObject extends ISpecificationExtension {
  name: string;
  identifier?: string; // New in OpenAPI 3.1
  url?: string;
}

/**
 * Container for reusable components with pathItems support
 */
interface ComponentsObject extends ISpecificationExtension {
  schemas?: { [schema: string]: SchemaObject | ReferenceObject };
  responses?: { [response: string]: ResponseObject | ReferenceObject };
  parameters?: { [parameter: string]: ParameterObject | ReferenceObject };
  examples?: { [example: string]: ExampleObject | ReferenceObject };
  requestBodies?: { [request: string]: RequestBodyObject | ReferenceObject };
  headers?: { [header: string]: HeaderObject | ReferenceObject };
  securitySchemes?: { [securityScheme: string]: SecuritySchemeObject | ReferenceObject };
  links?: { [link: string]: LinkObject | ReferenceObject };
  callbacks?: { [callback: string]: CallbackObject | ReferenceObject };
  pathItems?: { [pathItem: string]: PathItemObject | ReferenceObject }; // New in OpenAPI 3.1
}

/**
 * Container for API paths (optional in OpenAPI 3.1)
 */
interface PathsObject extends ISpecificationExtension {
  [path: string]: PathItemObject;
}

/**
 * @deprecated Use PathsObject instead
 */
type PathObject = PathsObject;

/**
 * Single path item with HTTP operations (same as 3.0)
 */
interface PathItemObject extends ISpecificationExtension {
  $ref?: string;
  summary?: string;
  description?: string;
  get?: OperationObject;
  put?: OperationObject;
  post?: OperationObject;
  delete?: OperationObject;
  options?: OperationObject;
  head?: OperationObject;
  patch?: OperationObject;
  trace?: OperationObject;
  servers?: ServerObject[];
  parameters?: (ParameterObject | ReferenceObject)[];
}

/**
 * HTTP operation definition with optional responses
 */
interface OperationObject extends ISpecificationExtension {
  tags?: string[];
  summary?: string;
  description?: string;
  externalDocs?: ExternalDocumentationObject;
  operationId?: string;
  parameters?: (ParameterObject | ReferenceObject)[];
  requestBody?: RequestBodyObject | ReferenceObject;
  responses?: ResponsesObject; // Optional in OpenAPI 3.1
  callbacks?: CallbacksObject;
  deprecated?: boolean;
  security?: SecurityRequirementObject[];
  servers?: ServerObject[];
}

/**
 * External documentation reference (same as 3.0)
 */
interface ExternalDocumentationObject extends ISpecificationExtension {
  description?: string;
  url: string;
}

/**
 * Parameter location type
 */
type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';

/**
 * Parameter serialization style
 */
type ParameterStyle =
  | 'matrix'
  | 'label'
  | 'form'
  | 'simple'
  | 'spaceDelimited'
  | 'pipeDelimited'
  | 'deepObject';

/**
 * Base parameter properties (same as 3.0)
 */
interface BaseParameterObject extends ISpecificationExtension {
  description?: string;
  required?: boolean;
  deprecated?: boolean;
  allowEmptyValue?: boolean;
  style?: ParameterStyle;
  explode?: boolean;
  allowReserved?: boolean;
  schema?: SchemaObject | ReferenceObject;
  examples?: { [param: string]: ExampleObject | ReferenceObject };
  example?: any;
  content?: ContentObject;
}

/**
 * Complete parameter definition (same as 3.0)
 */
interface ParameterObject extends BaseParameterObject {
  name: string;
  in: ParameterLocation;
}

/**
 * Request body definition (same as 3.0)
 */
interface RequestBodyObject extends ISpecificationExtension {
  description?: string;
  content: ContentObject;
  required?: boolean;
}

/**
 * Content type mappings (same as 3.0)
 */
interface ContentObject {
  [mediatype: string]: MediaTypeObject;
}

/**
 * Media type definition (same as 3.0)
 */
interface MediaTypeObject extends ISpecificationExtension {
  schema?: SchemaObject | ReferenceObject;
  examples?: ExamplesObject;
  example?: any;
  encoding?: EncodingObject;
}

/**
 * Response definitions container (same as 3.0)
 */
interface ResponsesObject extends ISpecificationExtension {
  default?: ResponseObject | ReferenceObject;
  [statuscode: string]: ResponseObject | ReferenceObject | any;
}

/**
 * HTTP response definition (same as 3.0)
 */
interface ResponseObject extends ISpecificationExtension {
  description: string;
  headers?: HeadersObject;
  content?: ContentObject;
  links?: LinksObject;
}

/**
 * Headers container (same as 3.0)
 */
interface HeadersObject {
  [name: string]: HeaderObject | ReferenceObject;
}

/**
 * Header definition (same as 3.0)
 */
interface HeaderObject extends BaseParameterObject {
  $ref?: string;
}

/**
 * JSON Schema types (same as 3.0)
 */
type SchemaObjectType =
  | 'integer'
  | 'number'
  | 'string'
  | 'boolean'
  | 'object'
  | 'null'
  | 'array';

/**
 * Enhanced JSON Schema definition for OpenAPI 3.1
 */
interface SchemaObject extends ISpecificationExtension {
  $ref?: string; // Reference support in schemas
  discriminator?: DiscriminatorObject;
  readOnly?: boolean;
  writeOnly?: boolean;
  xml?: XmlObject;
  externalDocs?: ExternalDocumentationObject;
  example?: any; // @deprecated use examples instead
  examples?: any[];
  deprecated?: boolean;
  
  type?: SchemaObjectType | SchemaObjectType[];
  format?:
    | 'int32'
    | 'int64'
    | 'float'
    | 'double'
    | 'byte'
    | 'binary'
    | 'date'
    | 'date-time'
    | 'password'
    | string;
  allOf?: (SchemaObject | ReferenceObject)[];
  oneOf?: (SchemaObject | ReferenceObject)[];
  anyOf?: (SchemaObject | ReferenceObject)[];
  not?: SchemaObject | ReferenceObject;
  items?: SchemaObject | ReferenceObject;
  properties?: { [propertyName: string]: SchemaObject | ReferenceObject };
  additionalProperties?: SchemaObject | ReferenceObject | boolean;
  propertyNames?: SchemaObject | ReferenceObject; // New in OpenAPI 3.1
  description?: string;
  default?: any;
  
  title?: string;
  multipleOf?: number;
  maximum?: number;
  const?: any; // New in OpenAPI 3.1
  exclusiveMaximum?: number; // Changed to number in OpenAPI 3.1
  minimum?: number;
  exclusiveMinimum?: number; // Changed to number in OpenAPI 3.1
  maxLength?: number;
  minLength?: number;
  pattern?: string;
  maxItems?: number;
  minItems?: number;
  uniqueItems?: boolean;
  maxProperties?: number;
  minProperties?: number;
  required?: string[];
  enum?: any[];
  prefixItems?: (SchemaObject | ReferenceObject)[]; // New in OpenAPI 3.1
  contentMediaType?: string; // New in OpenAPI 3.1
  contentEncoding?: string; // New in OpenAPI 3.1
}

/**
 * Schemas container (same as 3.0)
 */
interface SchemasObject {
  [schema: string]: SchemaObject;
}

/**
 * Polymorphism discriminator (same as 3.0)
 */
interface DiscriminatorObject {
  propertyName: string;
  mapping?: { [key: string]: string };
}

/**
 * XML serialization metadata (same as 3.0)
 */
interface XmlObject extends ISpecificationExtension {
  name?: string;
  namespace?: string;
  prefix?: string;
  attribute?: boolean;
  wrapped?: boolean;
}

/**
 * Enhanced reference object with summary and description
 */
interface ReferenceObject {
  $ref: string;
  summary?: string; // New in OpenAPI 3.1
  description?: string; // New in OpenAPI 3.1
}

/**
 * Security scheme types (same as 3.0)
 */
type SecuritySchemeType = 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';

/**
 * Security scheme definition (same as 3.0)
 */
interface SecuritySchemeObject extends ISpecificationExtension {
  type: SecuritySchemeType;
  description?: string;
  name?: string; // required only for apiKey
  in?: string; // required only for apiKey
  scheme?: string; // required only for http
  bearerFormat?: string;
  flows?: OAuthFlowsObject; // required only for oauth2
  openIdConnectUrl?: string; // required only for openIdConnect
}

/**
 * OAuth flows container (same as 3.0)
 */
interface OAuthFlowsObject extends ISpecificationExtension {
  implicit?: OAuthFlowObject;
  password?: OAuthFlowObject;
  clientCredentials?: OAuthFlowObject;
  authorizationCode?: OAuthFlowObject;
}

/**
 * OAuth flow definition (same as 3.0)
 */
interface OAuthFlowObject extends ISpecificationExtension {
  authorizationUrl?: string;
  tokenUrl?: string;
  refreshUrl?: string;
  scopes: ScopesObject;
}

/**
 * OAuth scopes definition (same as 3.0)
 */
interface ScopesObject extends ISpecificationExtension {
  [scope: string]: any;
}

/**
 * Security requirement (same as 3.0)
 */
interface SecurityRequirementObject {
  [name: string]: string[];
}

/**
 * Links container (same as 3.0)
 */
interface LinksObject {
  [name: string]: LinkObject | ReferenceObject;
}

/**
 * Link definition (same as 3.0)
 */
interface LinkObject extends ISpecificationExtension {
  operationRef?: string;
  operationId?: string;
  parameters?: LinkParametersObject;
  requestBody?: any | string;
  description?: string;
  server?: ServerObject;
  [property: string]: any;
}

/**
 * Link parameters mapping (same as 3.0)
 */
interface LinkParametersObject {
  [name: string]: any | string;
}

/**
 * Callbacks container (same as 3.0)
 */
interface CallbacksObject extends ISpecificationExtension {
  [name: string]: CallbackObject | ReferenceObject | any;
}

/**
 * Callback definition (same as 3.0)
 */
interface CallbackObject extends ISpecificationExtension {
  [name: string]: PathItemObject | any;
}

/**
 * Examples container (same as 3.0)
 */
interface ExamplesObject {
  [name: string]: ExampleObject | ReferenceObject;
}

/**
 * Example value definition (same as 3.0)
 */
interface ExampleObject {
  summary?: string;
  description?: string;
  value?: any;
  externalValue?: string;
  [property: string]: any;
}

/**
 * Encoding definitions container (same as 3.0)
 */
interface EncodingObject extends ISpecificationExtension {
  [property: string]: EncodingPropertyObject | any;
}

/**
 * Individual encoding property (same as 3.0)
 */
interface EncodingPropertyObject {
  contentType?: string;
  headers?: { [key: string]: HeaderObject | ReferenceObject };
  style?: string;
  explode?: boolean;
  allowReserved?: boolean;
  [key: string]: any;
}

/**
 * Tag metadata (same as 3.0)
 */
interface TagObject extends ISpecificationExtension {
  name: string;
  description?: string;
  externalDocs?: ExternalDocumentationObject;
  [extension: string]: any;
}

/**
 * Parameter location options
 * @deprecated - Use ParameterLocation type instead
 */
type PathObject = PathsObject;

/**
 * The location of a parameter
 * Possible values are "query", "header", "path" or "cookie"
 */
type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';

/**
 * The style of a parameter
 * Describes how the parameter value will be serialized
 */
type ParameterStyle =
    | 'matrix'
    | 'label'
    | 'form'
    | 'simple'
    | 'spaceDelimited'
    | 'pipeDelimited'
    | 'deepObject';

/**
 * Valid schema types in OpenAPI 3.1
 */
type SchemaObjectType =
    | 'integer'
    | 'number'
    | 'string'
    | 'boolean'
    | 'object'
    | 'null'
    | 'array';

/**
 * Valid security scheme types in OpenAPI 3.1
 */
type SecuritySchemeType = 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';

/**
 * Extract path item from paths object, handling optional paths
 * @param pathsObject - Paths container object (can be undefined in 3.1)
 * @param path - Path string to retrieve
 * @returns PathItemObject if found, undefined otherwise
 */
function getPath(
  pathsObject: PathsObject | undefined,
  path: string
): PathItemObject | undefined;

/**
 * Type guard to check if object is a ReferenceObject
 * @param obj - Object to check
 * @returns True if object is a ReferenceObject
 */
function isReferenceObject(obj: any): obj is ReferenceObject;

/**
 * Type guard to check if schema is a SchemaObject (not a ReferenceObject)
 * @param schema - Schema to check
 * @returns True if schema is a SchemaObject
 */
function isSchemaObject(schema: SchemaObject | ReferenceObject): schema is SchemaObject;

import { oas31 } from "openapi3-ts";
import { getPath, isReferenceObject, isSchemaObject } from "openapi3-ts/oas31";

// JSON Schema Draft 2020-12 features
const enhancedUserSchema: oas31.SchemaObject = {
  type: "object",
  required: ["id", "name"],
  properties: {
    id: { 
      type: "integer",
      minimum: 1,
      exclusiveMinimum: 0 // Numeric in 3.1 (vs boolean in 3.0)
    },
    name: { type: "string" },
    role: {
      const: "user" // Constant value constraint
    },
    preferences: {
      type: "array",
      prefixItems: [ // Tuple validation
        { type: "string" }, // First item must be string
        { type: "boolean" } // Second item must be boolean
      ],
      items: false // No additional items allowed
    },
    metadata: {
      type: "string",
      contentMediaType: "application/json", // Content type hint
      contentEncoding: "base64" // Encoding hint
    }
  },
  propertyNames: { // Property name validation
    pattern: "^[a-zA-Z_][a-zA-Z0-9_]*$"
  }
};

// Enhanced reference with summary and description
const userReference: oas31.ReferenceObject = {
  $ref: "#/components/schemas/User",
  summary: "User model reference",
  description: "Standard user object with all required fields"
};

// License with identifier
const mitLicense: oas31.LicenseObject = {
  name: "MIT",
  identifier: "MIT", // SPDX license identifier
  url: "https://opensource.org/licenses/MIT"
};

const openApiDoc: oas31.OpenAPIObject = {
  openapi: "3.1.0",
  info: {
    title: "Enhanced API",
    version: "1.0.0"
  },
  paths: {
    "/users": {
      get: {
        responses: {
          "200": {
            description: "Success"
          }
        }
      }
    }
  },
  webhooks: {
    userCreated: {
      post: {
        summary: "User created webhook",
        requestBody: {
          content: {
            "application/json": {
              schema: { $ref: "#/components/schemas/User" }
            }
          }
        },
        responses: {
          "200": {
            description: "Webhook processed"
          }
        }
      }
    }
  },
  components: {
    schemas: {
      User: enhancedUserSchema
    }
  }
};