7lens Data Model — Organization

Canonical copy

Copied from the 7lens app repository, docs/datamodel/7lens-data-model-organization.md at 012d434, on 2026-11-11. Document version 1.0, dated 2026-10-29. The app repository is the source of truth. Do not edit this page here; change the source and re-run npm run sync:reference.

This is a strategic source document: the Organization-axis definition model. It defines the enterprise, its geography, its Legal Entities, ownership, and entity-side Group values.

---

Purpose

The 7lens Organization model provides a canonical representation of who the enterprise is and where it operates.

It establishes a single enterprise identity, a UN M49 / ISO geography tree, and Legal Entities that Business Domains map to. Every node carries structured ownership. Cross-cutting classification (Business Line, Accountability, and similar) is recorded on the entity — Group values are stored on the entity itself, not as a separate Groups assignment category.

This document defines:

1. Entity semantics — Organization, Region, Sub-region, Country, Legal Entity.
2. Ownership — wire field accountable_person (UI label Owner).
3. Group values — entity-side group_values, including cardinality: many.
4. Validation and persistence — what is an error versus a warning, and how Save / Backup / Clear All behave.
5. Configuration surfaces — Structure view, company templates, Backup.

Product copy uses the terms Organization, Structure, Owner, and Group values as defined here.

---

Concepts

Organization (enterprise identity)

Definition

Organization is the enterprise itself. There is at most one Organization record in a Configuration. It is the root of identity (name, id, optional email domain) and the starting point for geography and Legal Entities.

The Organization record may be absent only while Configuration is empty (onboarding). Once any Region, Sub-region, Country, or Legal Entity exists, the Organization record is required.

Identity and ownership

Attribute	Role
id	Stable identifier. Slug: lowercase letters, digits, underscores; must start with a letter; max 25 characters.
name	Human-readable enterprise name (max 100).
accountable_person	Structured Owner for the enterprise identity (see Ownership wire shape).
email_domain	Optional email domain used by Configuration UI to suggest Owner emails (for example example.com).
group_values	Optional entity-side picks for Groups that apply to organization (see Group values).

What Organization is not

• Not a Region or Legal Entity.
• Not a Business Domain (Domains map to a Legal Entity).
• Not a Technology Platform or Stack.
• Not itself a Group — classification of the enterprise is done by selecting Group values on this record.

---

Structure (geography and Legal Entities)

Configuration UI presents two left-hand concept boxes on the Organization axis:

1. Organization — enterprise identity (the singleton).
2. Structure — regions → sub-regions → countries → legal entities.

Product hierarchy:

Organization
 └── Region
      └── Sub-region (optional)
           └── Country
                └── Legal Entity

A Country belongs to exactly one Sub-region or, when Sub-regions are not used, exactly one Region — never both, never neither.

Region

Attribute	Role
id	Stable slug (max 25).
name	Human-readable label.
m49Code	UN M49 region code — three digits (for example 150 for Europe).
accountable_person	Required Owner.
group_values	Optional entity-side picks for Groups that apply to region.

Regions are children of Organization by containment (no parent id field).

Sub-region

Attribute	Role
id	Stable slug (max 25).
name	Human-readable label.
m49Code	UN M49 sub-region code — three digits (for example 039).
region	Parent Region id (required).
accountable_person	Required Owner.
group_values	Optional entity-side picks for Groups that apply to subregion.

Country

Attribute	Role
id	ISO 3166-1 alpha-2, lowercase (for example es).
name	Human-readable label.
subregion	Parent Sub-region id xor
region	Parent Region id — exactly one of subregion / region must be set.
accountable_person	Required Owner.
group_values	Optional entity-side picks for Groups that apply to country.

Legal Entity

Attribute	Role
id	Stable slug (max 25).
name	Legal name (max 150).
country	Parent Country id (required).
accountable_person	Required Owner.
group_values	Optional entity-side picks for Groups that apply to legal_entity.

Business Domains map to a Legal Entity. Applications inherit organizational context through their Domain — they do not carry a separate Organization owner.

Geography standards

• Regions and Sub-regions use UN M49 codes (m49Code is three digits).
• Countries use ISO 3166-1 alpha-2 as id.
• Commercial overlays such as EMEA or APAC are not base geographic levels in this model.
• Configuration validates that region / sub-region codes are known M49 codes, that a sub-region belongs to its parent region, that a country id is known, and that the country’s parent matches the M49 parent set for that ISO-2.

---

Ownership wire shape

Every Organization-axis entity requires an accountable_person object:

Field	Required	Meaning
name	yes	Given name.
surname	yes	Family name.
email	yes	Contact email.
role	no	Position or role title (optional).

UI label everywhere: Owner. Wire key: accountable_person.

Do not author free-text owner or accountable on new Organization data. Configuration create/edit dialogs and YAML Apply require a complete structured Owner. Legacy packs that still carry free-text Owner labels are migrated into a structured placeholder and flagged as a governance warning on whole-configuration validation; they are not the product model.

---

Group values (entity-side)

Classification picks for Organization entities live on the entity, not in a Groups assignments[] category. Group values are stored on the entity itself.

Shape

Each pick is:

Field	Required	Meaning
groupId	yes	Group being classified under.
valueId	yes (when the Group has options)	Selected value.
subgroupId	no	Present when the value lives under a subgroup container.

group_values:
  - groupId: accountability
    valueId: executive_management
  - groupId: business_line
    valueId: payments_collections
    subgroupId: payments_fx

Presence of the key

Document shape	Meaning
group_values omitted	Dual-read: legacy groups.assignments[] for that entity may still apply.
group_values present (even [])	Entity is source of truth for its picks; legacy assignments for that entity are ignored.

Groups starter packs ship definitions only (assignments: []). Organization packs carry the picks.

Which Groups appear

A Group appears for an Organization entity type when its rules include that type (organization, region, subregion, country, or legal_entity). Create/edit dialogs list applicable Groups immediately. Required controls whether Save / Apply enforce a pick; optional Groups may be left empty.

Cardinality

Driven by the Group rule for that entity type:

Rule cardinality	Behaviour
one (default)	Entity may hold at most one valued pick for that Group.
many	Entity may hold multiple valued picks for the same Group (UI multi-select add/remove).

# Valid only when the Group rule for this entity type has cardinality: many
group_values:
  - groupId: accountability
    valueId: executive_management
  - groupId: accountability
    valueId: group_strategy

Required versus optional

On the Organization axis (entity-side group_values are mandatory when Groups apply):

Condition	Severity
Missing required Group value	Error
Unknown / invalid pick; pick for a Group that does not apply	Error
More than one pick when cardinality is one	Error
Missing optional applicable Group	Warning

YAML Apply on an Organization entity hard-blocks on those errors. Whole-document Save lists errors and warnings in a confirmation popup and lets the operator choose Save anyway (see Persistence).

A Group may hold direct values, container subgroups (each holding values), or both. This document owns where Organization entities store picks and how Organization validation treats them. Picks are group_values on the entity, not a Groups assignment list.

---

Package layout

Organization Backup and starter packs use three YAML files:

File	Contents
organization.yaml	{ organization: … | null }
regions.yaml	{ regions, subregions }
countries.yaml	{ countries, legalEntities }

Group definitions belong on the Groups axis pack. Organization packs may carry empty groups.yaml stubs; do not treat those stubs as the classification model.

---

Rules (integrity)

Hard failures on whole-configuration validation include:

• Schema failures (ids, XOR country parent, M49 digit shape, incomplete structured Owner after migrate).
• Duplicate entity ids; duplicate region / sub-region M49 codes.
• Unknown parent FKs; Organization missing while geography or Legal Entities exist.
• Unknown ISO-2 or M49 membership failures.
• Entity-side group_values errors on Organization entities (invalid or missing required Group values; cardinality one violated).

Warnings include:

• Incomplete / invented Owner emails from legacy free-text migrate.
• Missing optional applicable Group values (“do not invent”).

---

Non-goals

This companion does not define or endorse:

• Treating Groups as nodes in the Organization hierarchy.
• Using Organization geography as Business Domains or Technology Platforms.
• Free-text owner / accountable as the product ownership model.
• Groups assignments[] as the product home for Organization classification picks.
• Commercial overlays (EMEA, APAC) as base Region / Sub-region levels.
• Inventory Assets or Contracts as Organization entities.

---

Q&A

Q1. Is there more than one Organization?

No. Configuration holds a single Organization record (or none during empty onboarding).

Q2. Must every Country hang under a Sub-region?

No. A Country belongs to exactly one Sub-region or exactly one Region. Create dialogs currently add Countries under Sub-regions; YAML may attach a Country directly to a Region when Sub-regions are unused.

Q3. What is the Owner field name on the wire?

accountable_person with required name, surname, email, and optional role. UI label: Owner.

Q4. Where do Group classifications for a Legal Entity live?

On that Legal Entity under group_values (entity-side). Groups packs define the Group; they do not ship assignment floods.

Q5. Can an Organization entity hold many values of one Group?

Yes, when that Group’s rule for the entity type has cardinality: many. Otherwise at most one valued pick is allowed.

Q6. Does a missing required Group value block Save?

On Organization YAML Apply: yes (parameter error). On whole-document Save: the Save popup lists the error and the operator may still choose Save anyway. Optional missing picks are warnings.

Q7. How do Domains relate to Organization?

A Business Domain maps to a Legal Entity. Applications inherit organizational context through that Domain.

Q8. What do Create Backup and Restore Backup do?

Create Backup exports the Organization axis package. Restore Backup replaces the Organization axis from an uploaded package after impact confirmation, without hard-blocking on semantic report issues or pending editor dirty state.

---

Examples

Illustrative YAML aligned with starter-pack shape.

Organization identity

organization:
  id: org_example
  name: Example Group, S.A.
  email_domain: example.com
  accountable_person:
    name: Alex
    surname: Morgan
    email: alex.morgan@example.com
    role: Chief Executive Officer
  group_values:
    - groupId: accountability
      valueId: executive_management

Regions and Sub-regions

regions:
  - id: europe
    name: Europe
    m49Code: '150'
    accountable_person:
      name: Ana
      surname: Ruiz
      email: ana.ruiz@example.com
      role: Europe Owner
subregions:
  - id: southern_europe
    name: Southern Europe
    m49Code: '039'
    region: europe
    accountable_person:
      name: Ana
      surname: Ruiz
      email: ana.ruiz@example.com

Country and Legal Entity (with Group values)

countries:
  - id: es
    name: Spain
    subregion: southern_europe
    accountable_person:
      name: Carlos
      surname: Vega
      email: carlos.vega@example.com
legalEntities:
  - id: example_renewables_sa
    name: Example Renewables, S.A.
    country: es
    accountable_person:
      name: Lucia
      surname: Soto
      email: lucia.soto@example.com
      role: Division Lead
    group_values:
      - groupId: division
        valueId: renewable_energy
      - groupId: accountability
        valueId: renewable_energy

Cardinality many

# Group rule for organization includes cardinality: many
organization:
  id: org_acme
  name: ACME
  accountable_person:
    name: Ada
    surname: Lovelace
    email: ada@acme.example
  group_values:
    - groupId: accountability
      valueId: executive_management
    - groupId: accountability
      valueId: group_strategy

Empty entity-side group_values authoring versus omission

# Entity is source of truth — no legacy assignments for this entity
group_values: []

# Omitting group_values entirely keeps dual-read of legacy groups.assignments[]