Underpost Build Manifest

Relation Type

https://underpost.net/rel/build-manifest

Status

Active

Purpose

This extension relation type identifies the Underpost Build Manifest associated with a web application document.

The relation connects the current HTML document with the machine-readable build manifest used to describe the build identity and common bootstrap configuration of the application.

Discovery

The relation is expressed in HTML using:

<link
  rel="https://underpost.net/rel/build-manifest"
  href="/underpost.manifest"
  type="application/json">

The href identifies the Build Manifest resource.

The relation type itself is a Web Linking extension relation type (RFC 8288). The relation URI is also the location of this specification.

Resource

The target resource is an Underpost Build Manifest.

Default path:

/underpost.manifest

When an application is mounted under a non-root base path, the manifest resource is relative to that application base path.

Examples:

/underpost.manifest
/test/underpost.manifest

Media Type

The Build Manifest is represented as:

application/json

Semantic Definition

The Underpost Build Manifest describes the build-level identity and common bootstrap parameters required by the generated application.

• It is not a Web App Manifest.
• It is not request-specific state.
• It is not user session state.
• It is not authorization data.
• It is not a replacement for page-level SSR metadata.

The manifest describes the application build and the common runtime bootstrap information associated with that build.

Canonical Representation

The application generates one canonical Build Manifest object. The same semantic object may be represented in two forms:

1. External resource: /underpost.manifest
2. Inline SSR bootstrap payload:

   <script type="application/json" id="underpost-build-manifest">
     ...
   </script>

The external and inline representations MUST describe the same build manifest.

Build Identity

The manifest SHOULD contain a stable build identity. Example:

{
  "schema": 1,
  "application": "underpost",
  "version": "v3.4.5",
  "build": { "id": "example-build-id", "mode": "production" },
  "runtime": {
    "basePath": "/",
    "apiBasePath": "api/v1"
  }
}

Schema

The top-level schema field identifies the Build Manifest schema version.

The schema version changes when the structure or semantics of the manifest change in a way that requires consumers to interpret the representation differently.

Build Metadata

Build metadata MAY include public information such as:

• application name;
• application version;
• build identity;
• source/repository information intended for public release metadata;
• documentation or coverage references intended for public consumption;
• other non-sensitive build information.

Runtime Bootstrap

The runtime section MAY contain common bootstrap parameters generated for the built application. Examples:

• API base path;
• API proxy path;
• API host mappings;
• other non-sensitive values required by the application bootstrap.

Security

The Build Manifest is publicly accessible application metadata. It MUST NOT contain:

• passwords;
• authentication tokens;
• private keys;
• Git credentials;
• infrastructure credentials;
• SOPS/Age secrets;
• private environment values;
• other confidential information.

Client Bootstrap

The generated client SHOULD use the inline SSR Build Manifest for initial bootstrap when it is present.

The external /underpost.manifest resource MAY be used for discovery, inspection, tooling, or fallback retrieval.

The initial application bootstrap SHOULD NOT require an additional network request when the same manifest is already present in the SSR document.

Relationship to SSR

The Build Manifest is build-level metadata. Page-specific SSR data remains part of the generated HTML document and is not required to be exposed through the Build Manifest.

Examples of information that do not belong in the Build Manifest include:

• page title;
• page description;
• Open Graph metadata;
• current user/session data;
• page-specific application data.

Relationship to the Web App Manifest

This relation MUST NOT be confused with the registered HTML link relation manifest.

The Underpost Build Manifest uses https://underpost.net/rel/build-manifest and /underpost.manifest because it represents Underpost build metadata rather than a Web App Manifest.

Versioning

The Build Manifest schema is versioned independently from the relation URI.

The relation URI identifies the semantic relationship. The schema field identifies the machine-readable manifest structure.

Backward-incompatible changes to the manifest representation require a schema version change.

Availability

The relation specification SHOULD remain publicly accessible at https://underpost.net/rel/build-manifest.

The Build Manifest itself is discovered through the HTML link target.

The relation specification does not need to be fetched by clients during normal application startup.

Example

HTML:

<link
  rel="https://underpost.net/rel/build-manifest"
  href="/underpost.manifest"
  type="application/json">

Manifest:

{
  "schema": 1,
  "application": "underpost",
  "version": "v3.4.5",
  "build": { "id": "example-build-id", "mode": "production" },
  "runtime": {
    "basePath": "/",
    "apiBasePath": "api/v1"
  }
}