Country → State → City → User — those flags belong in one scope. When your application has multiple distinct hierarchy types, you create a separate scope for each one.
Why scopes exist
Foff resolves flag values by walking up a hierarchy you provide at query time. For resolution to work correctly, all flags queried together must share the same hierarchy structure. Scopes enforce that guarantee: every flag inside a scope uses the same ordered hierarchy levels.Concrete example
Suppose you are building an internal company tool. Your access model organizes users like this:employee-hierarchy — and define all flags that apply to this structure inside it. When your app queries Foff for a specific user, it passes the full path (company-id, department-id, team-id, user-id) and Foff resolves the most specific override that matches.
Now imagine the same company also runs a customer-facing product with a completely different structure:
customer-hierarchy — for those flags. The two scopes are fully independent: flags, overrides, and resolution logic do not bleed across them.
One scope or multiple scopes?
| Situation | Recommendation |
|---|---|
| All flags share the same hierarchy | Use one scope |
| You have separate hierarchies (e.g., internal staff vs. external customers) | Create one scope per hierarchy |
| You want to isolate production from staging configs | Create separate scopes (e.g., production, staging) |
| You have a single hierarchy but many unrelated products | A single scope still works; use feature naming conventions to organize them |
Next steps
With a scope created, you are ready to add features — the individual flags and config values — inside it.Features
Learn how to create flags and set default values inside a scope.