Protection schema — Shared Protocol reference

Package-level metadata protection (ADR-0010 §3.7 — Phase 4.3)

Public, type-safe author surface for package authors to declare how much of one of their metadata items the runtime (and the tenant's Studio) is allowed to mutate. Internally this is what gets translated into the _lock / _lockReason / _lockDocsUrl private envelope (kernel/metadata-protection.zod.ts) that the protocol layer enforces.

Why two layers?

• protection is the author DX surface — typed, validated, and discoverable via IntelliSense on every *.app.ts / *.object.ts / *.view.ts etc.
• _lock envelope is the runtime surface — strips off the protection block on load and stamps the private fields so the persistence and overlay layers don't drag the author-facing block through every sys_metadata overlay diff.

Example:

export const SETUP_APP: App = {
  name: 'setup',
  label: 'Setup',
  protection: {
    lock: 'full',
    reason: 'Core admin UI shipped by @objectstack/platform-objects.',
    docsUrl: 'https://objectstack.ai/docs/references/shared/protection',
  },
  // ...
};

The loader (metadata/plugin.ts + objectql/registry.ts) calls applyProtection to translate this block into the private _lock envelope at registration time. Authors should NEVER set the underscored fields directly — they are an implementation detail.

That loader is the block's only door (ADR-0010 Phase 4.3). The metadata API's save door (PUT /api/v1/meta/{type}/{name}) writes environment-authored items, which take no package lock (ADR-0010 §3.5), so it does not translate the block: it refuses it with 400 VALIDATION_ERROR and stores nothing.

See also:

• ADR-0010 §3.7 — Future work → now implemented.
• kernel/metadata-protection.zod.ts — the runtime envelope.

TypeScript Usage

import { ProtectionSchema } from '@objectstack/spec/shared';
import type { Protection } from '@objectstack/spec/shared';

// Validate data
const result = ProtectionSchema.parse(data);

Protection

Properties