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	Stable identity of the source, unique within the hub (alphanumeric, hyphens, underscores; 1-50 chars). Stays unchanged once the hub configuration is published — see Source Identity
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 Identity

A source's id is its identity, not a label. Once a hub configuration is published, that value stays unchanged for the lifetime of the source.

Renaming a source URL. Keep the id value unchanged and change only the location — repository for github and awesome-copilot sources, url for apm sources. Because the id stayed the same, users who already installed bundles from that source have those bundles migrated to the new location on the next hub sync, so they stay updatable.

Changing an id is a different edit. It is read as removing one source and adding an unrelated one. The removed source is kept rather than deleted while installed bundles still reference it, so nothing is lost, but those bundles stay pointed at the old location and stop receiving updates from the new one.

Changing an id also breaks profiles, with or without a URL change. A profile bundle's source field names a source id (see Bundle Object), so every profile entry referencing the old id no longer resolves. That consequence is independent of installed-bundle migration.

See Renaming a Source URL in the author guide for the full workflow and its troubleshooting entries.

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

Schema boundary: Other parts of AI Primitives Hub have additional source adapters. A source type can be used inside hub-config.yml only when it is included in the Hub JSON Schema. The schema is authoritative for this list.

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 sources)
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	The id of a source declared in this hub's sources array (see Source Identity)
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

Validation currently differs by delivery layer.

Schema Validation

The VS Code extension uses AJV and the Hub JSON Schema to check field types, required fields, patterns, and constraints.

Runtime Validation

Shared runtime validation checks required metadata, basic source/profile shape, path traversal, and profile source references. The CLI currently runs these runtime checks during import, but does not apply the complete JSON Schema. Source accessibility is checked during resolution or synchronization, not by the schema itself.

Manual Validation

To run the CLI's runtime validation, import the local file without activating or synchronizing it:

ai-primitives-hub hub add \
  --type local \
  --location ./hub-config.yml \
  --id hub-validation \
  --no-use \
  --no-sync

The local --location is the path to the YAML file, not its containing directory. Remove the temporary imported entry after validation with ai-primitives-hub hub remove hub-validation.

To apply the full JSON Schema and runtime validation with the extension:

1. Open the Command Palette (Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS).
2. Run AI Primitives Hub: Import Hub.
3. Select the local hub-config.yml file
4. 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
• Creating a Hub — End-to-end authoring and publishing
• Adding Profiles and Sources to Existing Hubs — Editing sources[], including renaming a source URL
• Collection Schema — Schema for collection YAML files
• Settings Reference — Extension configuration options