discovery.mdx

title	Discovery
description	Discovery protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Service Status Enum

Describes the operational state of a service in the discovery response.

• available – Fully operational: service is registered AND HTTP handler is verified.

• registered – Route is declared in the dispatcher table but the HTTP handler has

not been verified (may 501 at runtime).

• unavailable – Service is not installed / not registered in the kernel.

• degraded – Partially working (e.g., in-memory fallback, missing persistence).

• stub – Placeholder handler that always returns 501 Not Implemented.

**Source:** `packages/spec/src/api/discovery.zod.ts`

TypeScript Usage

import { ApiRoutes, Discovery, RouteHealthEntry, RouteHealthReport, ServiceInfo, ServiceSelfInfo, WellKnownCapabilities } from '@objectstack/spec/api';
import type { ApiRoutes, Discovery, RouteHealthEntry, RouteHealthReport, ServiceInfo, ServiceSelfInfo, WellKnownCapabilities } from '@objectstack/spec/api';

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

---

ApiRoutes

Properties

Property	Type	Required	Description
data	string	✅	e.g. /api/v1/data
metadata	string	✅	e.g. /api/v1/meta
discovery	string	optional	e.g. /api/v1/discovery
ui	string	optional	e.g. /api/v1/ui
auth	string	optional	e.g. /api/v1/auth
automation	string	optional	e.g. /api/v1/automation
storage	string	optional	e.g. /api/v1/storage
analytics	string	optional	e.g. /api/v1/analytics
graphql	string	optional	e.g. /graphql
packages	string	optional	e.g. /api/v1/packages
workflow	string	optional	e.g. /api/v1/workflow
approvals	string	optional	e.g. /api/v1/approvals
realtime	string	optional	e.g. /api/v1/realtime
notifications	string	optional	e.g. /api/v1/notifications
ai	string	optional	e.g. /api/v1/ai
i18n	string	optional	e.g. /api/v1/i18n

---

Discovery

Properties

Property	Type	Required	Description
name	string	✅
version	string	✅
environment	Enum<'production' | 'sandbox' | 'development'>	✅
routes	{ data: string; metadata: string; discovery?: string; ui?: string; … }	✅
locale	{ default: string; supported: string[]; timezone: string }	✅
services	Record<string, { enabled: boolean; status: Enum<'available' | 'registered' | 'unavailable' | 'degraded' | 'stub'>; handlerReady?: boolean; route?: string; … }>	✅	Per-service availability map keyed by CoreServiceName
capabilities	Record<string, { enabled: boolean; features?: Record<string, boolean>; description?: string }>	optional	Hierarchical capability descriptors for frontend intelligent adaptation
schemaDiscovery	{ openapi?: string; graphql?: string; jsonSchema?: string }	optional	Schema discovery endpoints for API toolchain integration
metadata	Record<string, any>	optional	Custom metadata key-value pairs for extensibility

---

RouteHealthEntry

Properties

Property	Type	Required	Description
route	string	✅	Route path pattern
method	Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>	✅	HTTP method (GET, POST, etc.)
service	string	✅	Target service name
declared	boolean	✅	Whether the route is declared in discovery/metadata
handlerRegistered	boolean	✅	Whether the HTTP handler is registered
healthStatus	Enum<'pass' | 'fail' | 'missing' | 'skip'>	✅	pass = handler responds, fail = 501/503, missing = no handler (404), skip = not checked
message	string	optional	Diagnostic message

---

RouteHealthReport

Properties

Property	Type	Required	Description
timestamp	string	✅	ISO 8601 timestamp of report generation
adapter	string	✅	Adapter or runtime that produced this report
totalDeclared	integer	✅	Total routes declared in discovery
totalRegistered	integer	✅	Routes with confirmed handler
totalMissing	integer	✅	Routes missing a handler
routes	{ route: string; method: Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>; service: string; declared: boolean; … }[]	✅	Per-route health entries

---

ServiceInfo

Properties

Property	Type	Required	Description
enabled	boolean	✅
status	Enum<'available' | 'registered' | 'unavailable' | 'degraded' | 'stub'>	✅	available = fully operational, registered = route declared but handler unverified, unavailable = not installed, degraded = partial, stub = placeholder that returns 501
handlerReady	boolean	optional	Whether the HTTP handler is confirmed to be mounted. Omitted = readiness unknown/unverified; true = handler mounted; false = handler missing or stub (likely 501).
route	string	optional	e.g. /api/v1/analytics
provider	string	optional	e.g. "objectql", "plugin-redis", "driver-memory"
version	string	optional	Semantic version of the service implementation (e.g. "3.0.6")
message	string	optional	e.g. "Install plugin-workflow to enable"
rateLimit	{ requestsPerMinute?: integer; requestsPerHour?: integer; burstLimit?: integer; retryAfterMs?: integer }	optional	Rate limit and quota info for this service

---

ServiceSelfInfo

Properties

Property	Type	Required	Description
status	Enum<'stub' | 'degraded'>	✅	stub = placeholder or dev fake (do not use for real work); degraded = functional fallback with reduced capability
handlerReady	boolean	optional	Whether the HTTP handler genuinely serves requests. Defaults: false for stub, true for degraded.
message	string	optional	Human-readable explanation, e.g. what to install for the full implementation

---

WellKnownCapabilities

Well-known capability flags for frontend intelligent adaptation

Properties

Property	Type	Required	Description
comments	boolean	✅	Whether the backend supports record comments / chatter (the sys_comment object served via the data API)
automation	boolean	✅	Whether the backend supports Automation CRUD (flows, triggers)
cron	boolean	✅	Whether the backend supports cron scheduling
search	boolean	✅	Whether the backend supports full-text search
export	boolean	✅	Whether the backend supports async export
chunkedUpload	boolean	✅	Whether the backend supports chunked (multipart) uploads

---