0
# Configuration Schema
1

2
Structured configuration classes that define the schema for Hydra's internal configuration. These dataclasses provide type safety and validation for Hydra's own configuration system, including job settings, runtime information, and framework-specific options.
3

4
## Capabilities
5

6
### Main Hydra Configuration
7

8
The primary configuration schema that encompasses all Hydra settings and behavior.
9

10
```python { .api }
11
@dataclass
12
class HydraConf:
13
    """Main Hydra configuration schema."""
14
    
15
    defaults: List[Any] = field(default_factory=lambda: [
16
        {"output": "default"},
17
        {"launcher": "basic"},
18
        {"sweeper": "basic"},
19
        {"help": "default"},
20
        {"hydra_help": "default"},
21
        {"hydra_logging": "default"},
22
        {"job_logging": "default"},
23
        {"callbacks": None},
24
        {"env": "default"},
25
    ])
26
    
27
    mode: Optional[RunMode] = None
28
    searchpath: List[str] = field(default_factory=list)
29
    run: RunDir = field(default_factory=RunDir)
30
    sweep: SweepDir = field(default_factory=SweepDir)
31
    hydra_logging: Dict[str, Any] = MISSING
32
    job_logging: Dict[str, Any] = MISSING
33
    sweeper: Any = MISSING
34
    launcher: Any = MISSING
35
    callbacks: Dict[str, Any] = field(default_factory=dict)
36
    help: HelpConf = field(default_factory=HelpConf)
37
    hydra_help: HydraHelpConf = field(default_factory=HydraHelpConf)
38
    output_subdir: Optional[str] = ".hydra"
39
    overrides: OverridesConf = field(default_factory=OverridesConf)
40
    job: JobConf = field(default_factory=JobConf)
41
    runtime: RuntimeConf = field(default_factory=RuntimeConf)
42
    verbose: Any = False
43
```
44

45
### Job Configuration
46

47
Configuration schema for individual job settings and metadata.
48

49
```python { .api }
50
@dataclass
51
class JobConf:
52
    """Job configuration and runtime information."""
53
    
54
    name: str = MISSING                    # Job name
55
    chdir: Optional[bool] = None           # Change to output directory
56
    override_dirname: str = MISSING        # Override-based directory name
57
    id: str = MISSING                      # Job ID in scheduling system
58
    num: int = MISSING                     # Job number in sweep
59
    config_name: Optional[str] = MISSING   # Config name used
60
    env_set: Dict[str, str] = field(default_factory=dict)    # Environment variables to set
61
    env_copy: List[str] = field(default_factory=list)       # Environment variables to copy
62
    config: JobConfig = field(default_factory=JobConfig)    # Job-specific config
63
    
64
    @dataclass
65
    class JobConfig:
66
        """Nested job configuration settings."""
67
        
68
        @dataclass
69
        class OverrideDirname:
70
            """Configuration for override dirname generation."""
71
            kv_sep: str = "="                    # Key-value separator
72
            item_sep: str = ","                  # Item separator  
73
            exclude_keys: List[str] = field(default_factory=list)  # Keys to exclude
74
        
75
        override_dirname: OverrideDirname = field(default_factory=OverrideDirname)
76
```
77

78
### Runtime Configuration
79

80
Configuration schema for runtime information populated by Hydra during execution.
81

82
```python { .api }
83
@dataclass
84
class RuntimeConf:
85
    """Runtime information populated during execution."""
86
    
87
    version: str = MISSING                          # Hydra version
88
    version_base: str = MISSING                     # Version base setting
89
    cwd: str = MISSING                              # Current working directory
90
    config_sources: List[ConfigSourceInfo] = MISSING # Config source information
91
    output_dir: str = MISSING                       # Output directory path
92
    choices: Dict[str, Any] = field(default_factory=dict)  # Composition choices
93

94
@dataclass
95
class ConfigSourceInfo:
96
    """Information about configuration sources."""
97
    
98
    path: str        # Source path
99
    schema: str      # Source schema/type
100
    provider: str    # Source provider
101
```
102

103
### Directory Configuration
104

105
Configuration schemas for output directory management.
106

107
```python { .api }
108
@dataclass
109
class RunDir:
110
    """Run output directory configuration."""
111
    dir: str = MISSING
112

113
@dataclass  
114
class SweepDir:
115
    """Sweep output directory configuration."""
116
    dir: str = MISSING      # Base sweep directory
117
    subdir: str = MISSING   # Job subdirectory pattern
118
```
119

120
### Help and Documentation Configuration
121

122
Configuration schemas for help system customization.
123

124
```python { .api }
125
@dataclass
126
class HelpConf:
127
    """Application help configuration."""
128
    app_name: str = MISSING    # Application name for help
129
    header: str = MISSING      # Help header text
130
    footer: str = MISSING      # Help footer text  
131
    template: str = MISSING    # Help template path
132

133
@dataclass
134
class HydraHelpConf:
135
    """Hydra help configuration."""
136
    hydra_help: str = MISSING  # Hydra help text
137
    template: str = MISSING    # Hydra help template path
138
```
139

140
### Override Configuration
141

142
Configuration schema for command-line and programmatic overrides.
143

144
```python { .api }
145
@dataclass
146
class OverridesConf:
147
    """Configuration overrides tracking."""
148
    hydra: List[str] = field(default_factory=list)  # Hydra config overrides
149
    task: List[str] = field(default_factory=list)   # Task config overrides
150
```
151

152
## Usage Examples
153

154
### Accessing Hydra Configuration
155

156
```python
157
from hydra import main
158
from hydra.core.hydra_config import HydraConfig
159
from omegaconf import DictConfig
160

161
@main(version_base=None, config_path="conf", config_name="config")
162
def my_app(cfg: DictConfig) -> None:
163
    # Access Hydra's internal configuration
164
    hydra_cfg = HydraConfig.get()
165
    
166
    # Job information
167
    print(f"Job name: {hydra_cfg.job.name}")
168
    print(f"Job ID: {hydra_cfg.job.id}")
169
    print(f"Output directory: {hydra_cfg.runtime.output_dir}")
170
    
171
    # Runtime information
172
    print(f"Hydra version: {hydra_cfg.runtime.version}")
173
    print(f"Original CWD: {hydra_cfg.runtime.cwd}")
174
    
175
    # Configuration choices
176
    print(f"Config choices: {hydra_cfg.runtime.choices}")
177
```
178

179
### Customizing Job Configuration
180

181
```python
182
# In hydra configuration file (config.yaml):
183
hydra:
184
  job:
185
    name: custom_job_name
186
    chdir: true  # Change to output directory
187
    env_set:
188
      CUDA_VISIBLE_DEVICES: "0,1"
189
      PYTHONPATH: "/custom/path"
190
    env_copy:
191
      - HOME
192
      - USER
193
```
194

195
### Customizing Output Directories
196

197
```python
198
# In hydra configuration file:
199
hydra:
200
  run:
201
    dir: ./outputs/${now:%Y-%m-%d}/${now:%H-%M-%S}
202
  
203
  sweep:
204
    dir: ./multirun/${now:%Y-%m-%d_%H-%M-%S}
205
    subdir: ${hydra.job.num}_${hydra.job.id}
206
  
207
  job:
208
    config:
209
      override_dirname:
210
        kv_sep: "="
211
        item_sep: ","
212
        exclude_keys: ["hydra.verbose"]
213
```
214

215
### Accessing Configuration Metadata
216

217
```python
218
from hydra import main
219
from hydra.core.hydra_config import HydraConfig
220
from omegaconf import DictConfig
221

222
@main(version_base=None, config_path="conf", config_name="config")  
223
def analyze_config(cfg: DictConfig) -> None:
224
    hydra_cfg = HydraConfig.get()
225
    
226
    # Analyze configuration sources
227
    print("Configuration sources:")
228
    for source in hydra_cfg.runtime.config_sources:
229
        print(f"  {source.provider}: {source.path} ({source.schema})")
230
    
231
    # Show applied overrides
232
    print("\nApplied overrides:")
233
    print(f"  Task: {hydra_cfg.overrides.task}")
234
    print(f"  Hydra: {hydra_cfg.overrides.hydra}")
235
    
236
    # Show composition choices
237
    print("\nComposition choices:")
238
    for key, value in hydra_cfg.runtime.choices.items():
239
        print(f"  {key}: {value}")
240
```
241

242
### Custom Help Configuration
243

244
```python
245
# In hydra configuration file:
246
hydra:
247
  help:
248
    app_name: "My Amazing App"
249
    header: |
250
      My Amazing App - A demonstration of Hydra configuration
251
      
252
      This application showcases advanced configuration management.
253
    footer: |
254
      For more information, visit: https://example.com
255
      
256
  hydra_help:
257
    template: |
258
      Hydra configuration help for My Amazing App
259
      
260
      Use --config-help to see available configurations
261
      Use --hydra-help to see this message
262
```
263

264
### Environment Variable Management
265

266
```python
267
from hydra import main
268
from hydra.core.hydra_config import HydraConfig
269
import os
270

271
@main(version_base=None, config_path="conf", config_name="config")
272
def check_environment(cfg: DictConfig) -> None:
273
    hydra_cfg = HydraConfig.get()
274
    
275
    # Check which environment variables were set
276
    print("Environment variables set by Hydra:")
277
    for key, value in hydra_cfg.job.env_set.items():
278
        current_value = os.getenv(key)
279
        print(f"  {key}: {current_value} (configured: {value})")
280
    
281
    # Check which environment variables were copied
282
    print("\nEnvironment variables copied:")
283
    for key in hydra_cfg.job.env_copy:
284
        value = os.getenv(key)
285
        print(f"  {key}: {value}")
286
```
287

288
### Programmatic Configuration Inspection
289

290
```python
291
from hydra.core.hydra_config import HydraConfig
292
from hydra.conf import HydraConf, JobConf, RuntimeConf
293
from omegaconf import OmegaConf
294

295
def inspect_hydra_config():
296
    """Inspect the current Hydra configuration."""
297
    
298
    if not HydraConfig.initialized():
299
        print("Hydra not initialized")
300
        return
301
    
302
    hydra_cfg = HydraConfig.get()
303
    
304
    # Convert to structured config for easier inspection
305
    structured_cfg = OmegaConf.structured(HydraConf)
306
    current_cfg = OmegaConf.merge(structured_cfg, hydra_cfg)
307
    
308
    print("Current Hydra Configuration:")
309
    print(f"  Mode: {current_cfg.mode}")
310
    print(f"  Search paths: {current_cfg.searchpath}")
311
    print(f"  Output subdir: {current_cfg.output_subdir}")
312
    print(f"  Verbose: {current_cfg.verbose}")
313
    
314
    # Job configuration
315
    print("\nJob Configuration:")
316
    job_cfg: JobConf = current_cfg.job
317
    print(f"  Name: {job_cfg.name}")
318
    print(f"  Change directory: {job_cfg.chdir}")
319
    print(f"  Override dirname: {job_cfg.override_dirname}")
320
    
321
    # Runtime configuration  
322
    print("\nRuntime Configuration:")
323
    runtime_cfg: RuntimeConf = current_cfg.runtime
324
    print(f"  Version: {runtime_cfg.version}")
325
    print(f"  CWD: {runtime_cfg.cwd}")
326
    print(f"  Output dir: {runtime_cfg.output_dir}")
327
```
328

329
### Configuration Schema Validation
330

331
```python
332
from hydra.conf import HydraConf, JobConf
333
from omegaconf import OmegaConf, ValidationError
334
from dataclasses import dataclass
335

336
def validate_custom_hydra_config(config_dict: dict) -> bool:
337
    """Validate configuration against Hydra schema."""
338
    
339
    try:
340
        # Create structured config from dictionary
341
        hydra_conf = OmegaConf.structured(HydraConf)
342
        user_conf = OmegaConf.create(config_dict)
343
        
344
        # Merge and validate
345
        merged = OmegaConf.merge(hydra_conf, user_conf)
346
        
347
        # Additional custom validation
348
        if merged.job.chdir is not None and not isinstance(merged.job.chdir, bool):
349
            raise ValueError("job.chdir must be boolean")
350
        
351
        if merged.output_subdir is not None and not isinstance(merged.output_subdir, str):
352
            raise ValueError("output_subdir must be string or None")
353
        
354
        print("Configuration validation passed")
355
        return True
356
        
357
    except (ValidationError, ValueError) as e:
358
        print(f"Configuration validation failed: {e}")
359
        return False
360

361
# Usage
362
test_config = {
363
    "job": {
364
        "name": "test_job",
365
        "chdir": True
366
    },
367
    "output_subdir": ".hydra",
368
    "verbose": True
369
}
370

371
is_valid = validate_custom_hydra_config(test_config)
372
```