📐 Common schemas

Common schemas provide reusable JSON Schema definitions and OpenAPI parameters for pagination, standard responses, audits, files, and contact data. Address-specific schemas are documented in Address schemas.

Inventory

Export	Request location	Contract
address	N/A	Optional array of string address lines.
postalCode	N/A	Optional string postal code.
prefecture	N/A	Optional string or null prefecture.
city	N/A	Optional string city.
country	N/A	Optional string country.
addressJPSchema	N/A	Optional Japanese address components.
partialPostalCodeQueryParameter	Query	Required partial or full Japanese postal code.
findAddressSchema	Query	Lookup request schema.
arrayOfStringsSchema	N/A	Array whose items must be strings.
paginationQueryParametersSchema	Query	Optional bounded page and limit parameters.
auditSchema	N/A	Audit record with action and actor metadata.
paginationSchema	N/A	Pagination response metadata.
errorSchema	N/A	Standard error response.
successSchema	N/A	Standard success response.
fileSchema	N/A	Uploaded-file metadata.
addressSchema	N/A	Required structured address with US postal-code format.
contactSchema	N/A	Contact details with required email.

Details

address

Definition

An object with no additional properties and one optional address property. When present, address must be an array containing only strings.

View complete source

export const address: SchemaDefinition = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  additionalProperties: false,
  properties: {address: {items: {type: 'string'}, type: 'array'}},
  type: 'object',
};

---

postalCode

Definition

An object with no additional properties and an optional string postalCode. It does not impose a postal-code pattern.

View complete source

export const postalCode: SchemaDefinition = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  additionalProperties: false,
  properties: {postalCode: {type: 'string'}},
  type: 'object',
};

---

prefecture

Definition

An object with no additional properties and an optional prefecture whose value may be a string or null.

View complete source

export const prefecture: SchemaDefinition = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  additionalProperties: false,
  properties: {
    prefecture: {type: ['string', 'null']},
  },
  type: 'object',
};

---

city

Definition

An object with no additional properties and an optional string city.

View complete source

export const city: SchemaDefinition = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  additionalProperties: false,
  properties: {
    city: {type: 'string'},
  },
  type: 'object',
};

---

country

Definition

An object with no additional properties and an optional string country.

View complete source

export const country: SchemaDefinition = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  additionalProperties: false,
  properties: {
    country: {type: 'string'},
  },
  type: 'object',
};

---

addressJPSchema

Definition

A strict object for Japanese address data. city, country, postalCode, prefecture, and street are optional strings; the definition has no required array.

View complete source

export const addressJPSchema: SchemaDefinition = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  additionalProperties: false,
  properties: {
    city: {type: 'string'},
    country: {type: 'string'},
    postalCode: {type: 'string'},
    prefecture: {type: 'string'},
    street: {type: 'string'},
  },
  type: 'object',
};

---

partialPostalCodeQueryParameter

Definition

A required query parameter named postalCode. Its string pattern accepts three digits, an optional hyphen, and zero through four additional digits, so both partial and complete Japanese postal codes are valid.

View complete source

export const partialPostalCodeQueryParameter: OpenAPIParameter = {
  in: 'query',
  name: 'postalCode',
  required: true,
  schema: {
    pattern: '^\\d{3}-?\\d{0,4}$',
    type: 'string',
  },
};

---

findAddressSchema

Definition

A withSchema composition whose parameter list contains only partialPostalCodeQueryParameter. It validates the query contract used by custom address lookup composition.

View complete source

export const findAddressSchema = withSchema({
  parameters: [partialPostalCodeQueryParameter],
});

---

arrayOfStringsSchema

Definition

A Draft 7 array definition whose items must be strings. It has no length or uniqueness constraints.

View complete source

export const arrayOfStringsSchema: SchemaDefinition = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  items: {type: 'string'},
  type: 'array',
};

---

paginationQueryParametersSchema

Definition

Two optional integer query parameters: page ranges from 1 through 1000, and limit ranges from 1 through 50. Domain schemas spread this array into their own OpenAPI parameter lists, including Chat schemas.

View complete source

export const paginationQueryParametersSchema: OpenAPIParameter[] = [
  {
    in: 'query',
    name: 'page',
    required: false,
    schema: {
      maximum: 1000,
      minimum: 1,
      type: 'integer',
    },
  },
  {
    in: 'query',
    name: 'limit',
    required: false,
    schema: {
      maximum: 50,
      minimum: 1,
      type: 'integer',
    },
  },
];

---

auditSchema

Definition

An audit record requiring UUID-formatted id, entity_id, and user_id; string entity_type; an action of create, update, or delete; and date-time created_at. Optional changes accepts arbitrary properties.

View complete source

export const auditSchema = withSchema({
  $schema: 'http://json-schema.org/draft-07/schema#',
  properties: {
    action: {enum: ['create', 'update', 'delete'], type: 'string'},
    changes: {additionalProperties: true, type: 'object'},
    created_at: {format: 'date-time', type: 'string'},
    entity_id: {format: 'uuid', type: 'string'},
    entity_type: {type: 'string'},
    id: {format: 'uuid', type: 'string'},
    user_id: {format: 'uuid', type: 'string'},
  },
  required: ['id', 'entity_type', 'entity_id', 'action', 'user_id', 'created_at'],
  type: 'object',
});

---

paginationSchema

Definition

A pagination metadata object requiring numeric page, limit, total, and total_pages. Page and limit have a minimum of 1; totals have a minimum of 0.

View complete source

export const paginationSchema = withSchema({
  $schema: 'http://json-schema.org/draft-07/schema#',
  properties: {
    limit: {minimum: 1, type: 'number'},
    page: {minimum: 1, type: 'number'},
    total: {minimum: 0, type: 'number'},
    total_pages: {minimum: 0, type: 'number'},
  },
  required: ['page', 'limit', 'total', 'total_pages'],
  type: 'object',
});

---

errorSchema

Definition

An error object requiring string code and message. Optional details is an object that accepts arbitrary properties.

View complete source

export const errorSchema = withSchema({
  $schema: 'http://json-schema.org/draft-07/schema#',
  properties: {
    code: {type: 'string'},
    details: {additionalProperties: true, type: 'object'},
    message: {type: 'string'},
  },
  required: ['code', 'message'],
  type: 'object',
});

---

successSchema

Definition

A success object requiring string message. Optional data is an object that accepts arbitrary properties.

View complete source

export const successSchema = withSchema({
  $schema: 'http://json-schema.org/draft-07/schema#',
  properties: {
    data: {additionalProperties: true, type: 'object'},
    message: {type: 'string'},
  },
  required: ['message'],
  type: 'object',
});

---

fileSchema

Definition

File metadata requiring UUID id, string filename and mime_type, nonnegative numeric size, URI url, and date-time created_at.

View complete source

export const fileSchema = withSchema({
  $schema: 'http://json-schema.org/draft-07/schema#',
  properties: {
    created_at: {format: 'date-time', type: 'string'},
    filename: {type: 'string'},
    id: {format: 'uuid', type: 'string'},
    mime_type: {type: 'string'},
    size: {minimum: 0, type: 'number'},
    url: {format: 'uri', type: 'string'},
  },
  required: ['id', 'filename', 'mime_type', 'size', 'url', 'created_at'],
  type: 'object',
});

---

addressSchema

Definition

A structured address requiring street, city, state, country, and postal_code. Every field is a string; postal_code accepts five US digits with an optional four-digit extension.

View complete source

export const addressSchema = withSchema({
  $schema: 'http://json-schema.org/draft-07/schema#',
  properties: {
    city: {type: 'string'},
    country: {type: 'string'},
    postal_code: {pattern: '^[0-9]{5}(-[0-9]{4})?$', type: 'string'},
    state: {type: 'string'},
    street: {type: 'string'},
  },
  required: ['street', 'city', 'state', 'country', 'postal_code'],
  type: 'object',
});

---

contactSchema

Definition

A contact object requiring a format-validated email. Optional phone is a string, and optional address accepts an object with arbitrary properties.

View complete source

export const contactSchema = withSchema({
  $schema: 'http://json-schema.org/draft-07/schema#',
  properties: {
    address: {additionalProperties: true, type: 'object'},
    email: {format: 'email', type: 'string'},
    phone: {type: 'string'},
  },
  required: ['email'],
  type: 'object',
});

---