UsageSample `platform.usage-sample@1`

Generated at 2026-10-02 13:11:40 UTC from openvibe-contracts v0.84.0 and openvibe-sdk v0.26.0.

Version: 1.0.0
Owner: network
Visibility: public
Status: active
Compatibility: backward
Decision: ADR-034
Schema: https://openvibe.network/contracts/platform/usage-sample.v1.json

One metered usage reading with retry-safe attribution (T1 Universal Fabric; ADR-034 proposed). Consumers dedupe on `idempotency_key`.

Fields

Field	Type	Required	Description	Constraints
`id`	string	yes
`idempotency_key`	string	yes	Stable across retries
`service`	string	yes
`project`	string			`pattern ^prj_[0-9A-HJKMNP-TV-Z]{26}$`
`subject`	string
`resource`	string
`provider`	string
`node`	string
`cell`	string
`region`	string
`operation`	string	yes
`quantity`	number	yes		`minimum 0`
`unit`	string	yes
`at`	string	yes		`format date-time`
`cost_estimate`	number		Estimated USD	`minimum 0`
`free_allowance_used`	number		How much of this reading's `quantity` the free allowance covered (platform.rate-card@1 `free_allowance` for this provider/metric and period), in the reading's own `unit`, not in rate-card units, money or Vibes: a 1.5 GiB reading with 1 GiB free carries 1. Never more than `quantity`; 0 when nothing was free. Absent: not rated against a rate card.	`minimum 0`
`vibes_charged`	integer		Vibes charged for this reading, as an integer count of vibes-bits (Billing's ledger minor unit, currency `vibes-bits`; balance credit and ledger amounts use the same unit). Never whole Vibes, USD or a fraction: round once, when rating. Covers only `quantity` minus `free_allowance_used`; 0 means rated and nothing charged. Absent means not rated (yet). Records a charge already made in Billing's ledger; it is never a request to charge.	`minimum 0`
`route_epoch`	integer			`minimum 0`
`trace_id`	string
`source`	string	yes

Examples

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

Valid: all-fifteen-fields

{
  "id": "use-2",
  "idempotency_key": "media:delivery:2",
  "service": "media",
  "project": "prj_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "subject": "user:usr_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "resource": "object-1",
  "provider": "local",
  "node": "node-1",
  "cell": "cell-west",
  "region": "us-west",
  "operation": "deliver",
  "quantity": 1.5,
  "unit": "GiB",
  "at": "2026-09-30T10:00:00Z",
  "cost_estimate": 0.03,
  "source": "media.egress",
  "free_allowance_used": 1,
  "vibes_charged": 4,
  "route_epoch": 3,
  "trace_id": "tr-42"
}

Valid: example

{
  "id": "use-1",
  "idempotency_key": "media:delivery:1",
  "service": "media",
  "project": "prj_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "subject": "user:usr_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "resource": "object-1",
  "provider": "local",
  "node": "node-1",
  "cell": "cell-west",
  "region": "us-west",
  "operation": "deliver",
  "quantity": 1.5,
  "unit": "GiB",
  "at": "2026-09-30T10:00:00Z",
  "cost_estimate": 0.03,
  "source": "media.egress"
}

Valid: minimal

{
  "id": "use-3",
  "idempotency_key": "media:delivery:3",
  "service": "media",
  "operation": "deliver",
  "quantity": 0.25,
  "unit": "GiB",
  "at": "2026-09-30T10:05:00Z",
  "source": "media.egress"
}

Rejected: free-allowance-used-negative

{
  "id": "use-2",
  "idempotency_key": "media:delivery:2",
  "service": "media",
  "project": "prj_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "subject": "user:usr_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "resource": "object-1",
  "provider": "local",
  "node": "node-1",
  "cell": "cell-west",
  "region": "us-west",
  "operation": "deliver",
  "quantity": 1.5,
  "unit": "GiB",
  "at": "2026-09-30T10:00:00Z",
  "cost_estimate": 0.03,
  "source": "media.egress",
  "free_allowance_used": -1,
  "vibes_charged": 4,
  "route_epoch": 3,
  "trace_id": "tr-42"
}

Rejected: missing-id

{
  "idempotency_key": "media:delivery:1",
  "service": "media",
  "project": "prj_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "subject": "user:usr_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "resource": "object-1",
  "provider": "local",
  "node": "node-1",
  "cell": "cell-west",
  "region": "us-west",
  "operation": "deliver",
  "quantity": 1.5,
  "unit": "GiB",
  "at": "2026-09-30T10:00:00Z",
  "cost_estimate": 0.03,
  "source": "media.egress"
}

Rejected: vibes-charged-fraction

{
  "id": "use-2",
  "idempotency_key": "media:delivery:2",
  "service": "media",
  "project": "prj_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "subject": "user:usr_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "resource": "object-1",
  "provider": "local",
  "node": "node-1",
  "cell": "cell-west",
  "region": "us-west",
  "operation": "deliver",
  "quantity": 1.5,
  "unit": "GiB",
  "at": "2026-09-30T10:00:00Z",
  "cost_estimate": 0.03,
  "source": "media.egress",
  "free_allowance_used": 1,
  "vibes_charged": 1.5,
  "route_epoch": 3,
  "trace_id": "tr-42"
}

Rejected: vibes-charged-negative

{
  "id": "use-2",
  "idempotency_key": "media:delivery:2",
  "service": "media",
  "project": "prj_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "subject": "user:usr_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "resource": "object-1",
  "provider": "local",
  "node": "node-1",
  "cell": "cell-west",
  "region": "us-west",
  "operation": "deliver",
  "quantity": 1.5,
  "unit": "GiB",
  "at": "2026-09-30T10:00:00Z",
  "cost_estimate": 0.03,
  "source": "media.egress",
  "free_allowance_used": 1,
  "vibes_charged": -1,
  "route_epoch": 3,
  "trace_id": "tr-42"
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('platform.usage-sample@1', value);   // { valid, errors: [{ path, message }] }

UsageSample platform.usage-sample@1

Fields

Examples

Validate

UsageSample `platform.usage-sample@1`