Getting started

Audience: developers · Read route: apply

This page gets you from nothing to a mapped-out connection to the base protocol: pick an exchange pattern, agree a taxonomy, and decide where your runtime lives. It is a conceptual on-ramp, so you can follow it without having read How it works first, though that page explains the shape in more depth.

Status: the specification and the exchange patterns are live; the test vectors and reference implementation land alongside v0.1. Everything up to running code is here, and until the vectors ship this stays a conceptual on-ramp.

What you need

• An understanding of the base protocol shape: how a record is structured, how parties are addressed, and how each exchange is anchored and verified. How it works covers this conceptually, and the base protocol specification carries the rules.
• The open standards it rests on. Addressing and discovery use the open overlay standards; key derivation uses an open, published key-derivation standard; identity uses the open W3C DID and Verifiable Credentials standards. You follow each published standard directly, so no part of interoperability is proprietary.
• A decision about where your runtime lives: whether you run your own node or use a managed provider. That is the third of the choices below.

The choices you make

Choose an exchange pattern

Start from a pattern rather than designing an exchange from scratch. Five reusable configuration templates are documented at /patterns:

• one-to-many: one producer pushes a verifiable record to a bounded, named set of recipients.
• broadcast: one producer publishes to an open topic that any admitted party reads.
• on-demand: a recipient pulls a specific record when it is needed and verifies it at read time.
• request-response: a requester asks a bounded question and receives a bounded answer without the underlying data being shared.
• cross-sector: parties in different sectors exchange verifiable references across a domain boundary, each verifying independently.

Each pattern page carries a copyable configuration. A one-to-many configuration looks like this:

pattern: one-to-many
protocol_version: "0.1"
exchange:
  topology: one-to-many
  participants:
    - public-body
    - verifier
    - retailer
  admission: invited
delivery:
  mode: push
  ordering: per-topic
payload:
  encryption: field-level
  disclosure: selective
audit:
  anchor: public-audit-layer
  proof: per-record

On the built site this block carries a copy control and is marked translate="no", so machine translation leaves the configuration intact.

Choose or start a taxonomy

The base protocol fixes how data is shared, not what is shared. What a field means is a per-domain agreement that sits above the base layer as a light convention, not a new layer of its own. Reuse an existing domain protocol, for example content authenticity or fraud-signal sharing under /protocols, or start a new per-domain agreement above the base layer for your own field of work.

Run a node or choose a provider

Either run your own runtime or use a managed provider. If you run your own, the reference section documents the topologies you can configure, full, query-replica, ingest-only, and observer, each an adapter swap over the same code path. If you would rather not operate the infrastructure, a provider can operate a conforming implementation on your behalf. Both routes speak the same protocol, so the choice does not affect interoperability and you can move between them.

How to build against the specification

Conformance is defined against the published rules and the named test-vector suites, never against any single implementation. Section 6 of the specification at /protocols/data-sharing/v0.1 lists what an implementation must demonstrate and names each test-vector suite. The suites and the port-contract interfaces will be published alongside the reference implementation, at /protocols/data-sharing/v0.1/vectors and /protocols/data-sharing/v0.1/interfaces. Until they are published, the specification fixes the shape an implementation must match, and the vectors will pin the exact bytes.

A rebuilder starts there: read the conformance section, implement the reader, writer, and recorder interfaces, and validate output against the suites once they are available.

Next steps

How it works for the concepts, the specification for the rules, and the reference for the runtime detail.