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

connection-point

One endpoint, in one of two forms: a URL string, or an object of protocol, address and port.

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

ConnectionPoint

connection-point#/definitions/connection-point

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

string

A URL, protocol://address:port. The scheme is the protocol, the host the address, and the port, if any, the port.

object

object

The same three parts as separate fields. address is a bare host.

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

protocol

string

yes

What to dial with: a wire spelling such as https or ipsme+tcp+l4end, the same vocabulary a participant announces under the Discovery protocols capability (see Related schemas). The schema does not enumerate it.

address

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.

port

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"
    }
  }
}

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

ref-pnb.cxn-pts[]

schema_ProductsAndBundles

Where to fetch a referenced product or bundle: the shape of a curated-list entry.

observable.cxn-pt

schema_InstallSpec

The store endpoint an observable install polls for a curated list.

registration.cxn-pt, discovered[].cxn-pt

schema_Discovery-svc

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.

_origin[]

schema_1Store

The serving store’s own connection points, stamped onto a result at serve time: attribution and a way back, never authority.

protocols.protocols[]

schema_Discovery

The transport capability a participant announces: the same wire spellings as protocol here.

hyperport

schema_Discovery

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.