ObjectStackMetadata schema — API Protocol reference
Defines the standard API contracts for the @objectstack/metadata package.
Metadata Service Protocol
Defines the standard API contracts for the @objectstack/metadata package. This is the single authority for ALL metadata-related services and APIs across the entire platform, including Hono, Next.js, and NestJS adapters.
Architecture
┌──────────────────────────────────────────────────────────────────┐
│ @objectstack/metadata — API Contracts │
│ │
│ CRUD │ Query/Search │ Bulk Ops │ Overlay │ Watch │
│ Import/Export│ Validation │ Type Reg │ Deps │ │
├──────────────────────────────────────────────────────────────────┤
│ Hono Adapter │ Next.js Adapter │ NestJS Adapter │ CLI │
└──────────────────────────────────────────────────────────────────┘Alignment
- Salesforce: Metadata API (deploy, retrieve, describe)
- ServiceNow: System Dictionary + Metadata API
- Kubernetes: API Server + CRD Registry
Source: packages/spec/src/api/metadata.zod.ts
TypeScript Usage
import { AppDefinitionResponseSchema, ConceptListResponseSchema, MetadataBulkRegisterRequestSchema, MetadataBulkResponseSchema, MetadataBulkUnregisterRequestSchema, MetadataDeleteResponseSchema, MetadataDependenciesResponseSchema, MetadataDependentsResponseSchema, MetadataExistsResponseSchema, MetadataExportRequestSchema, MetadataExportResponseSchema, MetadataImportRequestSchema, MetadataImportResponseSchema, MetadataItemResponseSchema, MetadataListResponseSchema, MetadataNamesResponseSchema, MetadataQueryRequestSchema, MetadataQueryResponseSchema, MetadataRegisterRequestSchema, MetadataTypeInfoResponseSchema, MetadataTypesResponseSchema, MetadataValidateRequestSchema, MetadataValidateResponseSchema, ObjectDefinitionResponseSchema } from '@objectstack/spec/api';
import type { AppDefinitionResponse, ConceptListResponse, MetadataBulkRegisterRequest, MetadataBulkResponse, MetadataBulkUnregisterRequest, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataExistsResponse, MetadataExportResponse, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypeInfoResponse, MetadataTypesResponse, MetadataValidateRequest, MetadataValidateResponse, ObjectDefinitionResponse } from '@objectstack/spec/api';
// Validate data
const result = AppDefinitionResponseSchema.parse(data);AppDefinitionResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { name: string; label: string | Record<string, string>; description?: string | Record<string, string>; icon?: string; … } | ✅ | Full App Configuration |
Nested Shape: AppDefinitionResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: AppDefinitionResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
Nested Shape: AppDefinitionResponse.data
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ | App unique machine name (lowercase snake_case) |
| label | string | Record<string, string> | ✅ | App display label |
| version | never | optional | [REMOVED] App.version was removed in @objectstack/spec 17.0.0 (2026-06 liveness audit — no consumer in framework or objectui). An app is versioned by its owning package: use manifest.version. Delete the key. Run os migrate meta --from 16 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand. |
| description | string | Record<string, string> | optional | App description |
| icon | string | optional | App icon used in the App Launcher |
| branding | { primaryColor?: string; accentColor?: string; logo?: string; favicon?: string } | optional | App-specific branding |
| active | boolean | optional (default: true) | Whether the app is enabled |
| isDefault | boolean | optional (default: false) | Is default app |
| hidden | boolean | optional | Hide from the App Switcher; the shell surfaces hidden apps via the avatar menu instead (navigation only — never an access gate) |
| _unpublished | boolean | optional | Machine-managed publish gate (ADR-0045 §3) — true = unpublished, externally unobservable. Written by AI materialization, cleared by publish-drafts. Never authored. |
| navigation | ({ id: string; label?: string | Record<string, string>; icon?: string; order?: number; … } | { type: 'separator'; id?: string; order?: number } | … +8 more)[] | optional | Full navigation tree for the app sidebar |
| areas | { id: string; label: string | Record<string, string>; icon?: string; description?: string | Record<string, string>; … }[] | optional | Navigation areas for partitioning navigation by business domain |
| contextSelectors | { id: string; label: string | Record<string, string>; icon?: string; optionsSource: object; … }[] | optional | App-level scope dropdowns whose value is injected into nav items as {<id>} template vars |
| homePageId | never | optional | [REMOVED] app.homePageId was removed in @objectstack/spec 17.0.0 (ADR-0049). objectui's console did read it before v17 (resolveLandingRoute), so this key had a consumer — it was retired because the capability is better expressed on the navigation item itself than as an ID cross-reference that silently falls back when it dangles. An app's landing page IS its first navigation item (by order), and the root landing follows isDefault routing. Delete the key; to change where an app opens, reorder navigation so the intended entry is first, and set isDefault on the app that should own the root landing. Run os migrate meta --from 16 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand. |
| requiredPermissions | string[] | optional | Permissions required to access this app |
| objects | never | optional | [REMOVED] App.objects was removed in @objectstack/spec 17.0.0 (2026-06 liveness audit — never read; the spec itself labelled it "config file convenience"). Objects belong to the stack (defineStack({ objects })); an app reaches them through its navigation items. Delete the key. Run os migrate meta --from 16 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand. |
| apis | never | optional | [REMOVED] App.apis was removed in @objectstack/spec 17.0.0 (2026-06 liveness audit — never read). Delete the key and declare the endpoint one level up, on the STACK: defineStack({ apis }). That surface EXECUTES from protocol 17. Before the executor landed it was refused wholesale — nothing mounted a declared path, so every key including authRequired parsed and gated nothing — and that blanket refusal is now narrowed to five per-endpoint publish gates (namespace, supported target, mapping, policy, uniqueness): an endpoint that passes them is mounted and serves traffic as soon as the stack is published. Two things to get right when you move it: the path must sit inside your own carve-out, /api/v1/apps/<manifest.namespace>/<subpath> with an explicit manifest.namespace (ADR-0121 D1/D2), and authRequired defaults to true — an explicit false is the only thing that opens anonymous access, and ADR-0121 D6 then requires an armed rateLimit: { enabled: true, windowMs, maxRequests }. Read the declarative-apis-endpoints-live entry of the protocol upgrade guide first; it is a security review, not a rename. A route that genuinely needs handler CODE is mounted imperatively instead: resolve the http.server service from your plugin context and register the route on kernel:ready (NOT the manifest contributes.routes key — removed in @objectstack/spec 17: nothing ever read it, and authoring it is now rejected with its own prescription). Run os migrate meta --from 16 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand. |
| sharing | never | optional | [REMOVED] App.sharing was removed in @objectstack/spec 17.0.0 (2026-06 liveness audit / ADR-0049 enforce-or-remove) — no public-app route ever read it, so it declared sharing that did not exist. Public access is granted per FORM VIEW (FormView.sharing, the public-data-collection surface). Delete the key. Run os migrate meta --from 16 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand. |
| embed | never | optional | [REMOVED] App.embed was removed in @objectstack/spec 17.0.0 (2026-06 liveness audit / ADR-0049) — no iframe route ever read it. Embedding is a per-form-view surface (FormView.sharing), not an app-level switch. Delete the key. Run os migrate meta --from 16 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand. |
| mobileNavigation | never | optional | [REMOVED] App.mobileNavigation was removed in @objectstack/spec 17.0.0 (2026-06 liveness audit — fully unimplemented; no renderer, including packages/mobile, ever read it). Delete the key; the block returns if/when a real mobile navigation ships. Run os migrate meta --from 16 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand. |
| defaultAgent | string | optional | Platform agent bound to this app's ambient chat ('ask' is the implicit default; 'build' for authoring surfaces) — ADR-0063 §1 |
| aria | never | optional | [REMOVED] App.aria was removed in @objectstack/spec 17.0.0 (2026-06 liveness audit — no renderer read app-level ARIA attributes). Declare aria on the page component that renders the DOM node instead (page.components[].aria; page.aria and the list view aria are live too). Delete the key. Run os migrate meta --from 16 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand. |
| protection | { lock: Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>; reason: string; docsUrl?: string } | optional | Package author protection block — lock policy for this app. |
| _lock | Enum<'none' | 'no-overlay' | 'no-delete' | 'full'> | optional | Item-level lock — controls overlay & delete (ADR-0010). |
| _lockReason | string | optional | Human-readable reason shown when a write is refused by _lock. |
| _lockSource | Enum<'artifact' | 'package' | 'env-forced'> | optional | Layer that set _lock (artifact | package | env-forced). |
| _provenance | Enum<'package' | 'org' | 'env-forced'> | optional | Origin of the item (package | org | env-forced). |
| _packageId | string | optional | Owning package machine id. |
| _packageVersion | string | optional | Owning package version. |
| _lockDocsUrl | string | optional | Optional documentation link surfaced next to _lockReason. |
ConceptListResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { name: string; label: string; icon?: string; description?: string }[] | ✅ | List of available concepts (Objects, Apps, Flows) |
Nested Shape: ConceptListResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: ConceptListResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
MetadataBulkRegisterRequest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| items | { type: string; name: string; data: Record<string, any> }[] | ✅ | Items to register |
| continueOnError | boolean | optional (default: false) | Continue on individual failure |
| validate | boolean | optional (default: true) | Validate before registering |
Nested Shape: MetadataBulkRegisterRequest.items[number]
| Property | Type | Required | Description |
|---|---|---|---|
| type | string | ✅ | Metadata type |
| name | string | ✅ | Item name |
| data | Record<string, any> | ✅ | Metadata payload |
MetadataBulkResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { total: integer; succeeded: integer; failed: integer; errors?: object[] } | ✅ | Bulk operation result |
Nested Shape: MetadataBulkResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataBulkResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
Nested Shape: MetadataBulkResponse.data
| Property | Type | Required | Description |
|---|---|---|---|
| total | integer | ✅ | Total items processed |
| succeeded | integer | ✅ | Successfully processed |
| failed | integer | ✅ | Failed items |
| errors | { type: string; name: string; error: string }[] | optional | Per-item errors |
MetadataBulkUnregisterRequest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| items | { type: string; name: string }[] | ✅ | Items to unregister |
Nested Shape: MetadataBulkUnregisterRequest.items[number]
| Property | Type | Required | Description |
|---|---|---|---|
| type | string | ✅ | Metadata type |
| name | string | ✅ | Item name |
MetadataDeleteResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { type: string; name: string } | ✅ |
Nested Shape: MetadataDeleteResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataDeleteResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
Nested Shape: MetadataDeleteResponse.data
| Property | Type | Required | Description |
|---|---|---|---|
| type | string | ✅ | Metadata type |
| name | string | ✅ | Deleted item name |
MetadataDependenciesResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { sourceType: string; sourceName: string; targetType: string; targetName: string; … }[] | ✅ | Items this item depends on |
Nested Shape: MetadataDependenciesResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataDependenciesResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
Nested Shape: MetadataDependenciesResponse.data[number]
| Property | Type | Required | Description |
|---|---|---|---|
| sourceType | string | ✅ | Dependent metadata type |
| sourceName | string | ✅ | Dependent metadata name |
| targetType | string | ✅ | Referenced metadata type |
| targetName | string | ✅ | Referenced metadata name |
| kind | Enum<'reference' | 'extends' | 'includes' | 'triggers'> | ✅ | How the dependency is formed |
MetadataDependentsResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { sourceType: string; sourceName: string; targetType: string; targetName: string; … }[] | ✅ | Items that depend on this item |
Nested Shape: MetadataDependentsResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataDependentsResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
Nested Shape: MetadataDependentsResponse.data[number]
| Property | Type | Required | Description |
|---|---|---|---|
| sourceType | string | ✅ | Dependent metadata type |
| sourceName | string | ✅ | Dependent metadata name |
| targetType | string | ✅ | Referenced metadata type |
| targetName | string | ✅ | Referenced metadata name |
| kind | Enum<'reference' | 'extends' | 'includes' | 'triggers'> | ✅ | How the dependency is formed |
MetadataExistsResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { exists: boolean } | ✅ |
Nested Shape: MetadataExistsResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataExistsResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
Nested Shape: MetadataExistsResponse.data
| Property | Type | Required | Description |
|---|---|---|---|
| exists | boolean | ✅ | Whether the item exists |
MetadataExportRequest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| types | string[] | optional | Filter by metadata types |
| namespaces | string[] | optional | Filter by namespaces |
| format | Enum<'json' | 'yaml'> | optional (default: "json") | Export format |
MetadataExportResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | any | ✅ | Exported metadata bundle |
Nested Shape: MetadataExportResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataExportResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
MetadataImportRequest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| data | any | ✅ | Metadata bundle to import |
| conflictResolution | Enum<'skip' | 'overwrite' | 'merge'> | optional (default: "skip") | Conflict resolution strategy |
| validate | boolean | optional (default: true) | Validate before import |
| dryRun | boolean | optional (default: false) | Dry run (no save) |
MetadataImportResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { total: integer; imported: integer; skipped: integer; failed: integer; … } | ✅ | Import result |
Nested Shape: MetadataImportResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataImportResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
MetadataItemResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { type: string; name: string; definition: Record<string, any> } | ✅ | Metadata item |
Nested Shape: MetadataItemResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataItemResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
Nested Shape: MetadataItemResponse.data
| Property | Type | Required | Description |
|---|---|---|---|
| type | string | ✅ | Metadata type |
| name | string | ✅ | Item name |
| definition | Record<string, any> | ✅ | Metadata definition payload |
MetadataListResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | Record<string, any>[] | ✅ | Array of metadata definitions |
Nested Shape: MetadataListResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataListResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
MetadataNamesResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | string[] | ✅ | Array of metadata item names |
Nested Shape: MetadataNamesResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataNamesResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
MetadataQueryRequest
Metadata query with filtering, sorting, and pagination
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| types | Enum<'object' | 'field' | 'hook' | 'seed' | 'mapping' | 'picklist' | 'view' | 'page' | 'dashboard' | 'app' | 'action' | 'report' | 'dataset' | 'flow' | 'job' | 'datasource' | 'external_catalog' | 'translation' | 'api' | 'email_template' | 'doc' | 'book' | 'permission' | 'position' | 'capability' | 'agent' | 'tool' | 'skill'>[] | optional | Filter by metadata types |
| namespaces | string[] | optional | Filter by namespaces |
| packageId | string | optional | Filter by owning package |
| search | string | optional | Full-text search query |
| scope | Enum<'system' | 'platform' | 'user'> | optional | Filter by scope |
| state | Enum<'draft' | 'active' | 'archived' | 'deprecated'> | optional | Filter by lifecycle state |
| tags | string[] | optional | Filter by tags |
| sortBy | Enum<'name' | 'type' | 'updatedAt' | 'createdAt'> | optional (default: "name") | Sort field |
| sortOrder | Enum<'asc' | 'desc'> | optional (default: "asc") | Sort direction |
| page | integer | optional (default: 1) | Page number |
| pageSize | integer | optional (default: 50) | Items per page |
MetadataQueryResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { items: object[]; total: integer; page: integer; pageSize: integer } | ✅ | Paginated query result |
Nested Shape: MetadataQueryResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataQueryResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
Nested Shape: MetadataQueryResponse.data
| Property | Type | Required | Description |
|---|---|---|---|
| items | { type: string; name: string; namespace?: string; label?: string; … }[] | ✅ | Matched metadata items |
| total | integer | ✅ | Total matching items |
| page | integer | ✅ | Current page |
| pageSize | integer | ✅ | Page size |
MetadataRegisterRequest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| type | Enum<'object' | 'field' | 'hook' | 'seed' | 'mapping' | 'picklist' | 'view' | 'page' | 'dashboard' | 'app' | 'action' | 'report' | 'dataset' | 'flow' | 'job' | … +13 more> | ✅ | Metadata type |
| name | string | ✅ | Item name (snake_case) |
| data | Record<string, any> | ✅ | Metadata payload |
| namespace | string | optional | Optional namespace |
Allowed Values: MetadataRegisterRequest.type
objectfieldhookseedmappingpicklistviewpagedashboardappactionreportdatasetflowjobdatasourceexternal_catalogtranslationapiemail_templatedocbookpermissionpositioncapabilityagenttoolskill
MetadataTypeInfoResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { type: string; label: string; description?: string; filePatterns: string[]; … } | optional | Type info |
Nested Shape: MetadataTypeInfoResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataTypeInfoResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
Nested Shape: MetadataTypeInfoResponse.data
| Property | Type | Required | Description |
|---|---|---|---|
| type | string | ✅ | Metadata type identifier |
| label | string | ✅ | Display label |
| description | string | optional | Description |
| filePatterns | string[] | ✅ | File glob patterns |
| supportsOverlay | boolean | ✅ | Whether a stored overlay row of an item a managed package ships may be removed through the ordinary delete door without the type's environment-overlay permission: the removal removes no managed definition, and changes what is served for permission alone; it opens no save and it decides no read |
| domain | string | ✅ | Protocol domain |
| actions | { name: string; label: string | Record<string, string>; description?: string | Record<string, string>; objectName?: string; … }[] | optional | Declarative type-level actions (buttons) the metadata-admin UI renders for this type |
MetadataTypesResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | string[] | ✅ | Registered metadata type identifiers |
Nested Shape: MetadataTypesResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataTypesResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
MetadataValidateRequest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| type | string | ✅ | Metadata type to validate against |
| data | any | ✅ | Metadata payload to validate |
MetadataValidateResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { valid: boolean; errors?: object[]; warnings?: object[] } | ✅ | Validation result |
Nested Shape: MetadataValidateResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: MetadataValidateResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
Nested Shape: MetadataValidateResponse.data
| Property | Type | Required | Description |
|---|---|---|---|
| valid | boolean | ✅ | Whether the metadata is valid |
| errors | { path: string; message: string; code?: string }[] | optional | Validation errors |
| warnings | { path: string; message: string }[] | optional | Validation warnings |
ObjectDefinitionResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: integer; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { name: string; label?: string; pluralLabel?: string; description?: string; … } | ✅ | Full Object Schema |
Nested Shape: ObjectDefinitionResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
| declaredCode | string | optional | The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
| message | string | ✅ | Readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message. |
| refusal | true | optional | Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value. |
| category | string | optional | Error category (e.g. validation, authorization) |
| httpStatus | integer | optional | HTTP status of the response carrying this error |
| details | any | optional | Additional error context (e.g. field validation errors) |
| requestId | string | optional | Request ID for tracking |
Nested Shape: ObjectDefinitionResponse.meta
| Property | Type | Required | Description |
|---|---|---|---|
| timestamp | string | ✅ | |
| duration | integer | optional | Server-side processing duration in milliseconds |
| requestId | string | optional | |
| traceId | string | optional |
Nested Shape: ObjectDefinitionResponse.data
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ | Machine unique key (snake_case). Immutable. |
| label | string | optional | Human readable singular label (e.g. "Account") |
| pluralLabel | string | optional | Human readable plural label (e.g. "Accounts") |
| description | string | optional | Developer documentation / description |
| icon | string | optional | Icon name (Lucide/Material) for UI representation |
| isSystem | boolean | optional (default: false) | Is system object (protected from deletion; defaults its org-wide sharing to public when no sharingModel is set — plugin-sharing) |
| managedBy | Enum<'platform' | 'config' | 'system-data' | 'engine-owned' | 'append-only' | 'better-auth'> | optional | Lifecycle bucket — platform (user CRUD) | config (admin authored) | system-data (platform-defined schema, admin/user-writable data) | engine-owned (engine owns the lifecycle, no user writes) | append-only (audit) | better-auth (identity). UI clients honour the resolved affordance matrix. |
| ownership | Enum<'user' | 'business_unit' | 'org' | 'none'> | optional | Record-ownership model: user (default — injects reassignable owner_id plus owning_business_unit_id) | business_unit (unit-owned: owning_business_unit_id only, no owner_id) | org | none (no per-record owner, neither anchor). Distinct from the package own/extend contribution kind. |
| userActions | { create?: boolean | object; import?: boolean | object; edit?: boolean | object; delete?: boolean | object; … } | optional | Per-object override of the resolved CRUD affordance matrix. |
| systemFields | false | { tenant?: boolean; audit?: boolean } | optional | Opt out of, or selectively disable, registry-level system-field auto-injection. |
| datasource | string | optional (default: "default") | Target Datasource ID. "default" is the primary DB. |
| external | { remoteName?: string; remoteSchema?: string; writable?: boolean; columnMap?: Record<string, string>; … } | optional | Remote table binding for federated (external) objects. |
| fields | Record<string, { name?: string; label?: string; type: Enum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | …>; description?: string; … }> | ✅ | Field definitions map. Keys must be snake_case identifiers; "proto", "constructor" and "prototype" are refused. |
| attachedOnRead | Record<string, Record<string, Enum<'number' | 'text' | 'boolean' | 'date'>>> | optional | Blocks a service attaches to each row it serves, computed per caller on read and never stored: block name → { leaf key → value type (number | text | boolean | date) }. NOT a field — no column, form, list view, export, write path or translation bundle reads it, and a block name may not repeat a declared field name. Its reader is the shared build validator (@objectstack/lint over @objectstack/formula, as os build / os validate run it), and only where record is a row the service served: in an action's visible and disabled predicates record.<block> resolves, and record.<block>.<leaf> resolves only to a leaf the block declares. Every other expression site binds the stored row, which never carries a block — a flow condition, a validation rule, a field rule or formula, an option visibleWhen, a sharing rule, a hook — and refuses record.<block> as an unknown field. |
| indexes | { name?: string; fields: string[]; unique?: false | 'global' | 'organization' }[] | optional | Database performance indexes |
| fieldGroups | { key: string; label: string; icon?: string; description?: string; … }[] | optional | Ordered list of field groups (array order = display order). See ObjectFieldGroupSchema. |
| tenancy | { enabled: boolean; tenantField?: string } | optional | Multi-tenancy configuration for SaaS applications |
| access | { default?: Enum<'public' | 'private'> } | optional | [ADR-0066 D2] Object exposure posture (public-by-default vs private secure-by-default). |
| requiredPermissions | string[] | { read?: string[]; create?: string[]; update?: string[]; delete?: string[] } | optional | [ADR-0066 D3/⑤] Capabilities required to access this object (AND-gate) — string[] gates all CRUD, or a {read,create,update,delete} map gates per operation. |
| lifecycle | { class: Enum<'record' | 'audit' | 'telemetry' | 'transient' | 'event'>; retention?: object; ttl?: object; storage?: object; … } | optional | Data lifecycle contract (ADR-0057): class + retention/ttl/rotation/archive policies enforced by the platform LifecycleService. |
| fileAccessDelegate | string | optional | Kernel service that authorizes downloads of files owned by this object's media fields, and decides whether a reader who may not read sys_file sees their name, size and type in a record read of this object (asked once per owning record on each such read), instead of testing whether the caller can read the owning row. For objects whose access is mediated by a service (e.g. sys_approval_action → approvals). Fails closed. |
| validations | any[] | optional | Object-level validation rules |
| activityMilestones | { field: string; value: string; summary: string; type?: string }[] | optional | Declarative semantic activity milestones — emit a templated timeline row when a field transitions into a value, no hook code (ADR-0052 §5b.2). |
| nameField | string | optional | [ADR-0079] Canonical primary title field — the stored field used as the record display name (e.g. "name", "title"). |
| displayNameField | string | optional | [DEPRECATED → nameField] Field to use as the record display name (e.g., "name", "title"). Accepted as an alias for nameField. |
| titleFormat | string | { dialect: 'template'; source?: string; ast?: any; meta?: object } | optional | [DEPRECATED → nameField (ADR-0079)] Render-only title template; the server cannot return or query it, and an explicit nameField now takes precedence. Migrate a single-field title to nameField, a composite to a formula field designated as nameField. Placeholders may be written {{field}} or {field} — the title renderers treat the two as equivalent, normalizing {{field}} to {field} before substituting; neither spelling is judged at parse time. |
| imageField | string | optional | The record's picture: names the field the record page header (record chrome) draws beside the title — one object-level declaration every record detail page reads, not a per-page header prop. Must name a field of this object whose type is image or avatar; any other name is refused. A record whose field is empty shows no picture (no initials or placeholder). |
| highlightFields | string[] | optional | [ADR-0085] Ordered most-important fields; first entry wins where only one fits. Drives default columns, cards, previews, detail highlight strip. Renamed from compactLayout. |
| stageField | string | false | optional | [ADR-0085] Lifecycle stage field (linear/ordered), or false to declare the status field non-linear and suppress stage heuristics. Absent = heuristic detection allowed. |
| editMode | Enum<'modal' | 'page'> | optional | Edit-interaction intent for records of this object: 'modal' opens the edit form as a dialog over the current view; 'page' navigates to a dedicated full-page edit route. Absent = the renderer picks its own default (objectui defaults to modal). Cross-renderer intent, not pixel styling (family). |
| listViews | Record<string, { name?: string; label?: string | Record<string, string>; type?: Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | 'chart' | 'tree'>; data?: object | object | object; … }> | optional | Built-in named list views (segmented tabs) shipped with the object schema — "views" mode, dropdown userFilters allowed, no page-only tabs (ADR-0047) |
| searchableFields | string[] | optional | Fields the $search query matches against (ADR-0061). Canonical default for the record picker, list quick-search and global search; views may narrow it. When unset, search auto-defaults to the name/title field plus short-text fields. Entries must name a STORED column: a virtual formula field is computed on read and materializes no column, so searching it can never match and it is refused — mirror the value onto a stored text field and declare that. |
| enable | { trackHistory?: boolean; searchable?: boolean; apiEnabled?: boolean; apiMethods?: Enum<'get' | 'list' | 'create' | 'update' | 'delete' | 'bulk'>[]; … } | optional | Enabled system features modules |
| sharingModel | Enum<'private' | 'public_read' | 'public_read_write' | 'controlled_by_parent'> | optional | Org-Wide Default record visibility (OWD) for INTERNAL users. Canonical four only (legacy aliases removed, ADR-0090 D4): private (owner-only) | public_read (everyone reads, owner writes) | public_read_write (everyone reads+writes) | controlled_by_parent (derived from the master record). A CUSTOM object that omits this resolves to private at runtime (ADR-0090 D1). |
| externalSharingModel | never | optional | [REMOVED] object.externalSharingModel was removed in @objectstack/spec 18 (ADR-0049 enforce-or-remove) — it never had an effect: no request resolves an external principal, and the external rung of the authorization kernel (ADR-0095) admits explicitly shared rows only, never an org-wide default, so the value changed no answer for anyone. Delete the key. sharingModel is the one org-wide default; a principal reaches a row it does not own through an explicit share, and an anonymous reader through a share link (publicSharing). Run os migrate meta --from 17 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand. |
| publicSharing | { enabled?: boolean; allowedAudiences?: Enum<'public' | 'link_only' | 'signed_in' | 'email'>[]; allowedPermissions?: Enum<'view' | 'comment' | 'edit'>[]; maxExpiryDays?: integer; … } | optional | Public share-link policy (Notion/Figma-style link sharing) |
| actions | { name: string; label: string | Record<string, string>; description?: string | Record<string, string>; objectName?: string; … }[] | optional | Actions associated with this object (auto-populated from top-level actions via objectName) |
| protection | { lock: Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>; reason: string; docsUrl?: string } | optional | Package author protection block — lock policy for this object. |
| _lock | Enum<'none' | 'no-overlay' | 'no-delete' | 'full'> | optional | Item-level lock — controls overlay & delete (ADR-0010). |
| _lockReason | string | optional | Human-readable reason shown when a write is refused by _lock. |
| _lockSource | Enum<'artifact' | 'package' | 'env-forced'> | optional | Layer that set _lock (artifact | package | env-forced). |
| _provenance | Enum<'package' | 'org' | 'env-forced'> | optional | Origin of the item (package | org | env-forced). |
| _packageId | string | optional | Owning package machine id. |
| _packageVersion | string | optional | Owning package version. |
| _lockDocsUrl | string | optional | Optional documentation link surfaced next to _lockReason. |