Principle:OpenHands OpenHands Name Validation
| Knowledge Sources | |
|---|---|
| Domains | Organization_Management, Multi_Tenancy |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Validating resource name uniqueness before creation prevents duplicate-name conflicts and ensures each organization occupies a distinct namespace.
Description
The Name Validation principle enforces a uniqueness constraint pattern in which the system queries existing database state to confirm that no resource with the proposed name already exists before allowing the creation to proceed. In the context of organization onboarding, this means checking the organization table for a matching name prior to inserting a new row. If a collision is detected, the operation is rejected immediately with a descriptive error, avoiding partial resource creation that would need to be rolled back later.
This pattern is essential in multi-tenant systems where organization names serve as human-readable identifiers and may appear in URLs, API keys, or billing records. Allowing duplicates would create ambiguity in routing, access control, and audit trails.
Usage
Apply this principle whenever a new named resource is being created in a system that requires unique identifiers across a shared namespace. Typical scenarios include:
- Creating a new organization during the onboarding workflow
- Renaming an existing organization
- Any operation where a user-supplied name must be globally unique within its scope
Theoretical Basis
The uniqueness constraint pattern follows a check-then-act sequence:
# Pseudocode for uniqueness validation
def validate_name_uniqueness(name: str) -> None:
existing = database.query(Resource).filter_by(name=name).first()
if existing is not None:
raise NameAlreadyExistsError(f"Resource with name '{name}' already exists")
# Proceed with creation
Key considerations:
- Race conditions: In concurrent environments, a database-level UNIQUE constraint should complement the application-level check to handle time-of-check-to-time-of-use (TOCTOU) races.
- Case sensitivity: Depending on requirements, the comparison may need to be case-insensitive (e.g., comparing lowercased names).
- Early failure: By validating before allocating any dependent resources (LLM keys, billing accounts), the system avoids costly cleanup on name conflicts.