AllenNeuralDynamics / AllenNeuralDynamics/aind-file-standards

Allow timezone-aware information in filenames

Ouverte
#50 2 commentaires 0 réactions 2 personnes assignées Réclamée par @saskiad Voir sur GitHub
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.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.