Skip to content

System-Wide Naming, Taxonomy, and Structural Vocabulary Governance: Best Practices

Introduction

System-wide taxonomy governance is the foundation of all other best practices. Without consistent naming, taxonomy, and structural vocabulary, systems become mentally intractable, cross-system integration fails, and operational entropy increases. This guide establishes the "lingua franca" that enables all other practices.

What This Guide Covers: - Enterprise-wide naming conventions - Domain taxonomy and service vocabulary - Folder and repository structure standards - Database and table naming invariants - Schema and metadata naming standards - Geospatial layer naming contracts - Cross-language consistency rules (Python, Go, Rust) - Multi-cluster resource naming patterns

Prerequisites: - Understanding of distributed systems architecture - Familiarity with multiple programming languages - Experience with multi-environment deployments

Related Documents: This document is foundational to: - Data Lineage Contracts - Lineage clarity depends on consistent naming - Secure-by-Design Polyglot - Security policies reference taxonomy - Unified Observability Architecture - Metrics and logs use taxonomy - DX Architecture and Golden Paths - Developer tools enforce taxonomy

The Philosophy of System Taxonomy

Why Taxonomy Matters

Cognitive Load Reduction: Consistent naming reduces mental translation overhead.

Example: 

# Inconsistent: High cognitive load
def get_user_data():  # Python
func GetUserData()    # Go
fn get_user_data()    # Rust

# Consistent: Low cognitive load
def get_user_data():  # Python
func GetUserData()    # Go (exported)
fn get_user_data()    # Rust

Cross-System Integration: Consistent naming enables seamless integration.

Example: 

# Service naming enables auto-discovery
services:
  user-service:      # Consistent pattern
  order-service:    # Consistent pattern
  payment-service:  # Consistent pattern

Operational Clarity: Consistent naming makes operations predictable.

Example: 

# Predictable resource names
kubectl get pods -l app=user-service
kubectl get svc -l app=order-service

Taxonomy Principles

  1. Consistency First: Same concept, same name everywhere
  2. Clarity Over Brevity: Long names are better than ambiguous short ones
  3. Domain-Driven: Names reflect business domains
  4. Language-Agnostic: Core concepts transcend language syntax
  5. Hierarchical: Names form hierarchies (domain → service → resource)
  6. Versioned: Taxonomy evolves with versioning

Enterprise-Wide Naming Conventions

Core Naming Patterns

Pattern: {domain}-{component}-{resource}

Examples: 

user-service-api
order-service-db
payment-service-cache

Domain Taxonomy

Domains: - user: User management, authentication, authorization - order: Order processing, fulfillment - payment: Payment processing, billing - inventory: Inventory management - analytics: Analytics and reporting - geospatial: Geospatial data and processing

Domain Rules: - Domains are business capabilities - Domains are stable (change infrequently) - Domains map to team ownership

Service Vocabulary

Service Types: - api: REST/GraphQL API service - worker: Background job processor - scheduler: Scheduled task runner - ingest: Data ingestion service - transform: Data transformation service - query: Query service - gateway: API gateway

Service Naming Pattern: {domain}-{type}

Examples: 

user-api
order-worker
payment-gateway
analytics-query
geospatial-ingest

Component Naming

Components: - db: Database - cache: Cache (Redis) - queue: Message queue - storage: Object storage - search: Search index - ml: Machine learning model

Component Naming Pattern: {domain}-{component}

Examples: 

user-db
order-cache
payment-queue
analytics-storage

Folder and Repository Structure Standards

Repository Naming

Pattern: {organization}-{domain}-{type}

Examples: 

org-user-service
org-order-api
org-analytics-pipeline

Repository Structure

Standard Structure: 

{repo-name}/
├── .github/
│   └── workflows/
├── src/
│   └── {domain}/
│       ├── __init__.py
│       ├── main.py
│       ├── handlers/
│       ├── services/
│       ├── models/
│       └── utils/
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── docs/
├── config/
│   ├── base/
│   └── environments/
├── .pre-commit-config.yaml
├── Makefile
├── pyproject.toml
└── README.md

Folder Naming Conventions

Folders: - src/: Source code - tests/: Test code - docs/: Documentation - config/: Configuration files - scripts/: Utility scripts - deploy/: Deployment manifests

Database and Table Naming Invariants

Database Naming

Pattern: {domain}_{environment}

Examples: 

user_prod
order_staging
analytics_dev

Schema Naming

Pattern: {domain} or {domain}_{purpose}

Examples: 

user
order
analytics
analytics_warehouse

Table Naming

Pattern: {domain}_{entity}_{type}

Entity Types: - No suffix: Primary entity table - _log: Audit/log table - _history: Historical data table - _cache: Cache table - _temp: Temporary table

Examples: 

user_account
user_session
order_item
order_log
payment_transaction
payment_transaction_history

Column Naming

Pattern: {entity}_{attribute} or {attribute}

Examples: 

user_id
user_email
user_created_at
order_id
order_total
order_status

Index Naming

Pattern: idx_{table}_{columns}

Examples: 

idx_user_account_email
idx_order_item_order_id
idx_payment_transaction_user_id

Constraint Naming

Pattern: {type}_{table}_{columns}

Types: - pk_: Primary key - fk_: Foreign key - uk_: Unique key - ck_: Check constraint

Examples: 

pk_user_account_id
fk_order_item_order_id
uk_user_account_email
ck_order_item_quantity_positive

Schema and Metadata Naming Standards

Schema Versioning

Pattern: v{major}.{minor}.{patch}

Examples: 

v1.0.0
v1.1.0
v2.0.0

Metadata Naming

Pattern: {domain}_{entity}_{metadata_type}

Metadata Types: - _schema: Schema definition - _contract: Data contract - _lineage: Lineage metadata - _provenance: Provenance metadata

Examples: 

user_account_schema
order_item_contract
payment_transaction_lineage
analytics_report_provenance

Geospatial Layer Naming Contracts

Layer Naming

Pattern: {domain}_{feature}_{resolution}_{style}

Components: - domain: Business domain - feature: Feature type (roads, buildings, etc.) - resolution: Zoom level or scale - style: Visual style (dark, light, etc.)

Examples: 

geospatial_roads_z12_dark
geospatial_buildings_z14_light
geospatial_boundaries_z10_default

Geometry Naming

Pattern: {entity}_geom or {entity}_geometry

Examples: 

user_location_geom
order_delivery_area_geometry
analytics_region_boundary_geom

Spatial Index Naming

Pattern: idx_{table}_{column}_spatial

Examples: 

idx_user_location_geom_spatial
idx_order_delivery_area_geometry_spatial

Cross-Language Consistency Rules

Python Naming

Conventions: - Modules: snake_case - Classes: PascalCase - Functions: snake_case - Constants: UPPER_SNAKE_CASE - Private: _leading_underscore

Examples: 

# Module
import user_service

# Class
class UserService:
    pass

# Function
def get_user_data():
    pass

# Constant
MAX_RETRIES = 3

# Private
def _internal_helper():
    pass

Go Naming

Conventions: - Packages: lowercase - Exported: PascalCase - Unexported: camelCase - Constants: PascalCase or UPPER_SNAKE_CASE

Examples: 

// Package
package userservice

// Exported
type UserService struct {}

func GetUserData() {}

// Unexported
type userService struct {}

// Constant
const MaxRetries = 3

Rust Naming

Conventions: - Modules: snake_case - Types: PascalCase - Functions: snake_case - Constants: UPPER_SNAKE_CASE - Private: Module-level privacy

Examples: 

// Module
mod user_service;

// Type
struct UserService {}

// Function
fn get_user_data() {}

// Constant
const MAX_RETRIES: u32 = 3;

Cross-Language Mapping

Core Concepts (Language-Agnostic): - UserService: Service name - get_user_data: Function name - UserAccount: Entity name - user_id: Identifier name

Language-Specific Adaptations: - Python: user_service, get_user_data, UserAccount, user_id - Go: userservice, GetUserData, UserAccount, UserID - Rust: user_service, get_user_data, UserAccount, user_id

Multi-Cluster Resource Naming Patterns

Kubernetes Resource Naming

Pattern: {domain}-{component}-{instance}

Examples: 

user-api-prod
order-worker-staging
payment-gateway-dev

Namespace Naming

Pattern: {environment} or {domain}-{environment}

Examples: 

prod
staging
dev
user-prod
order-staging

Label Naming

Standard Labels: - app: Application name - component: Component type - environment: Environment name - version: Version tag - domain: Business domain

Examples: 

labels:
  app: user-service
  component: api
  environment: prod
  version: v1.2.3
  domain: user

Service Account Naming

Pattern: {domain}-{component}-sa

Examples: 

user-api-sa
order-worker-sa
payment-gateway-sa

Taxonomy Enforcement

Automated Enforcement

Linting Rules: 

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: naming-check
        name: Check naming conventions
        entry: scripts/check_naming.py
        language: system

Validation Script: 

# scripts/check_naming.py
import re
from pathlib import Path

def validate_naming(file_path: Path):
    """Validate naming conventions"""
    # Check service names
    # Check database names
    # Check table names
    # Check function names
    pass

CI/CD Integration

GitHub Actions: 

# .github/workflows/naming-check.yml
name: Naming Convention Check
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check naming
        run: |
          python scripts/check_naming.py

Taxonomy Evolution

Versioning Taxonomy

Taxonomy Versions: - v1.0.0: Initial taxonomy - v1.1.0: Additions (backward compatible) - v2.0.0: Breaking changes

Migration Strategy

Migration Process: 1. Document changes 2. Update tooling 3. Migrate codebases 4. Update documentation

Integration with Other Practices

Data Lineage Integration

Lineage Naming: - Uses taxonomy for entity names - Enables lineage clarity - See: Data Lineage Contracts

Security Integration

Security Naming: - Uses taxonomy for resource names - Enables policy clarity - See: Secure-by-Design Polyglot

Observability Integration

Observability Naming: - Uses taxonomy for metric names - Enables dashboard clarity - See: Unified Observability Architecture

DX Integration

DX Naming: - Uses taxonomy for tooling - Enables developer clarity - See: DX Architecture and Golden Paths

Cross-Document Architecture

graph TB
    subgraph Taxonomy["System Taxonomy Governance<br/>(This Document)"]
        Naming["Naming Conventions"]
        Domain["Domain Taxonomy"]
        Structure["Structure Standards"]
    end

    subgraph Lineage["Data Lineage Contracts"]
        Contracts["Data Contracts"]
        Provenance["Provenance"]
    end

    subgraph Security["Secure-by-Design"]
        Policies["Security Policies"]
        RBAC["RBAC/ABAC"]
    end

    subgraph Observability["Unified Observability"]
        Metrics["Metrics"]
        Logs["Logs"]
        Traces["Traces"]
    end

    subgraph DX["DX Architecture"]
        Tools["Developer Tools"]
        Workflows["Workflows"]
    end

    Naming --> Contracts
    Domain --> Provenance
    Structure --> Policies
    Naming --> Metrics
    Domain --> Logs
    Structure --> Tools

    style Taxonomy fill:#e1f5ff
    style Lineage fill:#fff4e1
    style Security fill:#ffebee
    style Observability fill:#e8f5e9
    style DX fill:#f3e5f5

Checklists

Taxonomy Compliance Checklist

  • All services follow naming pattern
  • All databases follow naming pattern
  • All tables follow naming pattern
  • All functions follow naming pattern
  • All repositories follow structure standard
  • All Kubernetes resources follow naming pattern
  • All geospatial layers follow naming pattern
  • Cross-language consistency verified

Taxonomy Review Checklist

  • Taxonomy documented
  • Tooling updated
  • Codebases migrated
  • Documentation updated
  • CI/CD checks enabled
  • Team trained

Anti-Patterns

Naming Anti-Patterns

Inconsistent Naming: 

# Bad: Inconsistent
def getUser(): pass
def get_user(): pass
def GetUser(): pass

# Good: Consistent
def get_user(): pass

Ambiguous Names: 

# Bad: Ambiguous
def process(): pass
def handle(): pass

# Good: Clear
def process_order(): pass
def handle_payment(): pass

Magic Numbers/Strings: 

# Bad: Magic values
if status == "A": pass

# Good: Named constants
if status == OrderStatus.ACTIVE: pass

See Also

This guide establishes the foundational taxonomy that enables all other best practices. Start with naming conventions, extend to structure standards, and continuously enforce consistency across all systems.