Skip to content
Almathal Handbook

Archetype Spec v1

Accepted

This document is the formal schema for the Archetype Spec, version 1. Both the Archetype definition (template) and the resolved Spec (specific build configuration) follow this schema, with the resolved Spec including additional populated fields.

For background, see Concepts → Archetype and Concepts → Spec.

Top-Level Structure

{
  "schema_version": "archetype-spec/v1",
  "archetype": { ... },
  "scaffolders": [ ... ],
  "adapter_slots": [ ... ],
  "module_slots": [ ... ],
  "variation_points": [ ... ],
  "seams": [ ... ],
  "sanity_checks": { ... },
  "fallback": { ... }
}

A resolved Spec additionally contains:

{
  "spec_id": "...",
  "approval": { ... }
}

Section: schema_version

Required string. Always "archetype-spec/v1" for the v1 schema.

Section: archetype

{
  "archetype": {
    "id": "archetype:internal-crud-admin",
    "uuid": "f1e2d3c4-...",
    "version": "0.1.0",
    "display_name": "Internal CRUD Admin Tool",
    "description": "Java backend + React frontend for managing business entities",
    "compatible_with": {
      "platform_version": ">=0.1.0,<1.0.0"
    }
  }
}

Section: scaffolders

Which Scaffolders to invoke:

{
  "scaffolders": [
    {
      "id": "scaffolder:jhipster",
      "version_constraint": ">=8.0.0",
      "config_mapping": {
        "applicationType": "monolith",
        "authenticationType": "jwt",
        "databaseType": "sql",
        "prodDatabaseType": "{{ variation.database }}",
        "clientFramework": "react"
      }
    }
  ]
}

The {{ variation.X }} template syntax interpolates Variation Point values at resolution time.

Section: adapter_slots

{
  "adapter_slots": [
    {
      "slot_id": "slot:internal-crud-admin/persistence-primary",
      "category": "persistence",
      "default": "adapter:java/spring-data-jpa",
      "alternatives": ["adapter:java/jooq", "adapter:java/mybatis"],
      "interface_contract": "contract:persistence/repository/v1",
      "required_capabilities": [
        "capability:persistence/crud/v1",
        "capability:persistence/transactions/v1"
      ]
    }
  ]
}
FieldRequiredNotes
slot_idyesNamespaced (slot:<archetype>/<name>)
categoryyesBroad Adapter category
defaultyesDefault Adapter slug if user doesn’t override
alternativesnoPre-vetted user-selectable alternatives
interface_contractnoRequired Contract; enables substitution
required_capabilitiesnoRequired Capabilities; filters Adapter candidates

In a resolved Spec, each slot also has a selected field with the chosen Adapter and version, plus the resolved UUID.

Section: module_slots

Same structure as adapter_slots, but for Modules:

{
  "module_slots": [
    {
      "slot_id": "slot:internal-crud-admin/auth",
      "category": "auth",
      "default": "module:auth/jwt-with-rbac",
      "alternatives": ["module:auth/oauth2-with-rbac"]
    }
  ]
}

Section: variation_points

User-configurable choices:

{
  "variation_points": [
    {
      "id": "database",
      "type": "enum",
      "options": ["postgresql", "mysql"],
      "default": "postgresql",
      "ui_label": "Primary Database",
      "ui_help": "PostgreSQL recommended for JSON-heavy workloads."
    },
    {
      "id": "entities",
      "type": "user_defined_list",
      "schema_ref": "#/definitions/entity",
      "min": 1,
      "ui_label": "Business Entities"
    }
  ]
}
type values
enum — pick from options
string — free text with optional pattern
integer — number with min/max
boolean — yes/no
user_defined_list — array of objects matching a schema
multi_select — multiple from options

In a resolved Spec, variation point values are stored as a separate variation_point_values object.

Section: seams

Where the Stitcher must fill code:

{
  "seams": [
    {
      "seam_id": "seam:internal-crud-admin/entity-to-ui",
      "type": "code_generation",
      "description": "Generate React list and form views for each entity",
      "input": "variation.entities",
      "output_files": [
        {
          "path_template": "frontend/src/pages/{entity.name}List.tsx",
          "template_role": "list_view",
          "must_use_adapters": [
            "adapter:typescript/react",
            "adapter:typescript/tanstack-query",
            "adapter:typescript/shadcn"
          ],
          "must_implement": ["pagination", "filtering", "delete_action"]
        }
      ],
      "verification": {
        "compile": true,
        "lint": true,
        "tests_must_pass": ["frontend/smoke_test_entity_pages"]
      }
    }
  ]
}

See Concepts → Seam for the deeper treatment.

Section: sanity_checks

Configurable per-Archetype:

{
  "sanity_checks": {
    "compatibility": {
      "mode": "deterministic_matrix",
      "blocking": true
    },
    "build_approval": {
      "approval_required": true,
      "audit_trail": true
    },
    "seam_validation": {
      "blocking": true
    },
    "build_verification": {
      "compile": true,
      "lint": true,
      "tests": ["smoke_test_crud", "auth_flow_test"],
      "blocking": true
    },
    "output_review": {
      "ai_reviewer_model": "different_from_stitcher",
      "categories": ["anti_patterns", "security", "consistency"],
      "blocking": false
    }
  }
}

Section: fallback

What to do when this Spec doesn’t fully resolve:

{
  "fallback": {
    "on_unmatched_request": "pure_llm_with_warning",
    "log_for_archetype_evolution": true
  }
}

Per ADR-0013, MVP uses pure_llm_with_warning. V1 may add exploratory_path as an alternative.

Resolved-Spec-Only Fields

{
  "spec_id": "build-7a3f8c2e",
  "approval": {
    "approved_by": "user-12345",
    "approved_at": "2026-06-10T14:33:12Z",
    "summary_shown": "...",
    "user_edits_applied": []
  }
}

Reserved for V1

Future fields (declared in v1 schema as reserved, not yet implemented):

  • service_topology — for microservice Archetypes (ADR-0015)
  • multi_app_orchestration — same context
  • customer_template_ref — link to a saved customer template (ADR-0014)

Schema File

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