Http Cache schema — API Protocol reference

HTTP Metadata Cache Protocol — Implements efficient HTTP-level metadata caching with ETag support.

HTTP Metadata Cache Protocol

Implements efficient HTTP-level metadata caching with ETag support. Implements P0 requirement for ObjectStack kernel.

Caching in ObjectStack

HTTP Cache (api/http-cache.zod.ts) - This File

Purpose: Cache API responses at HTTP protocol level
Technologies: HTTP headers (ETag, Last-Modified, Cache-Control), CDN
Configuration: Cache-Control headers, validation tokens
Use case: Reduce API response time for repeated metadata requests
Scope: HTTP layer, client-server communication

Application Cache (system/cache.zod.ts)

Purpose: Cache computed data, query results, aggregations
Technologies: Redis, Memcached, in-memory LRU
Configuration: TTL, eviction policies, cache warming
Use case: Cache expensive database queries, computed values
Scope: Application layer, server-side data storage

Features

ETag-based conditional requests (HTTP 304 Not Modified)
Cache-Control directives
Metadata versioning
Selective cache invalidation

Industry alignment: HTTP Caching (RFC 7234), Salesforce Metadata API

See also: ../../system/cache.zod.ts for application-level caching

Source: packages/spec/src/api/http-cache.zod.ts

TypeScript Usage

import { CacheControlSchema, CacheDirective, CacheInvalidationRequestSchema, CacheInvalidationResponseSchema, CacheInvalidationTarget, ETagSchema, MetadataCacheRequestSchema, MetadataCacheResponseSchema } from '@objectstack/spec/api';
import type { CacheControl, CacheDirective, CacheInvalidationRequest, CacheInvalidationResponse, CacheInvalidationTarget, ETag, MetadataCacheRequest, MetadataCacheResponse } from '@objectstack/spec/api';

// Validate data
const result = CacheControlSchema.parse(data);

CacheControl

Properties

Property	Type	Required	Description
directives	`Enum<'public' \| 'private' \| 'no-cache' \| 'no-store' \| 'must-revalidate' \| 'max-age'>[]`	✅	Cache control directives
maxAge	`number`	optional	Maximum cache age in seconds (unit per HTTP Cache-Control `max-age` (RFC 9111 §5.2.2.1))
staleWhileRevalidate	`number`	optional	Allow serving stale content while revalidating (seconds) (unit per HTTP Cache-Control `stale-while-revalidate` (RFC 5861 §3))
staleIfError	`number`	optional	Allow serving stale content on error (seconds) (unit per HTTP Cache-Control `stale-if-error` (RFC 5861 §4))

CacheDirective

Allowed Values

public
private
no-cache
no-store
must-revalidate
max-age

CacheInvalidationRequest

Properties

Property	Type	Required	Description
target	`Enum<'all' \| 'object' \| 'field' \| 'permission' \| 'layout' \| 'custom'>`	✅	What to invalidate
identifiers	`string[]`	optional	Specific resources to invalidate (e.g., object names)
cascade	`boolean`	optional (default: `false`)	If true, invalidate dependent resources
pattern	`string`	optional	Pattern for custom invalidation (supports wildcards)

CacheInvalidationResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅	Whether invalidation succeeded
invalidated	`number`	✅	Number of cache entries invalidated
targets	`string[]`	optional	List of invalidated resources

CacheInvalidationTarget

Allowed Values

all
object
field
permission
layout
custom

ETag

Properties

Property	Type	Required	Description
value	`string`	✅	ETag value (hash or version identifier)
weak	`boolean`	optional (default: `false`)	Whether this is a weak ETag

MetadataCacheRequest

Properties

Property	Type	Required	Description
ifNoneMatch	`string`	optional	ETag value for conditional request (If-None-Match header)
ifModifiedSince	`string`	optional	Timestamp for conditional request (If-Modified-Since header)
cacheControl	`{ directives: Enum<'public' \| 'private' \| 'no-cache' \| 'no-store' \| 'must-revalidate' \| 'max-age'>[]; maxAge?: number; staleWhileRevalidate?: number; staleIfError?: number }`	optional	Client cache control preferences

Nested Shape: `MetadataCacheRequest.cacheControl`

Property	Type	Required	Description
directives	`Enum<'public' \| 'private' \| 'no-cache' \| 'no-store' \| 'must-revalidate' \| 'max-age'>[]`	✅	Cache control directives
maxAge	`number`	optional	Maximum cache age in seconds (unit per HTTP Cache-Control `max-age` (RFC 9111 §5.2.2.1))
staleWhileRevalidate	`number`	optional	Allow serving stale content while revalidating (seconds) (unit per HTTP Cache-Control `stale-while-revalidate` (RFC 5861 §3))
staleIfError	`number`	optional	Allow serving stale content on error (seconds) (unit per HTTP Cache-Control `stale-if-error` (RFC 5861 §4))

MetadataCacheResponse

Properties

Property	Type	Required	Description
data	`any`	optional	Metadata payload (omitted for 304 Not Modified)
etag	`{ value: string; weak?: boolean }`	optional	ETag for this resource version
lastModified	`string`	optional	Last modification timestamp
cacheControl	`{ directives: Enum<'public' \| 'private' \| 'no-cache' \| 'no-store' \| 'must-revalidate' \| 'max-age'>[]; maxAge?: number; staleWhileRevalidate?: number; staleIfError?: number }`	optional	Cache control directives
notModified	`boolean`	optional (default: `false`)	True if resource has not been modified (304 response)
version	`string`	optional	Metadata version identifier

Nested Shape: `MetadataCacheResponse.etag`

Property	Type	Required	Description
value	`string`	✅	ETag value (hash or version identifier)
weak	`boolean`	optional (default: `false`)	Whether this is a weak ETag

Nested Shape: `MetadataCacheResponse.cacheControl`

Property	Type	Required	Description
directives	`Enum<'public' \| 'private' \| 'no-cache' \| 'no-store' \| 'must-revalidate' \| 'max-age'>[]`	✅	Cache control directives
maxAge	`number`	optional	Maximum cache age in seconds (unit per HTTP Cache-Control `max-age` (RFC 9111 §5.2.2.1))
staleWhileRevalidate	`number`	optional	Allow serving stale content while revalidating (seconds) (unit per HTTP Cache-Control `stale-while-revalidate` (RFC 5861 §3))
staleIfError	`number`	optional	Allow serving stale content on error (seconds) (unit per HTTP Cache-Control `stale-if-error` (RFC 5861 §4))

Http Cache schema — API Protocol reference

On this page