Conventions
Summary
| Category | Standard |
|---|---|
| Encoding | UTF-8 |
| Time | ISO 8601 with timezone |
| Country Codes | ISO alpha-2 |
| Naming (API) | camelCase |
| Naming (DB) | snake_case |
| Boolean | true / false |
| Null Handling | Avoid null, prefer omission |
| Numbers | Dot as decimal separator |
| Language Tags | BCP 47 |
1. Character Encoding
Standard: UTF-8 (mandatory)
All code, data storage, and data exchange must use UTF-8 encoding.
Rules: - UTF-8 is mandatory across all systems - Exceptions must be explicitly justified and documented
2. Date and Time
Standard: ISO 8601
Format: YYYY-MM-DDTHH:mm:ss±HH:MM or YYYY-MM-DDTHH:mm:ssZ
Rules
- Preferred format is UTC (
Z) - All timestamps must be in UTC (or include a timezone)
- Do not use daylight saving time or similar for storing data
- Apply timezone shifts only during rendering
Examples
- 2026-03-30T14:23:00Z
- 2026-03-30T16:23:00+02:00
- Zurich, half past two in January:
- 2026-01-15T13:30:00Z
- 2026-01-15T14:30:00+01:00
Time Zone Definition
Standard: IANA Time Zone Database (TZDB)
Use IANA time zone identifiers for all timezone-related configurations.
Examples
- Europe/Zurich
- Europe/Berlin
- UTC
Rules
- Always use IANA time zone names (e.g.
Europe/Zurich) -
Do not use ambiguous abbreviations:
-
❌ CET
- ❌ CEST
-
❌ PST
-
Time zone must be explicitly defined when relevant (e.g. scheduling, UI display)
- Backend systems should internally use UTC where possible
- Time zone conversion should happen at system boundaries (e.g. UI, reporting)
Rationale
- Avoids ambiguity caused by daylight saving time
- Ensures compatibility across systems, APIs, and databases
- Standard used by most modern platforms (Linux, Java, Python, JavaScript)
3. Country Codes
Standard: ISO 3166-1 alpha-2
Examples
- CH (Switzerland)
- DE (Germany)
- US (United States)
Rationale
- Widely used across APIs and systems
- Better compatibility than alpha-3 codes
4. Language and Locale
Standard: BCP 47
Examples
- en-US
- de-CH
5. Naming Conventions
Consistency is mandatory across all layers.
API / JSON
Use camelCase
Examples: - createdAt - isActive - userId
Database (SQL)
Use snake_case
Examples: - created_at - is_active - user_id
Constants
Use UPPER_CASE
Example: - MAX_RETRIES
File Names
Use kebab-case or snake_case
Examples: - user-service.ts - user_repository.py
Additional Rules
- Avoid abbreviations (except common ones like
id,url) -
Boolean fields must be readable:
-
✅ isActive, hasPermission
-
❌ active, flag1
-
Standard timestamp fields:
-
createdAt
- updatedAt
- deletedAt
6. Boolean Values
Use native boolean values: - true - false
Do not use:
- 0 / 1
- "yes" / "no"
7. Null Handling
Null handling must be consistent and intentional.
General Rule
Avoid null where possible.
Required Fields
- Must never be null
- Must be validated
Optional Fields
| Type | Representation |
|---|---|
| Missing value | omit only (null only if explicitly required) |
| Empty string | "" |
| List | [] (never null) |
| Object | {} (if applicable) |
Preferred Approach
Omit optional fields instead of setting them to null.
Preferred:
{
"firstName": "Max"
}
Avoid:
{
"firstName": "Max",
"middleName": null
}
Critical Rule
Do not mix null and empty values for the same meaning.
Each semantic state must have exactly one representation.
8. Numeric Values
- Use
.as decimal separator - Do not use thousands separators
Examples
- ✅ 1234.56
- ❌ 1,234.56
- ❌ 1'234.56
9. General Principles
- Prefer explicitness over ambiguity
- Enforce consistency across all services
- Validate data at system boundaries
- Document any exceptions clearly