CI Validation Checks

Every pull request to the Color Palettes repository is automatically validated by Continuous Integration (CI) checks. These automated tests ensure that all contributions meet the project’s quality standards before merging.

Overview of CI Validation

The validation workflow runs automatically when:

Pull Requests

Any PR targeting the main branch that modifies JSON files

Direct Pushes

Any push to the main branch that modifies JSON files

File Triggers:

*.json (root level JSON files)
palettes/**/*.json (JSON files in palettes directory)

CI Workflow Structure

The complete workflow is defined in .github/workflows/validate-schema.yml:

name: Validate Color Palette Schema

on:
  push:
    branches: [ main ]
    paths:
      - '*.json'
      - 'palettes/**/*.json'
  pull_request:
    branches: [ main ]
    paths:
      - '*.json'
      - 'palettes/**/*.json'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate JSON Schema
        uses: cardinalby/schema-validator-action@v1
        with:
          schema: schema.json
          file: color-palettes.json

      - name: Check for duplicate aliases
        run: |
          # Extract all aliases and their protocols, then check for duplicates
          jq -r 'to_entries | .[] | .key as $protocol | .value.aliases[] | [$protocol, .] | @tsv' color-palettes.json | \
          awk -F '\t' '{
            # Store the original alias
            original_alias = $2
            # Convert alias to lowercase for case-insensitive comparison
            alias = tolower(original_alias)
            
            # Check if this exact alias has been seen before (only comparing aliases)
            if (seen[alias]) {
              printf "Error: Duplicate alias \"%s\" found in protocols \"%s\" and \"%s\"\n", 
                     original_alias, seen[alias], $1
              exit 1
            }
            
            # Store the protocol for this alias
            seen[alias] = $1
          }'

Validation Checks Explained

Check 1: JSON Schema Validation

What It Checks
Implementation
Common Failures

Validates that color-palettes.json conforms to the defined schema in schema.json.Validation Rules:

Protocol Name Format

Pattern: ^[A-Za-z0-9\\s\\-_().₮]+$Valid Examples:

✅ "Ethereum"
✅ "Polygon zkEVM"
✅ "1inch"
✅ "USD₮"

Invalid Examples:

❌ "Protocol/Name" (contains /)
❌ "Protocol@Chain" (contains @)
❌ "Protocol#1" (contains #)

Hex Color Format

Pattern: ^#[0-9A-Fa-f]{6}$Valid Examples:

✅ "#627EEA"
✅ "#FF007A"
✅ "#000000"

Invalid Examples:

❌ "627EEA" (missing # prefix)
❌ "#627" (too short)
❌ "#627EEAFF" (too long - no alpha)
❌ "#GG0000" (invalid hex characters)

Aliases Array Format

Requirements:

Must be an array
Minimum 1 item
All items must be unique
Each item matches: ^[a-zA-Z0-9_\\s.₮-]+$

Valid Examples:

✅ ["ethereum", "eth", "weth"]
✅ ["polygon"]
✅ ["usd-tether-0"]

Invalid Examples:

❌ [] (empty array)
❌ ["eth", "eth"] (duplicates)
❌ ["eth/weth"] (invalid character /)

Required Fields

Every protocol entry must include:

"hex" (string)
"aliases" (array)

Valid Example:

"Ethereum": {
  "hex": "#88AAF1",
  "aliases": ["ethereum", "eth"]
}

Invalid Examples:

// ❌ Missing hex
"Ethereum": {
  "aliases": ["ethereum"]
}

// ❌ Missing aliases
"Ethereum": {
  "hex": "#88AAF1"
}

// ❌ Extra fields not allowed
"Ethereum": {
  "hex": "#88AAF1",
  "aliases": ["ethereum"],
  "description": "Layer 1 blockchain"
}

Uses the cardinalby/schema-validator-action@v1 GitHub Action:

- name: Validate JSON Schema
  uses: cardinalby/schema-validator-action@v1
  with:
    schema: schema.json
    file: color-palettes.json

The Schema (schema.json):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "patternProperties": {
    "^[A-Za-z0-9\\s\\-_().₮]+$": {
      "type": "object",
      "properties": {
        "hex": {
          "type": "string",
          "pattern": "^#[0-9A-Fa-f]{6}$"
        },
        "aliases": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_\\s.₮-]+$"
          },
          "minItems": 1,
          "uniqueItems": true
        }
      },
      "required": ["hex", "aliases"],
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Invalid Hex Color

Error: Instance does not match schema
Path: /Ethereum/hex
Message: String does not match pattern ^#[0-9A-Fa-f]{6}$
Value: "627EEA"

Fix: Add # prefix → "#627EEA"

Empty Aliases Array

Error: Instance does not match schema
Path: /Ethereum/aliases
Message: Array has too few items (0), minimum 1
Value: []

Fix: Add at least one alias → ["ethereum"]

Missing Required Field

Error: Instance does not match schema
Path: /Ethereum
Message: Required property 'hex' is missing

Fix: Add hex property → "hex": "#88AAF1"

Additional Properties

Error: Instance does not match schema
Path: /Ethereum
Message: Additional properties not allowed: description

Fix: Remove extra fields, only hex and aliases allowed

Check 2: Duplicate Alias Detection

What It Checks
Implementation
Case Sensitivity
Common Failures

Ensures no alias is used by multiple protocols, using case-insensitive comparison.Detection Logic:

Extracts all aliases from all protocols
Converts each alias to lowercase
Tracks which protocol “owns” each lowercase alias
Fails if any alias appears in multiple protocols

Example Conflict:

{
  "BNB": {
    "hex": "#F3BA2F",
    "aliases": ["bnb", "bsc"]
  },
  "Basis Cash": {
    "hex": "#000000",
    "aliases": ["bsc", "basis"]  // ❌ "bsc" conflicts
  }
}

CI Output:

Error: Duplicate alias "bsc" found in protocols "BNB" and "Basis Cash"

Custom shell script using jq and awk:

# Extract all aliases and their protocols, then check for duplicates
jq -r 'to_entries | .[] | .key as $protocol | .value.aliases[] | [$protocol, .] | @tsv' color-palettes.json | \
awk -F '\t' '{
  # Store the original alias
  original_alias = $2
  # Convert alias to lowercase for case-insensitive comparison
  alias = tolower(original_alias)
  
  # Check if this exact alias has been seen before (only comparing aliases)
  if (seen[alias]) {
    printf "Error: Duplicate alias \"%s\" found in protocols \"%s\" and \"%s\"\n", 
           original_alias, seen[alias], $1
    exit 1
  }
  
  # Store the protocol for this alias
  seen[alias] = $1
}'

How It Works:

Extract Protocol-Alias Pairs

jq extracts all protocols and their aliases into tab-separated format:

Ethereum    ethereum
Ethereum    eth
Ethereum    weth
Polygon     polygon
Polygon     matic

Process Each Alias

awk reads each line and:

Stores the original alias (preserving case)
Converts alias to lowercase for comparison
Checks if lowercase alias already exists

Track Ownership

Associates each lowercase alias with its protocol in the seen array:

seen["ethereum"] = "Ethereum"
seen["eth"] = "Ethereum"
seen["polygon"] = "Polygon"

Detect Conflicts

If a lowercase alias is encountered that already exists in seen, the script:

Prints an error message
Shows both protocols using the alias
Exits with code 1 (failure)

The check is case-insensitive because Dune’s color matching uses lowercase comparison.These Would Conflict:

{
  "Protocol A": {
    "hex": "#111111",
    "aliases": ["ETH"]  // Uppercase
  },
  "Protocol B": {
    "hex": "#222222",
    "aliases": ["eth"]  // Lowercase - ❌ CONFLICT
  }
}

Error Message:

Error: Duplicate alias "eth" found in protocols "Protocol A" and "Protocol B"

Even though “ETH” and “eth” look different, they’re treated as the same alias because Dune matches case-insensitively.

Simple Duplicate

Error: Duplicate alias "bsc" found in protocols "BNB" and "Basis Cash"

Fix: Remove or rename the conflicting alias in one of the protocolsSee Understanding Alias Conflicts for resolution strategies.

Case Variation Duplicate

Error: Duplicate alias "OP" found in protocols "Optimism" and "Ocean Protocol"

Fix: Use more specific aliases:

Optimism: ["optimism", "op", "op mainnet"]
Ocean Protocol: ["ocean", "ocean_protocol"]

Multi-Protocol Conflict

Error: Duplicate alias "link" found in protocols "Chainlink" and "Link Protocol"
Error: Duplicate alias "link" found in protocols "Link Protocol" and "LinkDAO"

Fix: Only one protocol can use “link”. Assign to most common usage (Chainlink), others use specific aliases.

Interpreting CI Results

Successful Validation

When all checks pass, you’ll see:

✅ Validate Color Palette Schema
   ✅ Validate JSON Schema — Passed
   ✅ Check for duplicate aliases — Passed

Your pull request is ready for maintainer review!

Failed Validation

When checks fail, you’ll see specific error messages:

Schema Validation Failure
Duplicate Alias Failure
Multiple Failures

❌ Validate Color Palette Schema
   ❌ Validate JSON Schema — Failed
   
   Error: Instance does not match schema
   Path: /Ethereum/hex
   Message: String does not match pattern ^#[0-9A-Fa-f]{6}$
   Value: "627EEA"

What to do:

Read the error message carefully
Identify the problematic path (e.g., /Ethereum/hex)
Check the value against the schema requirements
Fix the issue in your color-palettes.json
Commit and push the fix

❌ Validate Color Palette Schema
   ✅ Validate JSON Schema — Passed
   ❌ Check for duplicate aliases — Failed
   
   Error: Duplicate alias "bsc" found in protocols "BNB" and "Basis Cash"

What to do:

Identify the conflicting alias (e.g., “bsc”)
Determine which protocols are affected
Refer to Understanding Alias Conflicts
Choose and implement a resolution strategy
Commit and push the fix

❌ Validate Color Palette Schema
   ❌ Validate JSON Schema — Failed
   ❌ Check for duplicate aliases — Failed
   
   Schema Error: Missing required property 'hex' at /NewProtocol
   Duplicate Error: Duplicate alias "op" found in protocols "Optimism" and "Ocean Protocol"

What to do:

Fix schema issues first (they’re usually simpler)
Then address alias conflicts
Commit all fixes together
Push and wait for CI to re-run

Troubleshooting CI Failures

CI Won't Run

Symptoms: No CI checks appear on your PRPossible Causes:

You didn’t modify any JSON files
Changes are in a different directory
Branch protection not configured

Solutions:

Ensure you modified color-palettes.json or files in palettes/**/*.json
Check the “Files changed” tab in your PR
Verify the workflow file exists in .github/workflows/

CI Stuck on 'Pending'

Symptoms: CI checks show “Expected — Waiting for status to be reported”Possible Causes:

GitHub Actions queue delay
Workflow requires approval (first-time contributors)
Repository Actions disabled

Solutions:

Wait a few minutes for the queue
Ask a maintainer to approve workflow run
Check if Actions are enabled in repository settings

Can't Understand Error Message

Symptoms: CI fails but error message is unclearSolutions:

Click “Details” next to the failed check
Expand the failed step to see full logs
Copy the exact error message
Search documentation or existing issues
Comment on your PR asking for clarification

Maintainers are happy to help interpret CI errors. Include the full error message in your comment.

Fixed but CI Still Fails

Symptoms: Made changes but CI shows same errorPossible Causes:

Changes not committed
Changes not pushed
CI running on old commit

Solutions:

# Verify changes are staged
git status

# Commit if needed
git add color-palettes.json
git commit -m "Fix CI issues"

# Push to trigger new CI run
git push origin your-branch-name

Check the commit SHA in the PR to ensure CI is running on your latest commit.

CI Passes Locally but Fails in GitHub

Symptoms: Local validation passes but CI failsPossible Causes:

Different versions of tools (jq, etc.)
Line ending differences (Windows vs. Unix)
Testing different file

Solutions:

Ensure you’re testing the exact same file
Check for whitespace or encoding issues
Trust CI results over local tests
Review the CI logs for specific differences

Running Validation Locally

You can run the same checks locally before submitting:

Install Required Tools

macOS
Linux
Windows

# Install jq using Homebrew
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Fedora
sudo dnf install jq

# Arch
sudo pacman -S jq

# Using Chocolatey
choco install jq

# Or download from https://stedolan.github.io/jq/download/

Validate JSON Schema

# Basic JSON syntax validation
cat color-palettes.json | jq . > /dev/null && echo "✓ Valid JSON"

# For full schema validation, install ajv-cli:
npm install -g ajv-cli
ajv validate -s schema.json -d color-palettes.json

Check for Duplicate Aliases

# Run the exact CI check locally
jq -r 'to_entries | .[] | .key as $protocol | .value.aliases[] | [$protocol, .] | @tsv' color-palettes.json | \
awk -F '\t' '{
  original_alias = $2
  alias = tolower(original_alias)
  
  if (seen[alias]) {
    printf "Error: Duplicate alias \"%s\" found in protocols \"%s\" and \"%s\"\n", 
           original_alias, seen[alias], $1
    exit 1
  }
  
  seen[alias] = $1
}' && echo "✓ No duplicate aliases found"

Best Practices for Passing CI

Validate Before Committing

Run local validation before every commit to catch issues early

Follow the Schema Exactly

Don’t add extra fields or use different formats than specified

Check for Existing Aliases

Search the JSON file before adding new aliases to avoid conflicts

Use Automated Formatting

Format your JSON with jq or your editor’s formatter

Getting Help

If you’re stuck with CI failures:

Read the error message carefully - it usually tells you exactly what’s wrong
Check this documentation for explanations and solutions
Review Contribution Guidelines for best practices
Search existing issues and PRs for similar problems
Comment on your PR asking for help (include the full error message)

CI checks are designed to help you, not block you. When they fail, they’re providing valuable feedback to improve your contribution.

Getting Started

Using Color Palettes

Schema

Contributing

Reference

Overview of CI Validation

Pull Requests

Direct Pushes

CI Workflow Structure

Validation Checks Explained

Check 1: JSON Schema Validation

Check 2: Duplicate Alias Detection

Interpreting CI Results

Successful Validation

Failed Validation

Troubleshooting CI Failures

Running Validation Locally

Best Practices for Passing CI

Validate Before Committing

Follow the Schema Exactly

Check for Existing Aliases

Use Automated Formatting

Getting Help

​Overview of CI Validation

Pull Requests

Direct Pushes

​CI Workflow Structure

​Validation Checks Explained

​Check 1: JSON Schema Validation

​Check 2: Duplicate Alias Detection

​Interpreting CI Results

​Successful Validation

​Failed Validation

​Troubleshooting CI Failures

​Running Validation Locally

​Best Practices for Passing CI

Validate Before Committing

Follow the Schema Exactly

Check for Existing Aliases

Use Automated Formatting

​Getting Help

Overview of CI Validation

CI Workflow Structure

Validation Checks Explained

Check 1: JSON Schema Validation

Check 2: Duplicate Alias Detection

Interpreting CI Results

Successful Validation

Failed Validation

Troubleshooting CI Failures

Running Validation Locally

Best Practices for Passing CI

Getting Help