Setup Data Naming Convention Proposal¶

Overview¶

This document proposes a unified naming convention for all setup data files in the BSS (Battery Swap Service) ecosystem, ensuring consistency, clarity, and scalability across different service models, regions, and versions.

Core Naming Attributes¶

Based on analysis of existing files and future requirements, the naming convention includes these key attributes:

1. Service Model (`{service}`)¶

bss - Battery Swap Service
fcs - Fleet Charging Service (future)
ems - Energy Management Service (future)

2. Entity Type (`{entity}`)¶

template - ServicePlanTemplate definitions
plan - ServicePlan instances
services - Service definitions
bundles - ServiceBundle configurations
terms - CommonTerms definitions
accounts - Service/Payment account instances
agent-config - Agent configurations
agent-versions - Version mappings

3. Product Description (`{product}`)¶

monthly-flatfee - Monthly unlimited flat fee model
weekly-freedom - Weekly freedom package
daily-tourist - Daily tourist package
economy-count - Economy package with count-based billing
premium-unlimited - Premium unlimited access

4. Region/Location (`{location}`)¶

nairobi - Nairobi, Kenya
kenya - Kenya national
mombasa - Mombasa, Kenya (future)
kampala - Kampala, Uganda (future)
lagos - Lagos, Nigeria (future)

5. Version (`{version}`)¶

v1, v2, v3 - Major versions
v1-1, v2-3 - Minor versions
Date format YYYY-MM for time-based versions

6. Instance Identifier (`{instance}`)¶

plan1, plan2 - For plan instances
customer001, customer002 - For customer-specific instances
config001, config002 - For configuration instances

Proposed Naming Patterns¶

Pattern 1: Service Model-Wide Resources¶

{service}-{entity}-{location}-{version}.json

Examples: - bss-services-kenya-v2.json (replaces bss-services.json) - bss-bundles-kenya-v2.json (replaces bss-service-bundles.json) - bss-terms-kenya-v2.json (replaces bss-common-terms.json) - bss-agent-config-v2.json (current: good as-is) - bss-agent-versions.json (replaces agent-versions.json)

Pattern 2: ServicePlanTemplate Files¶

{service}-template-{product}-{location}-{version}.json

Examples: - bss-template-monthly-flatfee-nairobi-v2.json (replaces nairobi-monthly-flatfee-v2.json) - bss-template-weekly-freedom-nairobi-v2.json (replaces nairobi-weekly-freedom-v2.json) - bss-template-daily-tourist-nairobi-v2.json (future) - bss-template-economy-count-mombasa-v1.json (future)

Pattern 3: ServicePlan Instance Files¶

{service}-plan-{product}-{location}-{version}-{instance}.json

Examples: - bss-plan-monthly-flatfee-nairobi-v2-plan1.json (replaces nairobi-monthly-flatfee-v2-plan1.json) - bss-plan-weekly-freedom-nairobi-v2-plan1.json (replaces nairobi-weekly-freedom-v2-plan1.json) - bss-plan-monthly-flatfee-nairobi-v2-customer001.json (customer-specific)

Pattern 4: Account Instance Files¶

{service}-{account-type}-{product}-{location}-{version}-{instance}.json

Examples: - bss-service-account-freedom-nairobi-v2-plan1.json (replaces bss-service-account-v2.json) - bss-payment-account-monthly-nairobi-v2-customer001.json (replaces bss-payment-account-customer001.json)

JSON Object Description Convention¶

Internal Object Naming¶

Each JSON file should include a standardized description block:

{
  "_comment_file_info": "File naming convention metadata",
  "_meta": {
    "service_model": "bss",
    "entity_type": "template",
    "product_description": "monthly-flatfee",
    "location": "nairobi",
    "version": "v2",
    "instance": null,
    "filename_pattern": "{service}-{entity}-{product}-{location}-{version}.json"
  },

  "_comment_business_description": "ServicePlanTemplate for Nairobi Monthly Flat Fee BSS",
  "id": "bss-template-monthly-flatfee-nairobi-v2",
  "name": "Nairobi Monthly Flat Fee BSS Template v2",
  "description": "ServicePlanTemplate for Nairobi unlimited flat-fee battery swap service using BSS Agent v2"
}

Object ID Convention¶

Internal object IDs should follow the same pattern as filenames (without .json):

{
  "id": "bss-template-monthly-flatfee-nairobi-v2",
  "service_plan_id": "bss-plan-monthly-flatfee-nairobi-v2-plan1",
  "service_account_id": "bss-service-account-freedom-nairobi-v2-plan1",
  "payment_account_id": "bss-payment-account-monthly-nairobi-v2-customer001"
}

Migration Plan for Existing Files¶

Phase 1: Core Resource Files¶

bss-services.json → bss-services-kenya-v2.json
bss-service-bundles.json → bss-bundles-kenya-v2.json
bss-common-terms.json → bss-terms-kenya-v2.json
agent-versions.json → bss-agent-versions.json

Phase 2: Template Files¶

nairobi-monthly-flatfee-v2.json → bss-template-monthly-flatfee-nairobi-v2.json
nairobi-weekly-freedom-v2.json → bss-template-weekly-freedom-nairobi-v2.json

Phase 3: Instance Files¶

nairobi-monthly-flatfee-v2-plan1.json → bss-plan-monthly-flatfee-nairobi-v2-plan1.json
nairobi-weekly-freedom-v2-plan1.json → bss-plan-weekly-freedom-nairobi-v2-plan1.json
bss-service-account-v2.json → bss-service-account-freedom-nairobi-v2-plan1.json
bss-payment-account-customer001.json → bss-payment-account-monthly-nairobi-v2-customer001.json

Benefits of This Convention¶

1. Scalability¶

Clear patterns for adding new service models (FCS, EMS)
Easy to add new regions (Mombasa, Kampala, Lagos)
Consistent versioning across all entity types

2. Discoverability¶

Files sort logically by service model, then entity type
Easy to find related files (templates + plans + accounts)
Clear hierarchy from general (services) to specific (plan instances)

3. Consistency¶

Same attribute order across all file types
Predictable naming for developers and tools
Internal object IDs match filename patterns

4. Maintenance¶

Version tracking across related files
Clear separation of concerns by entity type
Easy to identify customer-specific vs. template data

File Organization Structure¶

setup-data/
├── bss-agent-versions.json
├── bss-agent-config-v2.json
├── bss-services-kenya-v2.json
├── bss-bundles-kenya-v2.json
├── bss-terms-kenya-v2.json
├── bss-template-monthly-flatfee-nairobi-v2.json
├── bss-template-weekly-freedom-nairobi-v2.json
├── bss-plan-monthly-flatfee-nairobi-v2-plan1.json
├── bss-plan-weekly-freedom-nairobi-v2-plan1.json
├── bss-service-account-freedom-nairobi-v2-plan1.json
├── bss-payment-account-monthly-nairobi-v2-customer001.json
└── bss-payment-account-weekly-nairobi-v2-customer002.json

Future Extensions¶

Multi-Region Support¶

bss-services-eastafrica-v3.json (regional services)
bss-template-premium-unlimited-kampala-v1.json (new city)

Multi-Service Model Support¶

fcs-services-kenya-v1.json (Fleet Charging Service)
ems-template-grid-management-nairobi-v1.json (Energy Management)

Time-Based Versioning¶

bss-template-seasonal-special-nairobi-2025-12.json (holiday packages)
bss-services-kenya-2025-Q2.json (quarterly updates)

This convention provides a robust foundation for organizing setup data that will scale with the platform's growth while maintaining clarity and consistency across all file types.