Hub Configuration Schema

This document describes the YAML schema for AI Primitives Hub hub configuration files.

Overview

Hubs are centralized configurations that define bundle sources and profiles for teams or organizations. A hub configuration file allows you to share a curated set of sources and pre-configured profiles.

Schema Version

Current schema version: Based on JSON Schema draft-07

Root Structure

version: "1.0.0"
metadata:
  name: "My Hub"
  description: "Hub description"
  maintainer: "Team Name"
  updatedAt: "2025-01-15T10:00:00Z"
sources:
  - id: "source-1"
    type: "github"
    # ... source configuration
profiles:
  - id: "profile-1"
    name: "Profile Name"
    # ... profile configuration
configuration:
  autoSync: true
  # ... hub configuration
telemetry:
  elasticSearch:
    node: "https://..."
    # ... ES configuration

Required Fields

Field	Type	Description
version	string	Semantic version of the hub configuration format (e.g., "1.0.0")
metadata	object	Hub metadata and descriptive information
sources	array	List of bundle sources available in this hub

Metadata Object

The metadata object contains descriptive information about the hub.

Required Fields

Field	Type	Description
name	string	Human-readable name of the hub (1-100 characters)
description	string	Detailed description of the hub's purpose (1-500 characters)
maintainer	string	Name or identifier of the hub maintainer (1-100 characters)
updatedAt	string	ISO 8601 timestamp of last update

Optional Fields

Field	Type	Description
checksum	string	Integrity checksum (format: sha256:abc123... or sha512:abc123...)

Example

metadata:
  name: "Engineering Team Hub"
  description: "Curated prompt bundles for the engineering team"
  maintainer: "Platform Team"
  updatedAt: "2025-01-15T10:30:00Z"
  checksum: "sha256:abc123def456..."

Sources Array

The sources array defines bundle sources available in the hub.

Required Fields per Source

Field	Type	Description
id	string	Unique identifier (alphanumeric, hyphens, underscores; 1-50 chars)
type	string	Source type (see below)
enabled	boolean	Whether this source is currently active
priority	number	Priority order for source resolution (0-100, higher = higher priority)

Source Types

Type	Description
github	GitHub repository releases
local	Local file system directory
awesome-copilot	GitHub-hosted YAML collections
local-awesome-copilot	Local YAML collections
apm	APM package repositories
local-apm	Local APM packages
skills	GitHub repository with skills
local-skills	Local filesystem skills directory

Optional Fields per Source

Field	Type	Description
url	string	URL or path to the source
repository	string	GitHub repository in owner/repo format
branch	string	Git branch name
name	string	Human-readable name of the source
config	object	Source-specific configuration
metadata	object	Additional source metadata

Config Object

Field	Type	Description
branch	string	Git branch name (for git-based sources)
collectionsPath	string	Path to collections directory (for awesome-copilot)
indexFile	string	Index file name (for awesome-copilot)

Source Metadata Object

Field	Type	Description
description	string	Source description
homepage	string	Source homepage URL
contact	string	Contact information

Example

sources:
  - id: "company-bundles"
    type: "github"
    repository: "myorg/prompt-bundles"
    branch: "main"
    name: "Company Bundles"
    enabled: true
    priority: 100
    config:
      branch: "main"
    metadata:
      description: "Official company prompt bundles"
      homepage: "https://github.com/myorg/prompt-bundles"

  - id: "community-collection"
    type: "awesome-copilot"
    repository: "community/awesome-prompts"
    enabled: true
    priority: 50
    config:
      collectionsPath: "collections"
      indexFile: "index.yml"

Profiles Array (Optional)

The profiles array defines predefined bundle collections.

Required Fields per Profile

Field	Type	Description
id	string	Unique identifier (alphanumeric, hyphens, underscores; 1-50 chars)
name	string	Human-readable name (1-100 characters)
description	string	Description of the profile's purpose (1-500 characters)
bundles	array	List of bundles included in this profile (minimum 1)

Optional Fields per Profile

Field	Type	Description
icon	string	Icon or emoji for the profile
active	boolean	Whether this profile is currently active
createdAt	string	ISO 8601 timestamp of creation
updatedAt	string	ISO 8601 timestamp of last update
path	array	Path hierarchy for organizing in the UI

Bundle Object (within Profile)

Field	Type	Required	Description
id	string	Yes	Bundle identifier (1-50 chars)
version	string	Yes	Bundle version (semver or "latest")
source	string	Yes	Source ID where this bundle is available
required	boolean	Yes	Whether this bundle is mandatory for the profile

Example

profiles:
  - id: "frontend-dev"
    name: "Frontend Development"
    description: "Essential prompts for frontend developers"
    icon: "🎨"
    active: false
    bundles:
      - id: "react-patterns"
        version: "latest"
        source: "company-bundles"
        required: true
      - id: "css-helpers"
        version: "2.0.0"
        source: "company-bundles"
        required: false
    path:
      - "engineering"
      - "frontend"

Configuration Object (Optional)

Hub-level configuration settings.

Field	Type	Description
autoSync	boolean	Enable automatic synchronization with hub sources
syncInterval	number	Sync interval in seconds (60-86400)
strictMode	boolean	Enable strict validation and security checks

Example

configuration:
  autoSync: true
  syncInterval: 3600
  strictMode: true

Telemetry Object (Optional)

Hub-level telemetry configuration for forwarding extension events to an Elastic Search cluster.

Elastic Search Configuration

Field	Type	Required	Description
node	string	Yes	Elastic Search telemetry proxy URL (e.g., https://es-proxy.internal:8080)
indexPrefix	string	No	Custom index prefix (default: prompt-registry-telemetry)

Note: Authentication is handled by the telemetry proxy. The extension sends events to the proxy, which manages credentials and forwards data to Elastic Search.

Example

telemetry:
  elasticSearch:
    node: "https://es-proxy.internal:8080"
    indexPrefix: "my-team-telemetry"

Complete Example

version: "1.0.0"

metadata:
  name: "Engineering Team Hub"
  description: "Centralized prompt management for the engineering organization"
  maintainer: "Platform Team"
  updatedAt: "2025-01-15T10:30:00Z"

sources:
  - id: "official-bundles"
    type: "github"
    repository: "myorg/prompt-bundles"
    name: "Official Bundles"
    enabled: true
    priority: 100
    config:
      branch: "main"

  - id: "community"
    type: "awesome-copilot"
    repository: "community/awesome-prompts"
    enabled: true
    priority: 50

profiles:
  - id: "backend-starter"
    name: "Backend Starter Kit"
    description: "Essential prompts for backend development"
    icon: "⚙️"
    bundles:
      - id: "api-design"
        version: "latest"
        source: "official-bundles"
        required: true
      - id: "testing-helpers"
        version: "1.2.0"
        source: "official-bundles"
        required: false

configuration:
  autoSync: true
  syncInterval: 3600

telemetry:
  elasticSearch:
    node: "https://es-proxy.internal:8080"

Validation

Hub configurations are automatically validated during import and loading operations using two validation phases:

Schema Validation

• Uses JSON Schema validation with AJV
• Validates against schemas/hub-config.schema.json
• Checks field types, required fields, patterns, and constraints

Runtime Validation

• Additional business logic checks
• Validates hub references and security constraints
• Verifies source configurations and accessibility

Manual Validation

To manually validate a hub configuration:

1. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Run "AI Primitives Hub: Import Hub"
3. The extension validates the configuration before importing

Validation errors are displayed in VS Code notifications and logged to the output channel.

See Also

• Profiles and Hubs Guide — User guide for working with hubs
• Collection Schema — Schema for collection YAML files
• Settings Reference — Extension configuration options