Adapter Manifest v1

Accepted

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

For background on what a Manifest is, see Concepts → Manifest and Concepts → Adapter.

Top-Level Structure

{
  "manifest_version": "adapter-manifest/v1",
  "identity": { ... },
  "category": "...",
  "capabilities": [ ... ],
  "interface_contracts": [ ... ],
  "compatibility": { ... },
  "dependencies": { ... },
  "provenance": { ... },
  "integration": { ... },
  "lifecycle": { ... }
}

Section: `manifest_version`

Required string. Always "adapter-manifest/v1" for the v1 schema. Future versions will use "adapter-manifest/v2", etc.

Section: `identity`

{
  "identity": {
    "id": "adapter:java/spring-data-jpa",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "version": "3.2.4",
    "display_name": "Spring Data JPA",
    "language": "java",
    "slice": "java-backend",
    "homepage": "https://spring.io/projects/spring-data-jpa",
    "source": {
      "type": "maven",
      "group_id": "org.springframework.data",
      "artifact_id": "spring-data-jpa",
      "repository": "https://repo.maven.apache.org/maven2"
    }
  }
}

Field	Type	Required	Notes
`id`	string	yes	Namespaced slug (`adapter:<slice>/<name>`)
`uuid`	UUIDv4	yes	Immutable, assigned at admission
`version`	semver	yes	Matches underlying library version
`display_name`	string	yes	Human-readable name
`language`	string	yes	Primary language: `java`, `typescript`, `python`, `polyglot`, `none`
`slice`	string	yes	Library slice (`java-backend`, `ts-frontend`, etc.)
`homepage`	URL	no	Upstream project page
`source`	object	yes	How to fetch the artifact

`source.type` values

maven — Java/JVM artifacts; requires group_id, artifact_id, repository
npm — JavaScript/TypeScript packages; requires package_name, registry
pypi — Python packages; requires package_name, index_url
oci — Container images; requires image, registry
git — Git-based source; requires repository, ref
binary — Released binaries; requires url, checksum

Section: `category`

Required string. The broad category this Adapter fills. Drawn from the categories defined in the Capability namespace registry. Examples: persistence, auth, messaging, observability, web-framework, llm-provider, vector-db.

Section: `capabilities`

Required array. Each capability the Adapter provides:

{
  "capabilities": [
    { "id": "capability:persistence/crud/v1" },
    {
      "id": "capability:persistence/transactions/v1",
      "modes": ["jta", "local"]
    },
    {
      "id": "capability:persistence/pagination/v1",
      "styles": ["offset", "cursor"]
    }
  ]
}

Sub-fields (modes, styles, etc.) are defined per-Capability in the Capability registry.

Section: `interface_contracts`

Required array (may be empty for Adapters that don’t expose a consumer interface). Each Contract the Adapter implements:

{
  "interface_contracts": [
    {
      "contract_id": "contract:persistence/repository/v1",
      "binding": "java",
      "concrete_pattern": "interface {EntityName}Repository extends JpaRepository<{EntityName}, {IdType}>"
    }
  ]
}

Field	Type	Required	Notes
`contract_id`	string	yes	Namespaced Contract slug
`binding`	string	yes	Language binding: `java`, `typescript`, `python`, `polyglot`
`concrete_pattern`	string	yes	Code shape this Adapter exposes for the Contract

Section: `compatibility`

{
  "compatibility": {
    "language_runtime": {
      "java": ">=17,<22"
    },
    "scaffolder_versions": {
      "jhipster": ">=8.0.0,<9.0.0"
    },
    "requires_adapters": [
      {
        "category": "persistence_driver",
        "capability": "capability:persistence/jdbc/v1"
      }
    ],
    "compatible_with": [
      { "adapter_id": "adapter:java/spring-boot", "version_range": ">=3.0.0,<4.0.0" }
    ],
    "incompatible_with": [
      {
        "adapter_id": "adapter:java/mybatis",
        "reason": "alternative persistence approach; do not combine"
      }
    ],
    "known_good_combinations": [
      {
        "label": "Spring Boot 3.2 LTS stack",
        "adapters": {
          "adapter:java/spring-boot": "3.2.4",
          "adapter:java/hibernate-orm": "6.4.4",
          "adapter:infra/postgresql": "16"
        }
      }
    ]
  }
}

All sub-fields optional except where context demands them. The Compatibility Validator walks these declarations during the Compatibility Validation stage.

Section: `dependencies`

{
  "dependencies": {
    "transitive_artifacts": "managed_by_source_system",
    "system_dependencies": [
      { "type": "jvm", "version": ">=17" }
    ],
    "runtime_services": [
      {
        "type": "database",
        "category": "sql",
        "supported": ["postgresql", "mysql", "h2"],
        "default": "postgresql"
      }
    ],
    "configuration_required": [
      "spring.datasource.url",
      "spring.datasource.username",
      "spring.datasource.password",
      "spring.jpa.hibernate.ddl-auto"
    ]
  }
}

Field	Notes
`transitive_artifacts`	`"managed_by_source_system"` means Maven/npm/etc. handles it; otherwise list explicitly
`system_dependencies`	OS-level dependencies (JVM version, native libraries)
`runtime_services`	Other Adapters or services required at runtime
`configuration_required`	Config keys the user/Archetype must provide

Section: `provenance`

{
  "provenance": {
    "license": {
      "spdx": "Apache-2.0",
      "verified": true,
      "verified_at": "2025-11-15T00:00:00Z"
    },
    "source_repository": "https://github.com/spring-projects/spring-data-jpa",
    "maintainer_organization": "VMware/Broadcom",
    "is_official": true,
    "release_signature": {
      "type": "pgp",
      "key_id": "...",
      "verified": true
    },
    "security": {
      "cve_check": {
        "last_run": "2026-06-08T00:00:00Z",
        "scanner": "trivy",
        "result": "clean",
        "advisory_url": null
      },
      "sbom_available": true,
      "sbom_format": "cyclonedx-1.5"
    },
    "audit_trail": [
      {
        "event": "admitted_to_library",
        "timestamp": "2025-11-15T00:00:00Z",
        "method": "human_reviewed",
        "reviewer_id": "..."
      }
    ]
  }
}

All provenance fields required for production Adapters. License and security must be mechanically verified.

Section: `integration`

{
  "integration": {
    "imports": [
      "org.springframework.data.jpa.repository.JpaRepository",
      "org.springframework.stereotype.Repository"
    ],
    "build_dependency_snippet": {
      "maven": "<dependency>\n  <groupId>org.springframework.data</groupId>\n  <artifactId>spring-data-jpa</artifactId>\n</dependency>",
      "gradle": "implementation 'org.springframework.data:spring-data-jpa'"
    },
    "minimal_config_snippet": "# application.yml\nspring:\n  datasource:\n    url: ${DATABASE_URL}",
    "typical_usage_pattern": "@Repository\npublic interface {EntityName}Repository extends JpaRepository<{EntityName}, Long> {}",
    "common_pitfalls": [
      "Lazy loading outside transaction boundaries causes LazyInitializationException",
      "N+1 query problem with default fetch strategy"
    ]
  }
}

The Stitcher reads these fields to know how to write integration code consuming this Adapter.

Section: `lifecycle`

{
  "lifecycle": {
    "status": "active",
    "added_at": "2025-11-15",
    "last_verified": "2026-06-08",
    "deprecation": null,
    "successor_adapter": null,
    "previous_slugs": [],
    "maintenance_signals": {
      "last_upstream_release": "2024-03-15",
      "github_stars": 2900,
      "github_last_commit_days": 12,
      "open_issues_count": 87,
      "release_cadence_days": 90
    }
  }
}

`status` values
`experimental` — recently admitted, limited use
`active` — production-ready
`deprecated` — discouraged, scheduled for removal
`superseded` — replaced by `successor_adapter`
`archived` — no longer available for new builds

Schema File

The machine-readable JSON Schema is at schemas/adapter-manifest-v1.schema.json in the platform’s central registry. Validation tooling references that file.

Concepts → Manifest
Concepts → Adapter
Schemas → Module Manifest v1
ADR-0006: JSON Canonical Format
ADR-0010: Semver and Compatibility Matrix Versioning
ADR-0020: Manifest Schema Versioning

Adapter Manifest v1

Top-Level Structure

Section: manifest_version

Section: identity

source.type values

Section: category

Section: capabilities

Section: interface_contracts

Section: compatibility

Section: dependencies

Section: provenance

Section: integration

Section: lifecycle