Schema Validation

The Color Palettes project uses JSON Schema Draft 7 to validate all entries automatically. This ensures data quality, consistency, and reliability across the entire collection.

JSON Schema Definition

The complete JSON schema used to validate color palette entries:

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
}

Validation Rules Breakdown

Root Level Validation

string

default:"object"

The color palettes file must be a JSON object at the root level.

// ✅ Valid: Root is an object
{
  "Ethereum": { ... },
  "Uniswap": { ... }
}

// ❌ Invalid: Root is an array
[
  { "name": "Ethereum", ... }
]

boolean

default:"false"

Only protocol entries matching the pattern are allowed. No extra top-level properties.

// ❌ Invalid: Extra top-level property
{
  "version": "1.0",  // Not allowed
  "Ethereum": {
    "hex": "#88AAF1",
    "aliases": ["ethereum", "eth"]
  }
}

Protocol Name Pattern

object

Protocol names must match: ^[A-Za-z0-9\\s\\-_().₮]+$Valid Protocol Names:

"Ethereum"           // ✅ Letters only
"1inch"              // ✅ Starts with number
"Polygon zkEVM"      // ✅ Contains space
"SEI (Cosmos)"       // ✅ Contains parentheses
"USD₮"               // ✅ Contains special character ₮
"Optimism-Legacy"    // ✅ Contains hyphen
"proof_of_play"      // ✅ Contains underscore
"Phi.Box"            // ✅ Contains period

Invalid Protocol Names:

"Protocol@Name"      // ❌ @ not allowed
"Protocol/Name"      // ❌ / not allowed
"Protocol#Name"      // ❌ # not allowed
"Protocol$Name"      // ❌ $ not allowed
"Protocol&Name"      // ❌ & not allowed
""                   // ❌ Empty string

Hex Color Validation

string

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

Must start with #
Must be followed by exactly 6 hexadecimal characters
Accepts both uppercase (A-F) and lowercase (a-f)
No alpha channel (8-character codes not allowed)

Valid Hex Codes:

"#88AAF1"  // ✅ Uppercase hex
"#f50db4"  // ✅ Lowercase hex
"#0052FF"  // ✅ Mixed case
"#000000"  // ✅ Black
"#FFFFFF"  // ✅ White
"#123ABC"  // ✅ Numbers and letters

Invalid Hex Codes:

"88AAF1"     // ❌ Missing #
"#88AAF"     // ❌ Only 5 characters
"#88AAFFFF"  // ❌ 8 characters (no alpha support)
"#GGG111"    // ❌ Invalid hex character 'G'
"#88A AF1"   // ❌ Contains space
"rgb(136, 170, 241)" // ❌ Not hex format
"blue"       // ❌ Not hex format

Aliases Array Validation

number

default:"1"

At least one alias is required.

// ✅ Valid: Single alias
"aliases": ["ethereum"]

// ✅ Valid: Multiple aliases
"aliases": ["ethereum", "eth", "weth"]

// ❌ Invalid: Empty array
"aliases": []

boolean

default:"true"

All aliases in the array must be unique (no duplicates).

// ✅ Valid: All unique
"aliases": ["ethereum", "eth", "weth"]

// ❌ Invalid: Duplicate "eth"
"aliases": ["ethereum", "eth", "eth", "weth"]

string

Pattern: ^[a-zA-Z0-9_\\s.₮-]+$Valid Alias Examples:

"ethereum"           // ✅ Lowercase letters
"ETHEREUM"           // ✅ Uppercase letters
"eth"                // ✅ Abbreviation
"uniswap_v3"         // ✅ With underscore
"sei cosmos"         // ✅ With space
"avalanche c-chain"  // ✅ With hyphen
"usdc.n"             // ✅ With period
"usd-tether"         // ✅ Combined

Invalid Alias Examples:

""                   // ❌ Empty string
"eth@mainnet"        // ❌ @ not allowed
"eth/mainnet"        // ❌ / not allowed
"eth#1"              // ❌ # not allowed
"eth(v1)"            // ❌ Parentheses not allowed in aliases

Required Properties

array

default:"[\"hex\", \"aliases\"]"

Both hex and aliases are required for every protocol entry.

// ✅ Valid: Both properties present
{
  "Ethereum": {
    "hex": "#88AAF1",
    "aliases": ["ethereum", "eth"]
  }
}

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

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

Additional Properties

boolean

default:"false"

Protocol objects can only contain hex and aliases properties. No additional fields allowed.

// ✅ Valid: Only hex and aliases
{
  "Ethereum": {
    "hex": "#88AAF1",
    "aliases": ["ethereum", "eth"]
  }
}

// ❌ Invalid: Extra property "rgb"
{
  "Ethereum": {
    "hex": "#88AAF1",
    "rgb": "rgb(136, 170, 241)",
    "aliases": ["ethereum", "eth"]
  }
}

// ❌ Invalid: Extra property "description"
{
  "Ethereum": {
    "hex": "#88AAF1",
    "aliases": ["ethereum", "eth"],
    "description": "Ethereum mainnet"
  }
}

Automated CI Validation

Every pull request triggers automated validation checks to ensure data quality and prevent conflicts.

JSON Schema Validation

The CI pipeline validates the entire color-palettes.json file against the schema definition.Checks performed:

Valid JSON syntax
All protocol names match the allowed pattern
All hex codes are valid 6-character hex colors
All aliases arrays have at least one item
All aliases match the allowed pattern
No duplicate aliases within the same entry
No additional properties present

Alias Conflict Detection

The CI system checks for duplicate aliases across different protocols.

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

Error message: Alias conflict detected: "bsc" is used by both "BNB" and "Basis Cash"

Hex Color Format

Validates that all hex codes follow the correct format and contain valid hexadecimal characters.

// ❌ These will fail validation
"hex": "#82828"   // Only 5 characters
"hex": "#GGGGGG"  // Invalid hex characters
"hex": "88AAF1"   // Missing #

Required Fields Check

Ensures every protocol entry includes both required fields: hex and aliases.

// ❌ This will fail - missing aliases
{
  "Ethereum": {
    "hex": "#88AAF1"
  }
}

Validation Examples

Complete Valid Entry

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

{
  "Ethereum": {
    "hex": "#88AAF1",
    "aliases": ["ethereum", "eth", "weth"]
  },
  "Base": {
    "hex": "#0052FF",
    "aliases": ["base"]
  },
  "Arbitrum": {
    "hex": "#12AAFF",
    "aliases": ["arbitrum", "arbitrum one", "arb"]
  }
}

Common Validation Errors

Missing # in Hex Code

// ❌ Invalid
{
  "Ethereum": {
    "hex": "88AAF1",
    "aliases": ["ethereum"]
  }
}

Error: String does not match pattern "^#[0-9A-Fa-f]{6}$"Fix: Add # prefix to the hex code:

"hex": "#88AAF1"

Empty Aliases Array

// ❌ Invalid
{
  "Ethereum": {
    "hex": "#88AAF1",
    "aliases": []
  }
}

Error: Array must contain at least 1 item (minItems: 1)Fix: Add at least one alias:

"aliases": ["ethereum"]

Invalid Hex Characters

// ❌ Invalid
{
  "Ethereum": {
    "hex": "#GGHHII",
    "aliases": ["ethereum"]
  }
}

Error: String does not match pattern "^#[0-9A-Fa-f]{6}$"Fix: Use only valid hexadecimal characters (0-9, A-F):

"hex": "#88AAF1"

Duplicate Aliases in Same Entry

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

Error: Array items must be unique (uniqueItems: true)Fix: Remove duplicates:

"aliases": ["ethereum", "eth"]

Additional Properties

// ❌ Invalid
{
  "Ethereum": {
    "hex": "#88AAF1",
    "aliases": ["ethereum"],
    "website": "https://ethereum.org"
  }
}

Error: Additional properties not allowed (additionalProperties: false)Fix: Remove extra properties:

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

Incorrect Hex Code Length

// ❌ Invalid - Too short
{
  "Ethereum": {
    "hex": "#88AAF",
    "aliases": ["ethereum"]
  }
}

// ❌ Invalid - Too long (8 characters)
{
  "Ethereum": {
    "hex": "#88AAF1FF",
    "aliases": ["ethereum"]
  }
}

Error: String does not match pattern "^#[0-9A-Fa-f]{6}$"Fix: Use exactly 6 hexadecimal characters:

"hex": "#88AAF1"

Testing Validation Locally

Before submitting a pull request, validate your changes locally to catch errors early.

Using Command Line Tools

# Install ajv-cli globally
npm install -g ajv-cli

# Validate color-palettes.json against schema.json
ajv validate -s schema.json -d color-palettes.json

# Install jsonschema
pip install jsonschema

# Create validation script
python validate.py

import json
from jsonschema import validate, ValidationError

# Load schema
with open('schema.json', 'r') as f:
    schema = json.load(f)

# Load color palettes
with open('color-palettes.json', 'r') as f:
    data = json.load(f)

# Validate
try:
    validate(instance=data, schema=schema)
    print("✅ Validation successful!")
except ValidationError as e:
    print(f"❌ Validation failed: {e.message}")

IDE Integration

Modern code editors can validate JSON files against schemas automatically:

{
  "json.schemas": [
    {
      "fileMatch": ["color-palettes.json"],
      "url": "./schema.json"
    }
  ]
}

{
  "$schema": "./schema.json",
  "Ethereum": {
    "hex": "#88AAF1",
    "aliases": ["ethereum", "eth"]
  }
}

Validation Best Practices

Validate Early

Test your changes locally before creating a pull request to catch errors immediately.

Use Schema-Aware Editors

Configure your IDE to validate against the schema for real-time feedback.

Check Alias Conflicts

Search the existing file for aliases before adding new ones to avoid conflicts.

Follow Patterns

Look at existing entries as examples when adding new protocols.

The automated CI validation is the final gate before merging. All validation checks must pass for a pull request to be approved.

Getting Started

Using Color Palettes

Schema

Contributing

Reference

JSON Schema Definition

Validation Rules Breakdown

Root Level Validation

Protocol Name Pattern

Hex Color Validation

Aliases Array Validation

Required Properties

Additional Properties

Automated CI Validation

Validation Examples

Complete Valid Entry

Common Validation Errors

Testing Validation Locally

Using Command Line Tools

IDE Integration

Validation Best Practices

Validate Early

Use Schema-Aware Editors

Check Alias Conflicts

Follow Patterns

​JSON Schema Definition

​Validation Rules Breakdown

​Root Level Validation

​Protocol Name Pattern

​Hex Color Validation

​Aliases Array Validation

​Required Properties

​Additional Properties

​Automated CI Validation

​Validation Examples

​Complete Valid Entry

​Common Validation Errors

​Testing Validation Locally

​Using Command Line Tools

​IDE Integration

​Validation Best Practices

Validate Early

Use Schema-Aware Editors

Check Alias Conflicts

Follow Patterns

JSON Schema Definition

Validation Rules Breakdown

Root Level Validation

Protocol Name Pattern

Hex Color Validation

Aliases Array Validation

Required Properties

Additional Properties

Automated CI Validation

Validation Examples

Complete Valid Entry

Common Validation Errors

Testing Validation Locally

Using Command Line Tools

IDE Integration

Validation Best Practices