Metadata Metadata protocol schemas
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.
┌──────────────────────────────────────────────────────────────────┐ │ @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 │ └──────────────────────────────────────────────────────────────────┘
Salesforce : Metadata API (deploy, retrieve, describe)ServiceNow : System Dictionary + Metadata APIKubernetes : API Server + CRD Registry
Source: packages/spec/src/api/metadata.zod.ts
import { AppDefinitionResponseSchema, ConceptListResponseSchema, MetadataBulkRegisterRequestSchema, MetadataBulkResponseSchema, MetadataBulkUnregisterRequestSchema, MetadataDeleteResponseSchema, MetadataDependenciesResponseSchema, MetadataDependentsResponseSchema, MetadataEffectiveResponseSchema, MetadataExistsResponseSchema, MetadataExportRequestSchema, MetadataExportResponseSchema, MetadataImportRequestSchema, MetadataImportResponseSchema, MetadataItemResponseSchema, MetadataListResponseSchema, MetadataNamesResponseSchema, MetadataOverlayResponseSchema, MetadataOverlaySaveRequestSchema, MetadataQueryRequestSchema, MetadataQueryResponseSchema, MetadataRegisterRequestSchema, MetadataTypeInfoResponseSchema, MetadataTypesResponseSchema, MetadataValidateRequestSchema, MetadataValidateResponseSchema, ObjectDefinitionResponseSchema } from '@objectstack/spec/api' ; import type { AppDefinitionResponse, ConceptListResponse, MetadataBulkRegisterRequest, MetadataBulkResponse, MetadataBulkUnregisterRequest, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportResponse, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypeInfoResponse, MetadataTypesResponse, MetadataValidateRequest, MetadataValidateResponse, ObjectDefinitionResponse } from '@objectstack/spec/api' ; // Validate data const result = AppDefinitionResponseSchema. parse (data); Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; 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
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { name: string; label: string; icon?: string; description?: string }[]✅ List of available concepts (Objects, Apps, Flows)
Property Type Required Description items { type: string; name: string; data: Record<string, any> }[]✅ Items to register continueOnError boolean✅ Continue on individual failure validate boolean✅ Validate before registering
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { total: integer; succeeded: integer; failed: integer; errors?: object[] }✅ Bulk operation result
Property Type Required Description items { type: string; name: string }[]✅ Items to unregister
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { type: string; name: string }✅
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { sourceType: string; sourceName: string; targetType: string; targetName: string; … }[]✅ Items this item depends on
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { sourceType: string; sourceName: string; targetType: string; targetName: string; … }[]✅ Items that depend on this item
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data Record<string, any>optional Effective metadata with all overlays applied
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { exists: boolean }✅
Property Type Required Description types string[]optional Filter by metadata types namespaces string[]optional Filter by namespaces format Enum<'json' | 'yaml'>✅ Export format
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data any✅ Exported metadata bundle
Property Type Required Description data any✅ Metadata bundle to import conflictResolution Enum<'skip' | 'overwrite' | 'merge'>✅ Conflict resolution strategy validate boolean✅ Validate before import dryRun boolean✅ Dry run (no save)
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { total: integer; imported: integer; skipped: integer; failed: integer; … }✅ Import result
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { type: string; name: string; definition: Record<string, any> }✅ Metadata item
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data Record<string, any>[]✅ Array of metadata definitions
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data string[]✅ Array of metadata item names
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { id: string; baseType: string; baseName: string; packageId?: string; … }optional Overlay definition, undefined if none
Overlay to save
Property Type Required Description id string✅ Overlay record ID (UUID) baseType string✅ Metadata type being customized baseName string✅ Metadata name being customized packageId stringoptional Package ID that delivered the base metadata packageVersion stringoptional Package version when overlay was created scope Enum<'platform' | 'user'>✅ Customization scope (platform=admin, user=personal) tenantId stringoptional Tenant identifier owner stringoptional Owner user ID for user-scope overlays patch Record<string, any>✅ JSON Merge Patch payload (changed fields only) changes { path: string; originalValue?: any; currentValue: any; changedBy?: string; … }[]optional Field-level change tracking for conflict detection active boolean✅ Whether this overlay is active createdAt stringoptional createdBy stringoptional updatedAt stringoptional updatedBy stringoptional
Metadata query with filtering, sorting, and pagination
Property Type Required Description types Enum<'object' | 'field' | 'hook' | 'seed' | 'mapping' | '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 stringoptional Filter by owning package search stringoptional 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'>✅ Sort field sortOrder Enum<'asc' | 'desc'>✅ Sort direction page integer✅ Page number pageSize integer✅ Items per page
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { items: object[]; total: integer; page: integer; pageSize: integer }✅ Paginated query result
Property Type Required Description type Enum<'object' | 'field' | 'hook' | 'seed' | 'mapping' | 'view' | 'page' | 'dashboard' | 'app' | 'action' | 'report' | 'dataset' | 'flow' | 'job' | 'datasource' | … +12 more>✅ Metadata type name string✅ Item name (snake_case) data Record<string, any>✅ Metadata payload namespace stringoptional Optional namespace
objectfieldhookseedmappingviewpagedashboardappactionreportdatasetflowjobdatasourceexternal_catalogtranslationapiemail_templatedocbookpermissionpositioncapabilityagenttoolskill
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { type: string; label: string; description?: string; filePatterns: string[]; … }optional Type info
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data string[]✅ Registered metadata type identifiers
Property Type Required Description type string✅ Metadata type to validate against data any✅ Metadata payload to validate
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { valid: boolean; errors?: object[]; warnings?: object[] }✅ Validation result
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { name: string; label?: string; pluralLabel?: string; description?: string; … }✅ Full Object Schema
ObjectStack