Best Practices: Naming Conventions in Zixi
Zixi component names including channels, inputs, outputs, targets, adaptive groups, and ZEN Master resources, are used internally in configuration files, API calls, log entries, and URL-based endpoints. Using special characters in these names can cause unexpected failures that are difficult to diagnose, particularly in automation workflows, REST API integrations, and scripted monitoring pipelines.
Use only alphanumeric characters, hyphens, underscores and periods for naming conventions
What to Avoid
Avoid all characters outside the safe set described above.
Common problem characters include:
Character | Example | Why It's Problematic |
|---|---|---|
Spaces | My Channel | Breaks URL parsing; must be percent-encoded as %20, which causes issues in API calls and log searches |
Forward slash | BBC/HD | Interpreted as a path separator in URLs and file systems |
Backslash | BBC\HD | Causes parsing failures in JSON and config files |
Ampersand | Sport&News | Reserved in URLs; interpreted as a query string delimiter |
Hash | Channel#1 | Interpreted as a URL fragment identifier; truncates API requests |
Question mark | Test?HD | Interpreted as the start of a URL query string |
Percent | 50%Feed | Triggers percent-encoding interpretation in URLs |
At sign | feed@site | Confused with authentication syntax in URLs |
Brackets | [HD]Feed | Can break shell scripts, JSON parsing, and regex-based log filters |
Parentheses | Feed(Backup) | Can interfere with scripting, CLI tools, and API parsing |
Quotes | "Primary" | Breaks JSON serialization and command-line argument handling |
Colons | BBC:HD | Reserved in URIs and can interfere with host:port parsing |
Commas | CH1,CH2 | Often used as delimiters in API parameters; can split values unexpectedly |
Safe Characters
Character type | Allowed | Notes |
|---|---|---|
Letters | A–Z, a–z | Both upper and lower case |
Numbers | 0–9 | |
Hyphen | - | Good for word separation: bbc-hd-primary |
Underscore | _ | Good for grouping segments: bbc_hd_primary |
Period | . | Useful for versioning or hierarchy: bbc.hd.primary |
Recommended Naming Patterns
Use a consistent naming convention across your deployment. A structured pattern makes names predictable, searchable and automation friendly.
Suggested format:
Examples:
Keep names concise and machine-readable.
Renaming Existing Components
If you have existing resources with non-compliant names, plan renames carefully:
- Audit first: Check your lists in ZEN Master or Broadcaster and identify all non-compliant names.
- Check dependencies: Before renaming, verify whether the resource name is referenced in API integrations, monitoring scripts, or external systems (encoders, decoders, automation).
- Rename during a maintenance window: Renaming an active channel or output will interrupt the stream. Always rename during scheduled downtime.