Shared Configuration and Groupings

Awesome Comparisons provides a powerful configuration inheritance system that allows you to define criteria, groupings, and value displays once and reuse them across multiple datasets. This eliminates duplication and ensures consistency.

Overview

The configuration system consists of three layers:

Shared Defaults - Common configuration in configuration/defaults/
Dataset Manifest - Specifies which shared configs each dataset uses
Dataset-Specific - Local overrides in datasets/{id}/config/comparison.yml

Shared Configuration Files

Location

All shared configuration files live in configuration/defaults/:

configuration/
├── datasets.manifest.json          # Dataset registry
├── comparison-default.yml          # Global defaults
└── defaults/                       # Shared fragments
    ├── general-licensing.yml       # License-related criteria
    ├── groups-advanced.yml         # Advanced grouping definitions
    ├── groups.yml                  # Basic grouping definitions
    └── value-displays.yml          # Common value displays

Types of Shared Configuration

1. Criteria Definitions

Define reusable criteria in shared YAML files:

Example: configuration/defaults/general-licensing.yml

criteria:
  - License:
      name: License
      type: LABEL
      search: true
      table: true
      detail: true
      values:
        - name: "MIT"
          description: "MIT License - permissive open source"
          class: "label-success"
        - name: "Apache-2.0"
          description: "Apache License 2.0"
          class: "label-success"
        - name: "GPL-3.0"
          description: "GNU General Public License v3.0"
          class: "label-info"
        - name: "Proprietary"
          description: "Proprietary/commercial license"
          class: "label-warning"

  - Opensource:
      name: Opensource
      type: LABEL
      search: true
      table: true
      values:
        - name: "Yes"
          display: "Yes"
          class: "label-success"
        - name: "No"
          display: "No"
          class: "label-warning"

  - FreeTrial:
      name: FreeTrial
      type: LABEL
      search: true
      table: true
      values:
        - name: "Yes"
          display: "✓"
          class: "label-success"
        - name: "No"
          display: "✗"
          class: "label-danger"

2. Grouping Definitions

Define how criteria are organized into groups. Groups are regular criteria items with special properties:

Example: configuration/defaults/groups-advanced.yml

criteria:
  - General:
      name: General Info
      type: MARKDOWN
      search: false
      table: false
      detail: false
      order: '10'
      defaultExpanded: true
      children:
        - Classification
        - Version
        - Repository
        - Rating
        - ShortDescription
        - Description
        - Languages

  - Licensing:
      name: Licensing
      type: MARKDOWN
      search: false
      table: false
      detail: false
      order: '20'
      defaultExpanded: true
      children:
        - Opensource
        - License
        - FreeTrial

  - Features:
      name: Features
      type: MARKDOWN
      search: false
      table: false
      detail: false
      order: '30'
      defaultExpanded: true
      children:
        - BYOK
        - Local Offline
        - Git Support
        - Terminal
        - Extensible
        - MCP-Client

3. Value Displays

Define how specific values should render:

Example: configuration/defaults/value-displays.yml

criteria:
  - Classification:
      values:
        - name: "AIE/Model"
          display: "AIE/Model"
        - name: "Code/Editor"
          display: "Code/Editor"
        - name: "Code/Terminal"
          display: "Code/Terminal"

  - Languages:
      values:
        - name: "Python"
          display: "🐍 Python"
        - name: "JavaScript"
          display: "JS"
        - name: "TypeScript"
          display: "TS"
        - name: "Java"
          display: "☕ Java"
        - name: "Any"
          display: "Any"

Dataset Manifest Configuration

The dataset manifest (configuration/datasets.manifest.json) specifies which shared configuration files each dataset should inherit.

Example Entry

{
  "id": "aie-model",
  "displayLabel": "AIE/Model",
  "sources": {
    "dataDir": "datasets/aie-model/data",
    "config": "datasets/aie-model/config/comparison.yml",
    "configDefaults": [
      "configuration/comparison-default.yml",
      "configuration/defaults/general-licensing.yml",
      "configuration/defaults/groups-advanced.yml",
      "configuration/defaults/value-displays.yml"
    ]
  }
}

configDefaults Array

The configDefaults array lists shared configuration files in order:

Files are loaded in the specified order
Later files can override earlier files
Dataset-specific config overrides all shared files
The framework merges criteria by tag (later definitions win)

Order matters! Example:

"configDefaults": [
  "configuration/comparison-default.yml",      // Base defaults
  "configuration/defaults/general-licensing.yml",  // Add licensing criteria
  "configuration/defaults/groups-advanced.yml",    // Add advanced groupings
  "configuration/defaults/value-displays.yml"      // Override value displays
]

Per-Dataset Variation

Different datasets can inherit different combinations:

AIE Model Dataset (full set):

"configDefaults": [
  "configuration/comparison-default.yml",
  "configuration/defaults/general-licensing.yml",
  "configuration/defaults/groups-advanced.yml",
  "configuration/defaults/value-displays.yml"
]

Terminal Dataset (simpler configuration):

"configDefaults": [
  "configuration/comparison-default.yml",
  "configuration/defaults/general-licensing.yml",
  "configuration/defaults/value-displays.yml"
]

Configuration Inheritance Resolution

Resolution Order

When loading a dataset configuration, the system:

Loads Global Defaults
- Start with configuration/comparison-default.yml
Loads Shared Fragments (in order from configDefaults)
- Merge criteria by tag (including groups)
- Later criteria override earlier with same tag
- Groups are criteria items, so they merge like any other criterion
- Merge value displays by value name
Loads Dataset-Specific Config
- datasets/{id}/config/comparison.yml
Applies Dataset Overrides
- Dataset criteria override shared criteria (by tag)
- Groups override like any other criterion (same tag = override)
- Dataset value displays override shared displays
Resolves Group Children
- For each group criterion, resolve children tags against merged criteria
- Warn if any children reference non-existent criteria

Example Resolution

Shared (general-licensing.yml):

criteria:
  - License:
      name: License
      type: LABEL
      search: true
      table: true

Dataset-Specific (datasets/aie-model/config/comparison.yml):

criteria:
  - License:
      name: "License Type"  # Override name
      type: LABEL
      search: true
      table: true
      detail: true  # Add detail visibility

  - BYOK:  # Dataset-unique criterion
      name: "Bring Your Own Key"
      type: LABEL
      search: true

Merged Result for aie-model:

criteria:
  - License:
      name: "License Type"  # From dataset (overrides shared)
      type: LABEL
      search: true
      table: true
      detail: true  # From dataset

  - BYOK:  # From dataset (unique)
      name: "Bring Your Own Key"
      type: LABEL
      search: true

Working with Shared Configuration

Creating Shared Criteria

Identify criteria used by multiple datasets
Create or edit a file in configuration/defaults/
Add criteria definitions with complete metadata
Add the file to configDefaults for relevant datasets

Best practices:

Use descriptive file names (e.g., platform-support.yml)
Group related criteria together
Include comprehensive value definitions
Document shared files with comments

Creating Shared Groupings

Design the grouping structure
Create or edit a grouping file (e.g., groups-custom.yml)
Define groups in criteria array with:
- Criterion key as the group identifier (e.g., - Deployment:)
- name: Display name
- type: Must be MARKDOWN
- search, table, detail: Must all be false
- order: Position in list
- defaultExpanded: Default state (true/false)
- children: Array of criterion tags
Add to configDefaults for datasets that need it

Example: Custom grouping file

# configuration/defaults/groups-devtools.yml
criteria:
  - Deployment:
      name: Deployment Options
      type: MARKDOWN
      search: false
      table: false
      detail: false
      order: '40'
      defaultExpanded: true
      children:
        - BYOK
        - Local Offline
        - Git Support

  - Integration:
      name: Integration Features
      type: MARKDOWN
      search: false
      table: false
      detail: false
      order: '50'
      defaultExpanded: true
      children:
        - Terminal
        - Extensible
        - MCP-Client

Overriding Shared Configuration

To override a shared criterion in a dataset:

Add criterion with same tag to dataset config
Specify fields you want to override
Unspecified fields inherit from shared definition

Example:

Shared:

- Classification:
    name: Classification
    type: LABEL
    search: true
    table: true

Dataset Override:

- Classification:
    name: "Tool Classification"  # Override name only
    # type, search, table inherited from shared

Advanced Patterns

Layered Inheritance

Stack multiple shared files for modular configuration:

"configDefaults": [
  "configuration/comparison-default.yml",       // Base
  "configuration/defaults/general-licensing.yml", // Add licensing criteria
  "configuration/defaults/groups-advanced.yml",   // Add advanced groupings
  "configuration/defaults/value-displays.yml"     // Common displays
]

Partial Overrides

Override just values, not the entire criterion:

Shared:

- Opensource:
    name: Opensource
    type: LABEL
    values:
      - name: "Yes"
        class: "label-success"
      - name: "No"
        class: "label-warning"

Dataset:

- Opensource:
    values:
      - name: "Yes"
        display: "✓ Open Source"  # Override just display
      # Inherits "No" from shared

Conditional Groupings

Different datasets can use different grouping structures by including different shared config files:

Simple Dataset uses groups.yml (basic grouping):

"configDefaults": [
  "configuration/comparison-default.yml",
  "configuration/defaults/groups.yml"
]

Advanced Dataset uses groups-advanced.yml (detailed grouping):

"configDefaults": [
  "configuration/comparison-default.yml",
  "configuration/defaults/groups-advanced.yml"
]

Groups are merged like any other criteria, so datasets can also override or add to groups.

Dynamic Children

Groups can reference criteria that don't exist in all datasets:

Shared grouping:

criteria:
  - Features:
      name: Features
      type: MARKDOWN
      search: false
      table: false
      detail: false
      order: '30'
      defaultExpanded: true
      children:
        - BYOK
        - Local Offline
        - Git Support
        - Terminal  # May not exist in all datasets

The system resolves children against the merged criteria for each dataset and warns (but doesn't fail) if criteria are missing.

Best Practices

Organization

One Concern Per File: Keep licensing criteria separate from platform criteria
Logical Naming: Use clear, descriptive file names
Modular Design: Create small, focused shared files for easy mixing

Maintenance

Document Changes: Comment YAML files with explanations
Version Shared Files: Treat shared configs as reusable modules
Test Impact: When changing shared files, test all datasets that inherit them

Performance

Minimal Duplication: Use shared configs instead of copying
Lazy Loading: Only include shared files actually needed
Cache Friendly: Shared configs are loaded once and cached

Governance

Review Changes: Changes to shared files affect multiple datasets
Coordinate Updates: Communicate with dataset owners before modifying shared files
Backward Compatibility: Avoid breaking changes to shared configs

Troubleshooting

Group Child Not Found

Error: "Group child 'X' not found in criteria definitions"

Cause: A group criterion references a child tag that doesn't exist in the merged criteria.

Solutions:

Add the missing criterion to shared or dataset config
Remove the child reference from the group's children array
Check for typos in tag names (case-sensitive)

Duplicate Tag Warning

Error: "Duplicate criterion tag 'X'"

Cause: Same tag defined in multiple shared files or shared + dataset.

Solutions:

Remove duplicate from one file
If intentional override, ensure dataset file comes last
Use unique tags for distinct criteria

Shared Config Not Applied

Symptom: Changes to shared config don't appear in dataset.

Checks:

Verify shared file is in configDefaults array
Check file path is correct
Ensure YAML syntax is valid
Rebuild dataset: npm run data:prepare -- --dataset {id}
Clear browser cache

Override Not Working

Symptom: Dataset override doesn't replace shared definition.

Checks:

Verify tag matches exactly (case-sensitive)
Ensure dataset config is loaded after shared
Check inheritance resolution order
Use admin interface to inspect merged config

Examples

Complete Shared Configuration Setup

1. Create shared criteria file:

configuration/defaults/custom-features.yml:

criteria:
  - BYOK:
      name: "Bring Your Own Key"
      type: LABEL
      search: true
      table: true
      values:
        - name: "Yes"
          class: "label-success"
        - name: "No"
          class: "label-secondary"
        - name: "Partial"
          class: "label-info"

  - Local Offline:
      name: "Local/Offline"
      type: LABEL
      search: true
      values:
        - name: "Yes"
          display: "✓"
        - name: "No"
          display: "✗"

2. Create shared grouping:

configuration/defaults/groups-custom.yml:

criteria:
  - DeploymentFeatures:
      name: Deployment Features
      type: MARKDOWN
      search: false
      table: false
      detail: false
      order: '60'
      defaultExpanded: true
      children:
        - BYOK
        - Local Offline

3. Add to dataset manifest:

{
  "id": "aie-model",
  "sources": {
    "configDefaults": [
      "configuration/comparison-default.yml",
      "configuration/defaults/custom-features.yml",
      "configuration/defaults/groups-custom.yml"
    ]
  }
}

4. Dataset can now override:

datasets/aie-model/config/comparison.yml:

criteria:
  - BYOK:
      name: "API Key Support"  # Override name
      # Other fields inherited from shared

  - MCP-Client:  # Dataset-specific
      name: "MCP Client Support"
      type: LABEL

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Shared Configuration and Groupings

Overview

Shared Configuration Files

Location

Types of Shared Configuration

1. Criteria Definitions

2. Grouping Definitions

3. Value Displays

Dataset Manifest Configuration

Example Entry

configDefaults Array

Per-Dataset Variation

Configuration Inheritance Resolution

Resolution Order

Example Resolution

Working with Shared Configuration

Creating Shared Criteria

Creating Shared Groupings

Overriding Shared Configuration

Advanced Patterns

Layered Inheritance

Partial Overrides

Conditional Groupings

Dynamic Children

Best Practices

Organization

Maintenance

Performance

Governance

Troubleshooting

Group Child Not Found

Duplicate Tag Warning

Shared Config Not Applied

Override Not Working

Examples

Complete Shared Configuration Setup

See Also

FilesExpand file tree

Shared_Configuration.md

Latest commit

History

Shared_Configuration.md

File metadata and controls

Shared Configuration and Groupings

Overview

Shared Configuration Files

Location

Types of Shared Configuration

1. Criteria Definitions

2. Grouping Definitions

3. Value Displays

Dataset Manifest Configuration

Example Entry

configDefaults Array

Per-Dataset Variation

Configuration Inheritance Resolution

Resolution Order

Example Resolution

Working with Shared Configuration

Creating Shared Criteria

Creating Shared Groupings

Overriding Shared Configuration

Advanced Patterns

Layered Inheritance

Partial Overrides

Conditional Groupings

Dynamic Children

Best Practices

Organization

Maintenance

Performance

Governance

Troubleshooting

Group Child Not Found

Duplicate Tag Warning

Shared Config Not Applied

Override Not Working

Examples

Complete Shared Configuration Setup

See Also