ConnectionPoint
Fields
This section documents version 2 of the definition (_v is the constant "2"). The definition has one table per form listing the field name, its JSON type, whether it is required, and what it means.
Object model
A connection point is where a thing can be dialed: the endpoint a consumer connects to in order to fetch a catalog record, poll a curated list or reach a store. It is the one definition the other schemas leave opaque on purpose: they pin a cxn-pt or cxn-pts field to "a string or an object" and leave the shape to this schema, because iface-gen embeds one schema per header.
A connection point is attribution and a way back, never authority. An address says where content was served from and where to re-fetch it; the content itself still verifies at the product level.
| Definition | Purpose |
|---|---|
|
One endpoint, in one of two forms: a URL string, or an object of |
The schema publishes one standalone entry point, for validators that embed one schema per header:
$id (under https://root-interface.se/protocols/Definitions/) |
Resolves to |
|---|---|
|
|
connection-point
A oneOf of two forms. A value validates as exactly one of them; both carry the same three parts.
| Form | Type | Shape |
|---|---|---|
string |
A URL, |
|
object |
The same three parts as separate fields. |
Consumers normalise both forms to the triple (protocol, host, port) before use. The object form is the explicit one; the string form is the one a human writes.
String form
The schema does not constrain the string. A consumer parses it as a URL: the scheme becomes the protocol, the host the address and the port, if present, the port. A string without a port yields an empty port; whether that is acceptable is the consumer’s affair. The discovery service, for one, rejects a registration whose connection point yields no numeric port.
"https://store.example.se:8823"
Object form
| Field | Type | Required | Description |
|---|---|---|---|
|
string |
yes |
What to dial with: a wire spelling such as |
|
string |
yes |
The host: a DNS name or an IP literal, and nothing else. The port is its own field, so consumers reject an address carrying userinfo or a path. |
|
string or integer |
yes |
The port, accepted as either JSON type. Consumers normalise an integer to its decimal string. |
{ "protocol": "https", "address": "store.example.se", "port": 8823 }
All three fields are required: an object missing any of them fails this definition. The authored-empty {} that InstallSpec describes as the secure default for observable.cxn-pt passes InstallSpec, which does not constrain the field, but it is not a connection point under this definition. It is a placeholder the serving store fills in at serve time.
Schema
{
"$id": "https://root-interface.se/protocols/Definitions/ConnectionPoint",
"$schema": "https://json-schema.org/draft/2019-09/schema",
"schemas": {
"https://root-interface.se/protocols/Definitions/connection-point": {
"$id": "https://root-interface.se/protocols/Definitions/connection-point",
"$schema": "https://json-schema.org/draft/2019-09/schema",
"definitions": {
"_v": {
"const": "2"
},
"connection-point": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"required": [
"protocol",
"address",
"port"
],
"properties": {
"protocol": {
"type": "string"
},
"address": {
"type": "string"
},
"port": {
"type": [
"string",
"integer"
]
}
}
}
]
}
}
},
"https://root-interface.se/protocols/Definitions/ConnectionPoint": {
"$id": "https://root-interface.se/protocols/Definitions/ConnectionPoint",
"$schema": "https://json-schema.org/draft/2019-09/schema",
"$ref": "connection-point#/definitions/connection-point"
}
}
}
Related schemas
This definition is referenced loosely from every schema that carries an endpoint. Each pins the field to a string or an object and leaves validation to this schema.
| Field | Schema | Role |
|---|---|---|
|
Where to fetch a referenced product or bundle: the shape of a curated-list entry. |
|
|
The store endpoint an |
|
|
|
The endpoint a store registers with the discovery service, and what the service hands back to a consumer that queries it. Pinned to the object form there. |
|
|
The serving store’s own connection points, stamped onto a result at serve time: attribution and a way back, never authority. |
|
The transport capability a participant announces: the same wire spellings as |
|
|
The sibling notion, not a connection point: a hyperport is a place a user goes to in a subverse, a connection point an endpoint a consumer dials. |