Creating and publishing the network manifest
This guide explains how a Network Facilitator Organization (NFO) can create, publish, and maintain a network manifest for an NFH fabric network.
Guide for NFOs - Creating & Publishing Network Manifest
This guide explains how a Network Facilitator Organization (NFO) can create, publish, and maintain a network manifest for an NFH fabric network. The manifest is the control document for a given networkId and allows the NFO to publish network-level configuration in a discoverable, versioned, and verifiable way.
1. Overview
In NFH fabric, the networkId is tied to a specific registry maintained by the NFO. That registry represents the network boundary and acts as the network's root of trust. The network manifest is a signed YAML document associated with that registry and serves as the main release document for network-level configuration.
Participants can use the manifest to discover:
which policies apply to the network
where those policy artifacts are hosted
whether observability is enabled
where telemetry configuration and collector endpoints are defined
The manifest itself can be hosted by the NFO at any stable URL. The URL and signature metadata are then published as metadata on the NFO's network registry, allowing participants to resolve the current network configuration for that networkId.
2. Where the manifest is referenced
The NFO should attach manifest-related metadata to the network registry on DeDi Global. This allows participants and ONIX instances to discover the manifest for a specific networkId.
The registry metadata should contain:
manifestUrl
URL of the network manifest file
manifestSignatureUrl
URL of the detached signature for the manifest
signingPublicKeyLookupUrl
Lookup URL of the public key used to verify the manifest signature
The signing public key referenced here should be retrievable through the registry lookup URL so that participants can verify the authenticity and integrity of the manifest.
3. Relationship between registry and network ID
The networkId is formed from:
For example:
This means each network registry has its own manifest and its own network configuration. In practice, NFOs usually maintain separate registries and manifest for each environment boundary they are defining using their registries.
4. Manifest structure
The manifest is a YAML document for a specific network release. A typical manifest looks like this:
5. Top-level fields
manifestVersion
Yes
Version of the manifest schema
manifestType
Yes
Must be network-manifest
networkId
Yes
Network the manifest applies to
releaseId
Yes
Release identifier for this manifest version
publisher
Yes
Publisher identity information
policies
No
Policy distribution and evaluation configuration
observability
No
Telemetry and observability configuration
governance
Yes
Validity period and signature state
Publisher
role
Yes
Publisher role, typically NFO
domain
Yes
Domain representing the publisher
6. Defining policies in the manifest
The manifest can point to network policies written in Rego. Policies may be distributed either as:
an OPA bundle
a single Rego file
The policies section must declare the source format and the evaluation query path.
Policy section rules
type must currently be rego
source must be either bundle or file
exactly one of bundle or file must be present
Example using an OPA bundle
Example using a single Rego file
The policyQueryPath field should point to the decision rule that participants evaluate for that policy artifact.
7. Creating and publishing policy artifacts
Detailed guidance for policy authors, including the expected policy output contract, repository structure, build steps, signing flow, testing process, and publication of the final artifact, is covered in the separate guide: Creating and publishing Rego policy artifacts.
In the manifest, the NFO only needs to reference the final published artifact using the appropriate bundle or file section.
8. Defining observability in the manifest
The manifest can also define network observability settings. This allows the NFO to standardize what telemetry participants emit and where that telemetry is sent as part of the network release.
Observability fields
observability.enabled
Yes
Enables observability when true
observability.config.url
Conditional
URL of the observability config document
observability.config.signed
Conditional
Whether the config is signed
observability.config.signatureUrl
Conditional
Detached signature URL when signed
observability.config.signingPublicKeyId
Conditional
Key identifier used for verification
observability.collector.url
Conditional
Endpoint receiving telemetry events
Example
The observability config document can describe required and optional telemetry fields or other network-wide telemetry rules. Participants should verify the configuration before using it. Please refer the observability guide for the understanding the config.url parameter and how observability can be set up in ONIX.
9. Governance section
The governance section defines the validity window of the manifest.
Example:
Governance rules
effectiveFrom defines when the manifest becomes active
if effectiveUntil is present, it must be later than effectiveFrom
once the current time passes effectiveUntil, the manifest should be treated as expired
if the manifest is signed, the detached signature and key lookup information must be available through registry metadata
10. Suggested publishing workflow
Use this sequence when publishing or updating a manifest:
Create or update policy artifacts.
Create or update observability configuration if required.
Publish all referenced files at stable URLs.
Create the manifest YAML for the target networkId.
Sign the manifest. You can use this guide to sign the manifest file.
Publish the manifest and detached signature.
Update the NFO registry metadata with manifestUrl, manifestSignatureUrl, and signingPublicKeyLookupUrl.
Roll out the new release and communicate the new releaseId to participants if needed.
11. Operational recommendations
version releases clearly using releaseId
keep artifact URLs stable and preferably immutable
test policies before publishing them into production manifests
avoid mixing unrelated policy changes and observability changes in one release unless necessary
ensure registry metadata always points to the currently intended manifest for that network
The manifest is the NFO's main distribution mechanism for network-level configuration. Treat it as a versioned, signed contract between the NFO and all participants operating on that networkId.
Last updated
Was this helpful?