ObjectStackEnvironment Artifact
Environment Artifact protocol schemas
Environment Artifact Format Protocol (v0)
Defines the immutable envelope produced by objectstack compile and consumed
by the ObjectStack runtime at boot. The artifact carries everything a runtime instance
needs to hydrate an environment kernel without reading control-plane DB rows
directly.
Boundary
- Artifact (this schema): environment metadata + inlined function code +
plugin/driver requirements. Immutable, content-addressable via commitId
and checksum.
- Deployment Config (NOT in this schema): business DB coordinates,
credentials, environment identity, secrets. Injected at runtime.
See content/docs/concepts/north-star.mdx §6.3 for the runtime-inputs
boundary, and ROADMAP.md M1 for the milestone definition.
Storage / Distribution
v0 stores the full payload inline. Future revisions may swap metadata /
functions for a payloadRef that points at out-of-band storage (S3,
signed URL). The envelope shape preserves room for that indirection without
a breaking schema bump.
Source: packages/spec/src/system/environment-artifact.zod.ts
TypeScript Usage
import { EnvironmentArtifact, EnvironmentArtifactChecksum, EnvironmentArtifactFunction, EnvironmentArtifactFunctionLanguageEnum, EnvironmentArtifactHashAlgorithmEnum, EnvironmentArtifactManifest, EnvironmentArtifactMetadata, EnvironmentArtifactPayloadRef, EnvironmentArtifactRequirement } from '@objectstack/spec/system';
import type { EnvironmentArtifact, EnvironmentArtifactChecksum, EnvironmentArtifactFunction, EnvironmentArtifactFunctionLanguageEnum, EnvironmentArtifactHashAlgorithmEnum, EnvironmentArtifactManifest, EnvironmentArtifactMetadata, EnvironmentArtifactPayloadRef, EnvironmentArtifactRequirement } from '@objectstack/spec/system';
// Validate data
const result = EnvironmentArtifact.parse(data);EnvironmentArtifact
ObjectStack Environment Artifact envelope (v0)
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| schemaVersion | string | ✅ | Environment artifact envelope schema version |
| environmentId | string | ✅ | Environment identifier (control-plane scoped) |
| commitId | string | ✅ | Content-addressable revision id |
| checksum | Object | ✅ | Artifact integrity checksum |
| builtAt | string | optional | ISO-8601 timestamp of when the artifact was built |
| builtWith | string | optional | Build tool identifier |
| metadata | Record<string, any> | ✅ | Compiled environment metadata grouped by category |
| functions | Object[] | ✅ | Inlined function code packaged with the artifact |
| manifest | Object | ✅ | Plugin/driver requirements baked into the artifact |
| payloadRef | Object | optional | Out-of-band payload reference (reserved for future use) |
EnvironmentArtifactChecksum
Artifact integrity checksum
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| algorithm | Enum<'sha256' | 'sha384' | 'sha512'> | ✅ | Hash algorithm used for the artifact checksum |
| value | string | ✅ | Hex-encoded digest of the artifact body |
EnvironmentArtifactFunction
A single inlined function
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ | Function machine name (snake_case) |
| language | Enum<'javascript' | 'typescript'> | ✅ | Source language of the function code |
| code | string | ✅ | Inlined function source |
| source | Object | optional | Source-map metadata for the function |
| hash | string | optional | Hex SHA-256 of the inlined code |
EnvironmentArtifactFunctionLanguageEnum
Source language of the function code
Allowed Values
javascripttypescript
EnvironmentArtifactHashAlgorithmEnum
Hash algorithm used for the artifact checksum
Allowed Values
sha256sha384sha512
EnvironmentArtifactManifest
Plugin/driver requirements baked into the artifact
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| plugins | Object[] | optional | |
| drivers | Object[] | optional | |
| engine | Object | optional |
EnvironmentArtifactMetadata
Compiled environment metadata grouped by category
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| objects | any[] | optional | |
| fields | any[] | optional | |
| views | any[] | optional | |
| apps | any[] | optional | |
| pages | any[] | optional | |
| dashboards | any[] | optional | |
| reports | any[] | optional | |
| flows | any[] | optional | |
| workflows | any[] | optional | |
| triggers | any[] | optional | |
| agents | any[] | optional | |
| tools | any[] | optional | |
| skills | any[] | optional | |
| permissions | any[] | optional | |
| permissionSets | any[] | optional | |
| positions | any[] | optional | |
| translations | any[] | optional | |
| datasources | any[] | optional | |
| datasets | any[] | optional | |
| actions | any[] | optional | |
| apis | any[] | optional |
EnvironmentArtifactPayloadRef
Out-of-band payload reference (reserved for future use)
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| url | string | ✅ | Signed URL pointing at the artifact payload |
| expiresAt | string | optional | ISO-8601 expiry timestamp |
| checksum | Object | ✅ | Checksum of the referenced payload |
EnvironmentArtifactRequirement
A plugin or driver dependency declaration
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| id | string | ✅ | Plugin/driver package id |
| version | string | optional | SemVer range required by the environment |