ObjectStackEnvironment Artifact
Environment Artifact protocol schemas
Project Artifact Format Protocol (v0)
Defines the immutable envelope produced by objectstack compile and consumed
by ObjectOS at boot. The artifact carries everything an ObjectOS instance
needs to hydrate a project kernel without reading control-plane DB rows
directly.
Boundary
- Artifact (this schema): project metadata + inlined function code +
plugin/driver requirements. Immutable, content-addressable via commitId
and checksum.
- Deployment Config (NOT in this schema): business DB coordinates,
credentials, project 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 Project Artifact envelope (v0)
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| schemaVersion | string | ✅ | Project artifact envelope schema version |
| environmentId | string | ✅ | Project 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 project 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 project 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 | |
| roles | any[] | optional | |
| profiles | 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 project |