ObjectZoneUsage zone.object-zone-usage@1

Generated at from openvibe-contracts v0.97.0 and openvibe-sdk v0.26.0.

Version
1.0.0
Owner
zone
Visibility
public
Status
planned
Compatibility
backward
Decision
ADR-031
Schema
https://openvibe.network/contracts/zone/object-zone-usage.v1.json

zone.object-zone-usage@1 (PLANNED; ADR-031 amendment 2026-10-02): the answer of GET /api/v1/zones/{zone_id}/usage on OpenVibe.Zone (capability zone.usage.read). Zone never counts. current is the live-object snapshot that Media's internal zone endpoint returns. series sums Media's hourly media.usage.recorded rollups (common.usage-recorded@1) whose dimension is this zone id in lowercase, over the closed hours of the current UTC month. Rollups are counts; Billing rates only platform.usage-sample readings (billing.usage.record). Zone's control operations are not metered. ovrn is the OVRN of zone_id, never of another zone (contracts.zones.checkObjectZoneUsage). More fields may be added.

Fields

FieldTypeRequiredDescriptionConstraints
zone_idstringyes
  • pattern ^zon_[0-9A-HJKMNP-TV-Z]{26}$
ovrnstringyes
  • pattern ^ovrn:zone:prj_[0-9A-HJKMNP-TV-Z]{26}:object-zone/zon_[0-9A-HJKMNP-TV-Z]{26}$
currentobjectyes
  • no other fields
current.stored_bytesintegeryes
  • minimum 0
current.objectsintegeryes
  • minimum 0
current.as_ofstringyes
  • format date-time
window_startstringyesThe start of the current UTC month.
  • format date-time
window_endstringyesThe end of the last closed hour that Media has reported.
  • format date-time
seriesarray of objectyes
  • maxItems 32
  • items: no other fields
series[].capabilitystringyes
  • pattern ^media\.object\.[a-z0-9_]+$
series[].unitenumyes
  • one of "byte_hours", "requests", "egress_bytes"
series[].quantityintegeryes
  • minimum 0

Examples

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

Valid: month-to-date
{
  "zone_id": "zon_01K2A9C3D5E7F9G1H3J5K7M9N1",
  "ovrn": "ovrn:zone:prj_01JZQ3V8X5N7K2M4P6R8T0W2Y4:object-zone/zon_01K2A9C3D5E7F9G1H3J5K7M9N1",
  "current": {
    "stored_bytes": 1048576,
    "objects": 12,
    "as_of": "2026-10-02T10:00:00Z"
  },
  "window_start": "2026-10-01T00:00:00Z",
  "window_end": "2026-10-02T10:00:00Z",
  "series": [
    {
      "capability": "media.object.upload",
      "unit": "byte_hours",
      "quantity": 25165824
    },
    {
      "capability": "media.object.read",
      "unit": "requests",
      "quantity": 340
    },
    {
      "capability": "media.object.read",
      "unit": "egress_bytes",
      "quantity": 8388608
    }
  ]
}
Rejected: missing-current
{
  "zone_id": "zon_01K2A9C3D5E7F9G1H3J5K7M9N1",
  "ovrn": "ovrn:zone:prj_01JZQ3V8X5N7K2M4P6R8T0W2Y4:object-zone/zon_01K2A9C3D5E7F9G1H3J5K7M9N1",
  "window_start": "2026-10-01T00:00:00Z",
  "window_end": "2026-10-02T10:00:00Z",
  "series": [
    {
      "capability": "media.object.upload",
      "unit": "byte_hours",
      "quantity": 25165824
    },
    {
      "capability": "media.object.read",
      "unit": "requests",
      "quantity": 340
    },
    {
      "capability": "media.object.read",
      "unit": "egress_bytes",
      "quantity": 8388608
    }
  ]
}
Rejected: ovrn-names-other-zone
{
  "zone_id": "zon_01K2A9C3D5E7F9G1H3J5K7M9N1",
  "ovrn": "ovrn:zone:prj_01JZQ3V8X5N7K2M4P6R8T0W2Y4:object-zone/zon_01K2A9C3D5E7F9G1H3J5K7M9N9",
  "current": {
    "stored_bytes": 1048576,
    "objects": 12,
    "as_of": "2026-10-02T10:00:00Z"
  },
  "window_start": "2026-10-01T00:00:00Z",
  "window_end": "2026-10-02T10:00:00Z",
  "series": [
    {
      "capability": "media.object.upload",
      "unit": "byte_hours",
      "quantity": 25165824
    },
    {
      "capability": "media.object.read",
      "unit": "requests",
      "quantity": 340
    },
    {
      "capability": "media.object.read",
      "unit": "egress_bytes",
      "quantity": 8388608
    }
  ]
}
Rejected: unknown-unit
{
  "zone_id": "zon_01K2A9C3D5E7F9G1H3J5K7M9N1",
  "ovrn": "ovrn:zone:prj_01JZQ3V8X5N7K2M4P6R8T0W2Y4:object-zone/zon_01K2A9C3D5E7F9G1H3J5K7M9N1",
  "current": {
    "stored_bytes": 1048576,
    "objects": 12,
    "as_of": "2026-10-02T10:00:00Z"
  },
  "window_start": "2026-10-01T00:00:00Z",
  "window_end": "2026-10-02T10:00:00Z",
  "series": [
    {
      "capability": "media.object.read",
      "unit": "gigabytes",
      "quantity": 1
    }
  ]
}
Rejected: zone-counted-capability
{
  "zone_id": "zon_01K2A9C3D5E7F9G1H3J5K7M9N1",
  "ovrn": "ovrn:zone:prj_01JZQ3V8X5N7K2M4P6R8T0W2Y4:object-zone/zon_01K2A9C3D5E7F9G1H3J5K7M9N1",
  "current": {
    "stored_bytes": 1048576,
    "objects": 12,
    "as_of": "2026-10-02T10:00:00Z"
  },
  "window_start": "2026-10-01T00:00:00Z",
  "window_end": "2026-10-02T10:00:00Z",
  "series": [
    {
      "capability": "zone.zone.create",
      "unit": "requests",
      "quantity": 1
    }
  ]
}

Validate

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