3yearplan/schemas/uns/HIERARCHY.md

# UNS Hierarchy — High-Level View

> **Status: WIP draft (2026-04-30).** Levels 1–3 (Enterprise → Site → Area) drafted across all 6 currently-integrated SCADA sites. Level 4 (Line) and Level 5 (Equipment) pending the per-site discovery walk. Authoritative per-site source files live alongside this document at `<site>.json`. See [`README.md`](README.md) for status, [`QUESTIONS.md`](QUESTIONS.md) for open design questions, [`portal-queries.md`](portal-queries.md) for OpenText / corporate-doc lookups.

## Hierarchy levels (per `goal-state.md`)

| Level | Name | Always present | Notes |
|------:|------|---------------|-------|
| 1 | Enterprise | yes | `zb` (Zimmer Biomet) |
| 2 | Site | yes | `warsaw-west`, `warsaw-north`, `shannon`, `galway`, `tmt`, `ponce` |
| 3 | Area | yes | `bldg-N` at multi-cluster Warsaw campuses; `_default` at single-cluster sites |
| 4 | Line | yes | pending walk (will be `line-1` / `line-2` / process-name) |
| 5 | Equipment | yes | pending walk (will be `cnc-mill-05` / equivalent class-counter form) |

Path serialization: dots in messages and curated-table keys (`zb.warsaw-west.bldg-5.line-2.cnc-mill-05`); slashes in OPC UA browse paths (`zb/warsaw-west/bldg-5/line-2/cnc-mill-05`).

## High-level — all 6 currently-integrated sites

```
zb  (Zimmer Biomet — Enterprise)
├── warsaw-west    Warsaw West Campus    (legacy Zimmer, Warsaw IN, multi-cluster)
├── warsaw-north   Warsaw North Campus   (legacy Biomet, Warsaw IN, multi-cluster)
├── shannon        Shannon               (Ireland, single cluster)
├── galway         Galway                (Ireland, single cluster)
├── tmt            Zimmer Trabecular Metal Technology  (NJ USA, single cluster)
└── ponce          Zimmer Manufacturing B.V. (ZMBV)    (Puerto Rico, single cluster)
```

The Warsaw campuses are physically adjacent in Warsaw, IN; the West/North split traces to the 2015 Zimmer-Biomet merger of two pre-existing sites. The legacy origin shows up durably in the building-naming convention (numbers vs. letters) — see Warsaw expanded view below.

**Not yet integrated** (and therefore deliberately not in this hierarchy): Berlin, Winterthur, Jacksonville, Dover OH, Statesville NC, Calabasas / Carlsbad CA, Mercedita PR, the NJ TMT subsidiary sites (Allendale, Cedar Knolls, Parsippany), and others. These get added to the hierarchy as they onboard via the standardized stack.

## Warsaw expanded (worked example)

```
zb
├── warsaw-west                  Warsaw West Campus (legacy Zimmer)
│   ├── bldg-2                   Bone Cement, Packaging Clean Rooms
│   ├── bldg-5                   Main mfg facility (Foundry, R&D, Quality)
│   ├── bldg-7                   Tool Support, Upper Extremity Manufacturing
│   ├── bldg-10                  Hip and Knee Manufacturing, Packaging Clean Rooms
│   ├── bldg-19                  Trauma HQ + Trauma/Instrument/Knee&Hip Mfg, Foundry
│   └── bldg-20                  Sheet Metal, Scrap Salvage, Warehousing
│
└── warsaw-north                 Warsaw North Campus (legacy Biomet)
    ├── bldg-a                   (3 floors; production-vs-non-production TBD)
    ├── bldg-b                   (2 floors; TBD)
    ├── bldg-c                   (TBD)
    ├── bldg-d                   (TBD)
    ├── bldg-e                   (TBD)
    └── bldg-i                   (2 floors; F/G/H gap to verify, TBD)
```

**What an end-to-end path will look like** once Lines and Equipment are walked (illustrative — not yet committed):

```
zb.warsaw-west.bldg-5.line-2.cnc-mill-05.spindle-speed
zb/warsaw-west/bldg-5/line-2/cnc-mill-05/spindle-speed   (OPC UA form)
```

Each `cnc-mill-05`-style equipment node also carries a stable **UUIDv4** alongside the path, per `goal-state.md` → UNS naming hierarchy. The path is for navigation; the UUID is for lineage across renames or building moves.

## Single-cluster sites (`_default` Area)

All four single-cluster sites use the explicit `_default` placeholder at the Area level — the goal-state requires uniform path depth:

```
zb.shannon._default.<line>.<equipment>
zb.galway._default.<line>.<equipment>
zb.tmt._default.<line>.<equipment>
zb.ponce._default.<line>.<equipment>
```

When a single-cluster site grows to justify multiple Areas (e.g., adds a second production building), `_default` is replaced by the new named area in a single PR; the equipment UUIDs stay stable, the path updates in `dim_equipment` as a historical version. See `goal-state.md` → UNS naming hierarchy → "Area placeholder → named area promotion".

## What's intentionally not here

- **Non-production buildings.** Areas at multi-cluster sites are production buildings only. Warsaw's offices (bldg-3), distribution center (bldg-4), Z Hotel (bldg-15), residential (bldg-18), airport hangar (bldg-14), etc. do not appear — they don't host equipment that lands in the canonical model.
- **Auxiliary / outlying Warsaw buildings** (Cessna, 508 Detroit Street, Armstrong Road properties). Listed in the Real Estate inventory but not classified West/North per the building-naming convention; treated as separate from the main campuses pending walk verification.
- **Not-yet-integrated sites.** The plan's design is to grow this hierarchy as sites onboard, not to enumerate the full Zimmer Biomet manufacturing footprint upfront.
- **Sub-line groupings (cells, stations, work centers).** The 5-level hierarchy is fixed at Enterprise/Site/Area/Line/Equipment. Cells live below Line, encoded in equipment names (e.g., `cell-3-cnc-mill-05`) per the QUESTIONS.md Q6 default; not added as a 4.5 level unless a real driver appears.
- **Product / job hierarchy.** That's Camstar MES territory, not UNS — see `goal-state.md` → UNS naming hierarchy → out-of-scope list.

## What this doc is and isn't

- **Is:** a one-page consolidated view of the Enterprise/Site/Area state, suitable for stakeholders who don't want to read the per-site JSON files.
- **Isn't:** the source of truth. The per-site `<site>.json` files are. This doc is regenerated from those (currently by hand; a generator may be added later).