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 { ApiRoutesSchema, CapabilityDescriptorSchema, DiscoverySchema, DiscoveryEnvironmentSchema, RouteHealthEntrySchema, RouteHealthReportSchema, ServiceInfoSchema, ServiceSelfInfoSchema, ServiceStatus, WellKnownCapabilitiesSchema } from '@objectstack/spec/api';
import type { ApiRoutes, CapabilityDescriptor, DiscoveryEnvironment, RouteHealthEntry, RouteHealthReport, ServiceInfo, ServiceSelfInfo, ServiceStatus, WellKnownCapabilities } from '@objectstack/spec/api';

// Validate data
const result = ApiRoutesSchema.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
packages	`string`	optional	e.g. /api/v1/packages
datasources	`string`	optional	e.g. /api/v1/datasources — base for the datasources/:name/external/* federation-admin family; absent when no host mounts it
email	`string`	optional	e.g. /api/v1/email — base for the email/send endpoint; absent when no host mounts it
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
mcp	`string`	optional	e.g. /api/v1/mcp — always the unscoped base; absent when MCP is disabled or unserveable

CapabilityDescriptor

Properties

Property	Type	Required	Description
enabled	`boolean`	✅	Whether this capability is available
features	`Record<string, boolean>`	optional	Sub-feature flags within this capability
description	`string`	optional	Human-readable capability description

Properties

Property	Type	Required	Description
name	`string`	✅
version	`string`	✅
environment	`Enum<'production' \| 'sandbox' \| 'development'>`	✅	Deployment posture a discovery response advertises. Deliberately three coarse buckets — a client reads this to answer "am I talking to production?", not to identify a specific environment (that is `sys_environment` / EnvironmentTypeSchema, a richer 7-member taxonomy).
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	`{ comments: object; automation: object; cron: object; search: object; … }`	✅	Hierarchical capability descriptors — the full WellKnownCapabilities vocabulary, every key present
schemaDiscovery	`{ openapi?: string; jsonSchema?: string }`	optional	Schema discovery endpoints for API toolchain integration
scoping	`{ enabled: boolean; resolution: Enum<'required' \| 'optional' \| 'auto'>; scoped: boolean; environmentId?: string }`	optional	Environment-scoping posture, added by the REST discovery endpoint
metadata	`Record<string, any>`	optional	Custom metadata key-value pairs for extensibility

Deployment posture a discovery response advertises. Deliberately three coarse buckets — a client reads this to answer "am I talking to production?", not to identify a specific environment (that is sys_environment / EnvironmentTypeSchema, a richer 7-member taxonomy).

Allowed Values

production
sandbox
development

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

ServiceStatus

available = fully operational, registered = route declared but handler unverified, unavailable = not installed, degraded = partial, stub = placeholder that returns 501

Allowed Values

available
registered
unavailable
degraded
stub

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
transactionalBatch	`boolean`	✅	Whether the backend exposes the atomic cross-object batch endpoint (POST `{basePath}`/batch, #1604/ADR-0034): all ops commit or roll back together in one transaction. Lets clients skip non-atomic client-side simulation instead of runtime-probing 404/405/501. True ⟺ the /batch route is mounted AND the runtime can honour a transaction.
websockets	`boolean`	✅	Whether the backend mounts a realtime push surface (WebSocket/SSE) clients can subscribe to. False while realtime is an in-process bus with no mounted HTTP/WS surface (ADR-0076 D12, #2462).
files	`boolean`	✅	Whether a file-storage surface (upload/download/attachments) is served
analytics	`boolean`	✅	Whether the backend serves the analytics / BI query surface
ai	`boolean`	✅	Whether the backend serves the AI surface (NLQ, chat, agents, suggest)
notifications	`boolean`	✅	Whether the backend serves the notification surface (inbox, delivery)
i18n	`boolean`	✅	Whether the backend serves the i18n surface (translations, locale negotiation)

Discovery

On this page