Schemas and references

Use Schema for payload shape and Components to name reusable definitions. Optional properties below describe constraints; they do not apply defaults or validate data.

Schema fields

Family	Fields and accepted shape
Identity	$schema, title, description, format are strings; type is SchemaType or an array
Values	example, const, default accept any value; enum accepts any[]
Flags	nullable, readOnly, writeOnly, deprecated are optional booleans
Numbers	minimum/maximum/multipleOf are numbers; exclusiveMinimum/exclusiveMaximum accept boolean or number
Strings	minLength/maxLength numbers, pattern string
Arrays	items is one Schema/Reference; minItems/maxItems numbers, uniqueItems boolean
Objects	properties maps names to Schema/Reference; required is string[]; minProperties/maxProperties numbers; additionalProperties accepts boolean/Schema/Reference
Composition	allOf/anyOf/oneOf arrays, not one Schema/Reference
Metadata	discriminator, xml and externalDocs

SchemaType includes string, number, integer, boolean, array, object, null. This supports 3.0 and 3.1 notation together (nullable, type arrays, $schema, const, numeric exclusive bounds) and, all optional, the JSON Schema 2020-12 keywords 3.1 schemas use: $id, $anchor, $dynamicAnchor, $comment, $defs, examples, contentMediaType/contentEncoding/contentSchema, prefixItems, contains/minContains/maxContains, unevaluatedItems, patternProperties, propertyNames, dependentRequired, dependentSchemas, unevaluatedProperties and if/then/else. It is still not a complete 2020-12 model: there is no boolean Schema alternative, and a sibling $ref is not declared on Schema, because '$ref' in value is how code tells a Reference from a Schema. OpenAPI.paths stays required, although 3.1 allows a document with only components or webhooks; pass paths: {} for one.

References and components

Reference contains only $ref: string. It neither verifies target existence nor resolves local/remote pointers. IsReference<T> is a distributive conditional type selecting union members assignable to { $ref: string }; it is not a runtime type guard.

Components holds optional named maps of schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links, callbacks and pathItems (3.1). Each map value also accepts Reference. ComponentTypeMap maps those same keys to the corresponding non-reference object type for generic code.

Discriminator.propertyName is required; mapping is optional string-to-string. All XML properties are optional: name, namespace, prefix, attribute, wrapped. They do not change serialization themselves.

Complete type example

import type {
  Components,
  Reference,
  IsReference,
  Schema,
} from '@ahoo-wang/fetcher-openapi';
const item: Schema = {
  type: 'object',
  required: ['id'],
  additionalProperties: false,
  properties: { id: { type: 'string' }, note: { type: ['string', 'null'] } },
};
const components: Components = { schemas: { Item: item } };
const ref: IsReference<Schema | Reference> = {
  $ref: '#/components/schemas/Item',
};
console.log(components.schemas?.Item, ref.$ref);

SchemaType

packages/openapi/src/base-types.ts:44

export type SchemaType =
  'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';

Discriminator

packages/openapi/src/schema.ts:28

export interface Discriminator extends Extensible {
  propertyName: string;
  mapping?: Record<string, string>;
}

XML

packages/openapi/src/schema.ts:42

export interface XML extends Extensible {
  name?: string;
  namespace?: string;
  prefix?: string;
  attribute?: boolean;
  wrapped?: boolean;
}

Schema

packages/openapi/src/schema.ts:91

export interface Schema extends Extensible {
  $schema?: string;
  // General properties
  title?: string;
  description?: string;
  type?: SchemaType | SchemaType[];
  format?: string;
  nullable?: boolean;
  readOnly?: boolean;
  writeOnly?: boolean;
  deprecated?: boolean;
  example?: any;
  const?: any;
  default?: any;

  // Numeric constraints
  minimum?: number;
  maximum?: number;
  exclusiveMinimum?: boolean | number;
  exclusiveMaximum?: boolean | number;
  multipleOf?: number;

  // String constraints
  minLength?: number;
  maxLength?: number;
  pattern?: string;

  // Array constraints
  items?: Schema | Reference;
  minItems?: number;
  maxItems?: number;
  uniqueItems?: boolean;

  // Object constraints
  properties?: Record<string, Schema | Reference>;
  required?: string[];
  minProperties?: number;
  maxProperties?: number;
  additionalProperties?: boolean | Schema | Reference;

  // Composition
  allOf?: Array<Schema | Reference>;
  anyOf?: Array<Schema | Reference>;
  oneOf?: Array<Schema | Reference>;
  not?: Schema | Reference;

  // Enumeration
  enum?: any[];

  // Polymorphism support
  discriminator?: Discriminator;

  // XML serialization
  xml?: XML;

  // External documentation
  externalDocs?: ExternalDocumentation;
}

Reference

packages/openapi/src/reference.ts:23

export interface Reference {
  $ref: string;
}

IsReference

packages/openapi/src/reference.ts:30

export type IsReference<T> = T extends { $ref: string } ? T : never;

Components

packages/openapi/src/components.ts:43

export interface Components extends Extensible {
  schemas?: Record<string, Schema | Reference>;
  responses?: Record<string, Response | Reference>;
  parameters?: Record<string, Parameter | Reference>;
  examples?: Record<string, Example | Reference>;
  requestBodies?: Record<string, RequestBody | Reference>;
  headers?: Record<string, Header | Reference>;
  securitySchemes?: Record<string, SecurityScheme | Reference>;
  links?: Record<string, Link | Reference>;
  callbacks?: Record<string, Callback | Reference>;
  pathItems?: Record<string, PathItem | Reference>;
}

ComponentTypeMap

packages/openapi/src/components.ts:60

export type ComponentTypeMap = {
  schemas: Schema;
  responses: Response;
  parameters: Parameter;
  examples: Example;
  requestBodies: RequestBody;
  headers: Header;
  securitySchemes: SecurityScheme;
  links: Link;
  callbacks: Callback;
  pathItems: PathItem;
};