AllenNeuralDynamics / AllenNeuralDynamics/aind-file-standards
Allow timezone-aware information in filenames
- Langage dominant
- Aucune donnée de langage
- Étoiles
- 0
- Forks
- 0
- Métriques de merge des PR
- Aucune PR mergée en 30 j
Description
## Summary
This proposal suggests revising the AIND file-naming specification to explicitly allow timezone offset information in datetime components of file names, in accordance with ISO 8601.
The affected standard is the **AIND File Standards – Core Standards**, specifically the section governing datetime formatting in file names.
---
## Motivation
The current specification prohibits the inclusion of timezone offset information in file names. This restriction introduces ambiguity and information loss, and has recently surfaced as a practical issue in downstream data interpretation and tooling, as highlighted in discussions initiated by @dougollerenshaw.
Disallowing offsets creates uncertainty about what a datetime in a file name actually represents, complicating data exchange, long-term archiving, and interoperability across institutions and systems.
---
## Detailed Design
The proposal is to allow ISO 8601–inspired datetime strings **with timezone offsets** in file names. For example:
- `2025-03-01T14-32-10-08-00`
- `2025-03-01T22-32-10Z`
This change:
- Is parsable by std python methods
- Does not invalidate existing filenames that omit offsets
- Does not require changes to existing parsing logic if offsets are treated as optional
The proposal does **not** mandate offsets, but permits them as a valid and encouraged option.
---
## Drawbacks / Potential Impact (What can go wrong? Will it affect an existing standard?)
- Tools that strictly validate file names against the current specification may need minor updates to accept offsets.
- There is a possibility of increased filename variability, though this is already inherent in timestamp usage.
Importantly, this change does **not** break backward compatibility with existing files or standards-compliant tools that ignore offsets.
---
## Alternatives
1. Continue disallowing offsets and rely on external metadata (e.g., `aind-data-schema`) to infer offset information.
2. Require all datetimes in filenames to be expressed strictly in UTC (`Z`), eliminating offsets but enforcing a single global reference frame (Z).
Both alternatives either introduce information loss or impose stronger constraints than necessary.
---
## Unresolved Questions
- Should timezone offsets be optional or recommended?
- Should UTC (`Z`) be preferred when available?
- Are there any downstream consumers that strictly reject filenames containing offsets today?
---
## Stakeholders (Who should be involved/affected)
- AIND file standards maintainers
- AIND data schema maintainers
- Tooling and pipeline developers consuming AIND-formatted data
- External collaborators and institutions exchanging AIND datasets
Guide de contribution
Aucun guide de contribution indexé pour ce dépôt
Évaluation
Cette issue n'a pas encore été évaluée.