Skip to content
Almathal Handbook

Module Manifest v1

Draft

This document is the formal schema for the Module Manifest, version 1. Every Module in the Module Library is described by a JSON document conforming to this schema.

The Module Manifest shares most fields with the Adapter Manifest but differs in fields that reflect Modules’ composite nature.

Top-Level Structure

{
  "manifest_version": "module-manifest/v1",
  "identity": { ... },
  "category": "...",
  "capabilities": [ ... ],
  "interface_contracts": [ ... ],
  "constituent_adapters": [ ... ],
  "configuration_surface": [ ... ],
  "internal_seams": [ ... ],
  "compatibility": { ... },
  "provenance": { ... },
  "integration": { ... },
  "lifecycle": { ... }
}

Section: manifest_version

Required string. Always "module-manifest/v1" for the v1 schema.

Section: identity

{
  "identity": {
    "id": "module:auth/jwt-with-rbac",
    "uuid": "a1b2c3d4-...",
    "version": "1.0.0",
    "display_name": "JWT with RBAC Auth",
    "domain": "auth",
    "language_compatible": ["java", "polyglot"]
  }
}
FieldNotes
idNamespaced slug (module:<domain>/<name>)
domainBusiness domain (auth, payments, billing, observability, etc.)
language_compatibleWhich language slices this Module can be used with

No source field — Modules are platform-managed, not pulled from external registries.

Section: constituent_adapters

The Module’s most distinctive field. Lists the Adapters this Module composes:

{
  "constituent_adapters": [
    {
      "adapter_id": "adapter:java/spring-security",
      "version_constraint": ">=6.0.0,<7.0.0",
      "role": "framework",
      "required": true
    },
    {
      "adapter_id": "adapter:java/nimbus-jose-jwt",
      "version_constraint": ">=9.0.0,<10.0.0",
      "role": "jwt-handling",
      "required": true
    },
    {
      "adapter_id": "adapter:infra/keycloak",
      "version_constraint": ">=24.0.0",
      "role": "external-idp",
      "required": false
    }
  ]
}
FieldNotes
adapter_idThe constituent Adapter
version_constraintCompatible version range
roleThe role this Adapter plays in the Module’s composition
requiredIf false, the Adapter is included only when certain configuration is set

For Modules with provenance.composition_source: "upstream", this section may be absent or minimal — the upstream project handles its own composition.

Section: configuration_surface

What the Archetype must provide when using this Module:

{
  "configuration_surface": [
    {
      "key": "jwt_secret",
      "type": "secret",
      "required": true,
      "description": "Symmetric secret for JWT signing (rotate via env var)"
    },
    {
      "key": "token_expiry_seconds",
      "type": "integer",
      "default": 3600,
      "required": false
    },
    {
      "key": "rbac_roles",
      "type": "user_defined_list",
      "schema_ref": "#/definitions/role",
      "required": true
    }
  ]
}

The Archetype’s Spec Resolution maps the user’s Variation Point answers into the Module’s configuration surface.

Section: internal_seams

Some Modules have internal Seams — places where the Module’s composition includes custom integration code. These are filled once when the Module is composed and admitted, not on every generation:

{
  "internal_seams": [
    {
      "seam_id": "seam:module/auth-jwt/audit-log-bridge",
      "description": "Wires JWT auth events to the audit log Adapter",
      "filled": true,
      "fill_method": "human_reviewed"
    }
  ]
}

Internal Seams are usually absent for upstream-curated Modules.

Sections Shared with Adapter Manifest

The following sections follow the same structure as the Adapter Manifest:

  • category — broad category
  • capabilities — what the Module provides
  • interface_contracts — what the Module exposes
  • compatibility — with Archetypes, languages, scaffolders
  • provenance — with extended composition_source field
  • integration — how Archetypes consume the Module
  • lifecycle — status, audit trail

Extended provenance for Modules

{
  "provenance": {
    "composition_source": "platform-composed",
    "license": { ... },
    "audit_trail": [ ... ]
  }
}

composition_source values:

  • platform-composed — assembled from Adapters by the platform team
  • upstream — curated from an existing open-source modular project; an additional upstream_project field records the source

For upstream Modules, the license aggregates the upstream project’s license plus any platform-added integration code license.

Schema File

The machine-readable JSON Schema is at schemas/module-manifest-v1.schema.json in the platform’s central registry.

Status

This schema is draft. Refinements are expected as the first Modules are authored. The final v1 schema will be locked when the MVP’s first Module (likely an auth Module) is admitted.