location

A location is a place where stock is kept: a hall, a shelf, a bin, a service van. Locations form a tree through parent_id.

• Mutable: the version with the greater hlc wins.
• Ids: random UUIDs.
• Deleting: the reference app deletes (tombstone) only a location without stock and without child locations, and archives it instead when a movement references it.

Fields

Field	Type	Writer	Default	Meaning
code	string	server		Short code printed on the location label and scanned to pick the location
name	string	server		Display name
description	string?	optional	none
parent_id	uuid?	optional	none (top level)	The location this one is part of
erp_reference	string?	optional	none	Key of the location in another system
archived	boolean?	optional	false	Hidden from lists and pickers
created_at	date-time?	optional	none	When the first device created the record; display only

Rules for writers

• The reference app accepts codes of 1 to 40 characters from A-Z, a-z, 0-9, ., _ and -, refuses a code another location on the device already has (case-insensitive) and refuses a parent that would put a location below itself. Readers MUST still accept any code, duplicates and cycles, which concurrent offline edits can produce.
• parent_id may point to a location the reader does not know (not synced yet, or deleted). The location is then shown at the top level.

Derived values

Value	Rule
Path	Names from the root to the location joined with " › ", for example "Hall North › Shelf A01". Stops at an unknown parent or at a location already visited.
Articles	Number of non-archived articles with stock (absolute value above 0.0005) at this location
Total quantity	Sum of their stock at this location, across units

Server validation

Field	Rules
code, name	required, string
description, erp_reference	nullable, string
parent_id	nullable, UUID
archived	nullable, boolean

Example

{
  "entity": "location",
  "id": "2B0E6C1A-7D44-4F1B-9C3E-5A8D2F6B1C07",
  "op": "upsert",
  "hlc": "001791792000123-0000-3F2A9C1B",
  "data": {
    "code": "N-A01",
    "name": "Shelf A01",
    "description": "Hall North, left wall",
    "parent_id": "0D4E2B91-3A6C-4C8F-B1E7-9F2A5D3C6B18",
    "created_at": "2026-10-12T08:00:00Z"
  }
}

Schema

schemas/location.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Location",
  "description": "Storage location in a tree (area, shelf, bin). Mutable: the version with the greater hlc wins. Locations that movements reference are archived instead of deleted.",
  "type": "object",
  "required": ["code", "name"],
  "properties": {
    "code": { "description": "Short code printed on the location label. Not unique across the inventory; the reference app only accepts 1 to 40 characters from A-Z, a-z, 0-9, '.', '_' and '-' and refuses a duplicate (case-insensitive) on the device that types it.", "type": "string", "minLength": 1 },
    "name": { "description": "Display name.", "type": "string", "minLength": 1 },
    "description": { "type": ["string", "null"] },
    "parent_id": {
      "description": "UUID of the parent location; null for a top-level location. Clients must tolerate unknown parents and cycles that concurrent edits can produce.",
      "type": ["string", "null"],
      "format": "uuid",
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$"
    },
    "erp_reference": { "description": "Key of the location in another system.", "type": ["string", "null"] },
    "archived": { "description": "Hidden from lists and pickers; used instead of deleting once movements reference the record. Absent or null means false.", "type": ["boolean", "null"] },
    "created_at": { "description": "When the record was first created, set once by the creating device. Display only.", "type": ["string", "null"], "format": "date-time" }
  },
  "additionalProperties": true,
  "examples": [
    {
      "code": "N-A01",
      "name": "Shelf A01",
      "description": "Hall North, left wall",
      "parent_id": "0D4E2B91-3A6C-4C8F-B1E7-9F2A5D3C6B18",
      "created_at": "2026-10-12T08:00:00Z"
    }
  ]
}