Discovery

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, WellKnownCapabilities } from '@objectstack/spec/api';
import type { ApiRoutes, Discovery, RouteHealthEntry, RouteHealthReport, ServiceInfo, 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
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
feed	`string`	optional	e.g. /api/v1/feed

Properties

Property	Type	Required	Description
name	`string`	✅
version	`string`	✅
environment	`Enum<'production' \| 'sandbox' \| 'development'>`	✅
routes	`Object`	✅
locale	`Object`	✅
services	`Record<string, Object>`	✅	Per-service availability map keyed by CoreServiceName
capabilities	`Record<string, Object>`	optional	Hierarchical capability descriptors for frontend intelligent adaptation
schemaDiscovery	`Object`	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	`Object[]`	✅	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	`Object`	optional	Rate limit and quota info for this service

WellKnownCapabilities

Well-known capability flags for frontend intelligent adaptation

Properties

Property	Type	Required	Description
feed	`boolean`	✅	Whether the backend supports Feed / Chatter API
comments	`boolean`	✅	Whether the backend supports comments (a subset of Feed)
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

Discovery

On this page