ResourceControlRequest `common.resource-control-request@1`

Generated at 2026-10-05 03:00:43 UTC from openvibe-contracts v0.97.0 and openvibe-sdk v0.26.0.

Version: 1.0.0
Owner: contracts
Visibility: first-party
Status: active
Compatibility: backward
Decision: ADR-048
Schema: https://openvibe.network/contracts/common/resource-control-request.v1.json

common.resource-control-request@1: one control operation OpenVibe.Services (or Actor's Console) sends to the authority that owns a resource (ADR-048, plan T13). Services never mutates another service's database; every create, update, start, stop, delete, resize, rotate, pair, grant or revoke is this request to the owning authority's control API, which decides and answers with a common.resource-control-result@1. A request names exactly one of resource (every action but create) or resource_kind (create, before the name exists). project_id is the tenancy boundary and equals the project segment of resource. idempotency_key makes a retry safe: the authority answers a repeated key with the first result. A sensitive action (money, publishing, deleting, physical control) is refused with confirmation_required until its owner approves; the retry carries that confirmation_id (roadmap WS-Z2). The cross-field rules are checked by contracts.resources.checkControlRequest.

Fields

Field	Type	Required	Description	Constraints
`action`	enum	yes		`one of "create", "update", "delete", "start", "stop", "suspend", "resume", "resize", "rotate", "pair", "grant", "revoke", "archive"`
`resource`	common.resource-name		The resource acted on; required for every action but create.
`resource_kind`	string		service.type (a common.resource-summary@1 kind), for create, before the resource name exists.	`pattern ^[a-z][a-z0-9-]{0,31}\.[a-z][a-z0-9-]{0,39}$`
`project_id`	string	yes		`pattern ^prj_[0-9A-HJKMNP-TV-Z]{26}$`
`params`	object		Action-specific input, shaped by the authority's own contract (never redefined here).
`idempotency_key`	string	yes		`minLength 8` `maxLength 200`
`on_behalf_of`	identity.subject-ref		The subject whose grant the authority checks; the caller's own token says who sent it.
`confirmation_id`	string \| null		The approved confirmation from an earlier confirmation_required answer.	`maxLength 80`
`dry_run`	boolean		Decide and explain without applying.	`default false`
`trace_id`	string			`pattern ^[0-9a-f]{32}$`

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: create-events-queue

{
  "action": "create",
  "resource_kind": "events.queue",
  "project_id": "prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4",
  "params": {
    "name": "orders"
  },
  "idempotency_key": "ctl-01K6R3-queue-create"
}

Valid: delete-run

{
  "action": "delete",
  "resource": "ovrn:run:prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4:sandbox/run_01K6R3A1B2C3D4E5F6G7H8J9KA",
  "project_id": "prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4",
  "idempotency_key": "ctl-01K6R3-run-delete",
  "on_behalf_of": {
    "type": "user",
    "id": "usr_01K6R2Z8C4V7M9Q3T5W1X2Y3Z6"
  },
  "confirmation_id": "cnf_01K6R3A1B2C3D4E5F6G7H8J9KE",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Valid: dry-run-resize

{
  "action": "resize",
  "resource": "ovrn:media:prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4:object/med_01K6R3A1B2C3D4E5F6G7H8J9KB",
  "project_id": "prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4",
  "params": {
    "bytes": 1073741824
  },
  "idempotency_key": "resize-01",
  "dry_run": true
}

Rejected: both-names

{
  "action": "stop",
  "resource": "ovrn:run:prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4:sandbox/run_01K6R3A1B2C3D4E5F6G7H8J9KA",
  "resource_kind": "run.sandbox",
  "project_id": "prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4",
  "idempotency_key": "ctl-01K6R3-run-stop"
}

Rejected: create-with-resource

{
  "action": "create",
  "resource": "ovrn:run:prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4:sandbox/run_01K6R3A1B2C3D4E5F6G7H8J9KA",
  "project_id": "prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4",
  "idempotency_key": "ctl-01K6R3-run-create"
}

Rejected: delete-without-resource

{
  "action": "delete",
  "resource_kind": "run.sandbox",
  "project_id": "prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4",
  "idempotency_key": "ctl-01K6R3-run-delete"
}

Rejected: no-key

{
  "action": "stop",
  "resource": "ovrn:run:prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4:sandbox/run_01K6R3A1B2C3D4E5F6G7H8J9KA",
  "project_id": "prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4"
}

Rejected: other-project

{
  "action": "delete",
  "resource": "ovrn:run:prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z5:sandbox/run_01K6R3A1B2C3D4E5F6G7H8J9KA",
  "project_id": "prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4",
  "idempotency_key": "ctl-01K6R3-run-delete"
}

Rejected: unknown-action

{
  "action": "explode",
  "resource": "ovrn:run:prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4:sandbox/run_01K6R3A1B2C3D4E5F6G7H8J9KA",
  "project_id": "prj_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4",
  "idempotency_key": "ctl-01K6R3-run-boom"
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('common.resource-control-request@1', value);   // { valid, errors: [{ path, message }] }

ResourceControlRequest common.resource-control-request@1

Fields

Examples

Validate

ResourceControlRequest `common.resource-control-request@1`