Structured configs

A structured config uses a dataclass or attrs class to define fields, defaults, and types. OmegaConf.structured() creates a config with that schema. Its fields validate assignments at runtime:

>>> from dataclasses import dataclass
>>> from omegaconf import OmegaConf
>>> @dataclass
... class Server:
...     host: str = "localhost"
...     port: int = 80
>>> cfg = OmegaConf.structured(Server)
>>> cfg.port = 8080
>>> cfg.port
8080
>>> cfg.port = "oops"
Traceback (most recent call last):
...
omegaconf.errors.ValidationError: Value 'oops' of type 'str' could not be converted to Integer
    full_key: port
    object_type=Server

The resulting object is a DictConfig, not an instance of Server. OmegaConf.get_type(cfg) returns its schema class. The field annotations can also help a static type checker when you annotate the variable as Server. That annotation does not change the runtime object.

Nested structured configs

A field can be annotated with another structured config class. Use a default_factory when the field has a mutable default:

>>> from dataclasses import field
>>> @dataclass
... class App:
...     server: Server = field(default_factory=Server)
>>> app = OmegaConf.structured(App)
>>> app.server.port
80

Structured configs reject unknown fields. A field can be missing until supplied. The generated Python API documents OmegaConf.structured().

Next, learn how field types describe containers, choices, and alternatives.