Skip to content

Setup Data Metadata Convention Applied

Summary

Successfully applied filename and JSON object metadata conventions to all files in the setup-data directory following the established naming convention proposal.

Changes Applied

1. Standardized _meta Blocks Added

Every JSON file now includes: 

{
  "_comment_file_info": "File naming convention metadata",
  "_meta": {
    "service_model": "bss",
    "entity_type": "[entity]",
    "product_description": "[product]", // when applicable
    "location": "[location]",
    "version": "v2",
    "instance": "[instance]", // when applicable
    "filename_pattern": "[pattern]"
  }
}

2. Updated Object IDs to Match Filename Patterns

Service-wide Resources ({service}-{entity}-{location}-{version}.json)

  • bss-services.json: Added metadata for Kenya services v2
  • bss-service-bundles.json: Added metadata for Kenya bundles v2
  • bss-common-terms.json: Added metadata for Kenya terms v2
  • bss-agent-config-v2.json: Added metadata for global agent config v2
  • agent-versions.json: Added metadata for global agent versions

ServicePlanTemplate Files ({service}-template-{product}-{location}-{version}.json)

  • nairobi-monthly-flatfee-v2.json:
  • Updated ID: template-nairobi-monthly-flatfee-v2 → bss-template-monthly-flatfee-nairobi-v2
  • Added full metadata block
  • nairobi-weekly-freedom-v2.json:
  • Updated ID: template-nairobi-weekly-freedom-v2 → bss-template-weekly-freedom-nairobi-v2
  • Added full metadata block

ServicePlan Instance Files ({service}-plan-{product}-{location}-{version}-{instance}.json)

  • nairobi-monthly-flatfee-v2-plan1.json:
  • Updated ID: plan-nairobi-customer001-001 → bss-plan-monthly-flatfee-nairobi-v2-plan1
  • Updated template reference: template-nairobi-monthly-flatfee-v2 → bss-template-monthly-flatfee-nairobi-v2
  • Updated account references to new IDs
  • nairobi-weekly-freedom-v2-plan1.json:
  • Updated ID: plan-nairobi-customer002-001 → bss-plan-weekly-freedom-nairobi-v2-plan1
  • Updated template reference: template-nairobi-weekly-freedom-v2 → bss-template-weekly-freedom-nairobi-v2
  • Updated account references to new IDs

Account Instance Files ({service}-{account-type}-{product}-{location}-{version}-{instance}.json)

  • bss-service-account-v2.json:
  • Updated ID: svc-acc-bss-freedom-v2 → bss-service-account-freedom-nairobi-v2-plan1
  • Added metadata for freedom product, Nairobi location
  • bss-payment-account-v2.json:
  • Updated ID: pay-acc-customer002-001 → bss-payment-account-weekly-nairobi-v2-customer002
  • Added metadata for weekly product, customer002 instance
  • bss-payment-account-customer001.json:
  • Updated ID: pay-acc-customer001-001 → bss-payment-account-monthly-nairobi-v2-customer001
  • Added metadata for monthly product, customer001 instance

3. Cross-Reference Updates

Updated all internal references to use the new consistent ID patterns: - ServicePlan instances now reference the correct template IDs - ServicePlan instances reference the correct account IDs - All IDs follow the filename pattern convention

Benefits Achieved

✅ Consistency

  • All object IDs match their filename patterns
  • Standardized metadata across all files
  • Predictable naming for developers and tools

✅ Discoverability

  • Files can be located by service model, entity type, product, location
  • Metadata enables automated validation and tooling
  • Clear hierarchy from general (services) to specific (plan instances)

✅ Scalability

  • Ready for new service models (FCS, EMS)
  • Easy to add new regions (Mombasa, Kampala, Lagos)
  • Consistent patterns for new product types

✅ Validation Ready

  • Filename-metadata validator can now verify consistency
  • Build-time validation possible with provided validation tools
  • Automated migration scripts can be generated

Next Steps

  1. Filename Updates: Consider renaming physical files to match the new ID patterns:
  2. nairobi-monthly-flatfee-v2.json → bss-template-monthly-flatfee-nairobi-v2.json
  3. nairobi-weekly-freedom-v2.json → bss-template-weekly-freedom-nairobi-v2.json
  4. nairobi-monthly-flatfee-v2-plan1.json → bss-plan-monthly-flatfee-nairobi-v2-plan1.json
  5. nairobi-weekly-freedom-v2-plan1.json → bss-plan-weekly-freedom-nairobi-v2-plan1.json
  6. bss-services.json → bss-services-kenya-v2.json
  7. bss-service-bundles.json → bss-bundles-kenya-v2.json
  8. bss-common-terms.json → bss-terms-kenya-v2.json
  9. agent-versions.json → bss-agent-versions.json
  10. bss-service-account-v2.json → bss-service-account-freedom-nairobi-v2-plan1.json
  11. bss-payment-account-v2.json → bss-payment-account-weekly-nairobi-v2-customer002.json

  12. bss-payment-account-customer001.json → bss-payment-account-monthly-nairobi-v2-customer001.json

  13. Validation: Run validation tools to ensure filename-metadata consistency

  14. Update References: Check if any external files reference the old IDs and update them

Files Modified

  • ✅ agent-versions.json
  • ✅ bss-agent-config-v2.json
  • ✅ bss-common-terms.json
  • ✅ bss-payment-account-customer001.json
  • ✅ bss-payment-account-v2.json
  • ✅ bss-service-account-v2.json
  • ✅ bss-service-bundles.json
  • ✅ bss-services.json
  • ✅ nairobi-monthly-flatfee-v2-plan1.json
  • ✅ nairobi-monthly-flatfee-v2.json
  • ✅ nairobi-weekly-freedom-v2-plan1.json
  • ✅ nairobi-weekly-freedom-v2.json

Total: 12 files updated with standardized metadata and consistent ID patterns