--- title: "network.link@1 · OpenVibe.Services" canonical: "https://openvibe.services/docs/contracts/network.link" updated: null --- # network.link@1 · OpenVibe.Services HTML: [network.link@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/network.link) # NetworkLink `network.link@1` Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.161.0). - Version: 1.0.0 - Owner: network - Visibility: public - Status: active - Compatibility: backward - Decision: [ADR-034](/docs/adr/ADR-034) - Schema: [`https://openvibe.network/contracts/network/link.v1.json`](/docs/contracts/network.link.json) network.link@1: one machine of the OpenVibe platform as the node registry lists it (ADR-034 section 12; roadmap WS-X1). Roles are what it serves; location is region-level; the beacon is an HTTPS URL a client times to measure its own round trip. No addresses, capacity or secrets are public: a node is found by role and location, and reached through the service that uses it. ## Fields | Field | Type | Required | Description | Constraints | | --- | --- | --- | --- | --- | | `id` | string | yes | | - `pattern ^[a-z][a-z0-9-]{1,39}$` | | `name` | string | | | - `maxLength 80` | | `roles` | array of enum | yes | | - `minItems 1`
- `unique items`
- `items: one of "web", "app", "data", "media-worker", "ingest", "edge-probe", "edge-relay", "edge-cache", "gpu", "staging", "ci"` | | `location` | object | yes | | - `no other fields` | | `location.region` | string | yes | e.g. us-west, eu-central | - `pattern ^[a-z]{2}-[a-z]+(-[0-9])?$` | | `location.country` | string | yes | | - `pattern ^[A-Z]{2}$` | | `location.city` | string | | | - `maxLength 80` | | `location.lat` | number | | | - `minimum -90`
- `maximum 90` | | `location.lon` | number | | | - `minimum -180`
- `maximum 180` | | `provider` | string | | | - `maxLength 40` | | `beacon` | string | | Timed by clients (GET, tiny body, no caching) to measure round-trip time. | - `pattern ^https://`
- `format uri` | | `health` | object | yes | | - `no other fields` | | `health.status` | enum | yes | | - `one of "up", "degraded", "down", "unknown"` | | `health.checked_at` | string | yes | | - `format date-time` | | `updated_at` | string | yes | | - `format date-time` | | `cell` | string | | Cell the node belongs to, e.g. wnam-1. | - `pattern ^[a-z]{2,8}-[0-9]{1,3}$` | ## Examples From the contract's own test fixtures: valid ones validate, rejected ones must fail. Valid: minimal-edge ~~~~ { "id": "probe-fra", "roles": [ "edge-probe", "edge-relay" ], "location": { "region": "eu-central", "country": "DE" }, "health": { "status": "unknown", "checked_at": "2026-09-28T12:00:00Z" }, "updated_at": "2026-09-28T12:00:00Z" } ~~~~ Valid: oregon ~~~~ { "id": "oregon-1", "name": "Oregon 1", "roles": [ "web", "app", "data", "ingest" ], "location": { "region": "us-west", "country": "US", "city": "Hillsboro", "lat": 45.52, "lon": -122.99 }, "provider": "ovh", "beacon": "https://openvibe.network/api/v1/links/oregon-1/beacon", "health": { "status": "up", "checked_at": "2026-09-28T12:00:00Z" }, "updated_at": "2026-09-28T12:00:00Z" } ~~~~ Valid: with-cell ~~~~ { "id": "oregon-1", "name": "Oregon 1", "roles": [ "web", "app", "data", "ingest" ], "location": { "region": "us-west", "country": "US", "city": "Hillsboro", "lat": 45.52, "lon": -122.99 }, "provider": "ovh", "beacon": "https://openvibe.network/api/v1/links/oregon-1/beacon", "health": { "status": "up", "checked_at": "2026-09-28T12:00:00Z" }, "updated_at": "2026-09-28T12:00:00Z", "cell": "wnam-1" } ~~~~ Rejected: bad-cell ~~~~ { "id": "oregon-1", "name": "Oregon 1", "roles": [ "web", "app", "data", "ingest" ], "location": { "region": "us-west", "country": "US", "city": "Hillsboro", "lat": 45.52, "lon": -122.99 }, "provider": "ovh", "beacon": "https://openvibe.network/api/v1/links/oregon-1/beacon", "health": { "status": "up", "checked_at": "2026-09-28T12:00:00Z" }, "updated_at": "2026-09-28T12:00:00Z", "cell": "WNAM_1" } ~~~~ Rejected: bad-country ~~~~ { "id": "oregon-1", "name": "Oregon 1", "roles": [ "web", "app", "data", "ingest" ], "location": { "region": "us-west", "country": "usa", "city": "Hillsboro", "lat": 45.52, "lon": -122.99 }, "provider": "ovh", "beacon": "https://openvibe.network/api/v1/links/oregon-1/beacon", "health": { "status": "up", "checked_at": "2026-09-28T12:00:00Z" }, "updated_at": "2026-09-28T12:00:00Z" } ~~~~ Rejected: plain-http-beacon ~~~~ { "id": "oregon-1", "name": "Oregon 1", "roles": [ "web", "app", "data", "ingest" ], "location": { "region": "us-west", "country": "US", "city": "Hillsboro", "lat": 45.52, "lon": -122.99 }, "provider": "ovh", "beacon": "http://openvibe.network/api/v1/links/oregon-1/beacon", "health": { "status": "up", "checked_at": "2026-09-28T12:00:00Z" }, "updated_at": "2026-09-28T12:00:00Z" } ~~~~ Rejected: public-address ~~~~ { "id": "oregon-1", "name": "Oregon 1", "roles": [ "web", "app", "data", "ingest" ], "location": { "region": "us-west", "country": "US", "city": "Hillsboro", "lat": 45.52, "lon": -122.99 }, "address": "15.204.79.215", "beacon": "https://openvibe.network/api/v1/links/oregon-1/beacon", "health": { "status": "up", "checked_at": "2026-09-28T12:00:00Z" }, "updated_at": "2026-09-28T12:00:00Z" } ~~~~ Rejected: unknown-role ~~~~ { "id": "oregon-1", "name": "Oregon 1", "roles": [ "mainframe", "app", "data", "ingest" ], "location": { "region": "us-west", "country": "US", "city": "Hillsboro", "lat": 45.52, "lon": -122.99 }, "provider": "ovh", "beacon": "https://openvibe.network/api/v1/links/oregon-1/beacon", "health": { "status": "up", "checked_at": "2026-09-28T12:00:00Z" }, "updated_at": "2026-09-28T12:00:00Z" } ~~~~ ## Validate ~~~~ const contracts = require('openvibe-contracts'); contracts.validate('network.link@1', value); // { valid, errors: [{ path, message }] } ~~~~