---
title: Http Cache
description: Http Cache protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

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 ../../system/cache.zod.ts for application-level caching

<Callout type="info">
**Source:** `packages/spec/src/api/http-cache.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { CacheControl, CacheDirective, CacheInvalidationRequest, CacheInvalidationResponse, CacheInvalidationTarget, ETag, MetadataCacheRequest, MetadataCacheResponse } from '@objectstack/spec/api';
import type { CacheControl, CacheDirective, CacheInvalidationRequest, CacheInvalidationResponse, CacheInvalidationTarget, ETag, MetadataCacheRequest, MetadataCacheResponse } from '@objectstack/spec/api';

// Validate data
const result = CacheControl.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 |
| **staleWhileRevalidate** | `number` | optional | Allow serving stale content while revalidating (seconds) |
| **staleIfError** | `number` | optional | Allow serving stale content on error (seconds) |


---

## 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` | ✅ | 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` | ✅ | 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** | `Object` | optional | Client cache control preferences |


---

## MetadataCacheResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **data** | `any` | optional | Metadata payload (omitted for 304 Not Modified) |
| **etag** | `Object` | optional | ETag for this resource version |
| **lastModified** | `string` | optional | Last modification timestamp |
| **cacheControl** | `Object` | optional | Cache control directives |
| **notModified** | `boolean` | ✅ | True if resource has not been modified (304 response) |
| **version** | `string` | optional | Metadata version identifier |


---

