gw_data 0.3.0__py3-none-any.whl

gw_data/db/scripts/4_db_seed.py

@@ -0,0 +1,129 @@
+import csv
+import dotenv
+import json
+import os
+import uuid
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+from getpass import getpass
+from passlib.context import CryptContext
+
+from gw_data.config import Settings
+from gw_data.db.models.user import UserSql
+from gw_data.db.models.user_installation_role import UserInstallationRoleSql
+from gw_data.sema.enums import BaseGNodeClass, GNodeStatus
+from gw_data.db.models import GNodeSql, CustomerSql, InstallerSql, InstallationSql
+
+
+dotenv.load_dotenv()
+settings = Settings()
+engine = create_engine(settings.db_url.get_secret_value(), echo=True)
+
+db_sessionmaker = sessionmaker(bind=engine)
+db_session = db_sessionmaker()
+
+default_installer = InstallerSql(
+    id = uuid.uuid4(),
+    info = json.dumps({
+        "company_name": "Millinocket Heating Installers"
+    })
+)
+db_session.add(default_installer)
+
+beech_id = None
+file_path = os.path.join(os.path.dirname(__file__), './seed_data/homes.csv')
+with open(file_path, newline='') as csvfile:
+    csv_reader = csv.reader(csvfile, delimiter=',', quotechar='"')
+    next(csv_reader) # Skip the header row
+    for row in csv_reader:
+        # "short_alias","address","primary_contact","secondary_contact","hardware_layout","unique_id","g_node_alias","alert_status","representation_status","scada_ip_address","scada_git_commit","house_parameters","created_at"
+        (short_alias, address_json, primary_contact_json, secondary_contact_json, hardware_layout_json, unique_id, g_node_alias, alert_status_json, representation_status_json, scada_ip_address, scada_git_commit, house_parameters_json, created_at) = row
+
+        g_node = GNodeSql(
+            id = uuid.uuid4(),
+            alias = g_node_alias,
+            base_class = None,
+            g_node_class = BaseGNodeClass.LeafTransactiveNode,
+            status = GNodeStatus.Active,
+            display_name = None,
+            created_at = created_at
+        )
+        db_session.add(g_node)
+
+        customer = CustomerSql(
+            id = uuid.uuid4(),
+            primary_contact = json.loads(primary_contact_json),
+            secondary_contact = json.loads(secondary_contact_json),
+        )
+        db_session.add(customer)
+
+        installation = InstallationSql(
+            id = uuid.uuid4(),
+            g_node_id = g_node.id,
+            display_name = short_alias,
+            customer_id = customer.id,
+            installer_id = default_installer.id,
+            address = json.loads(address_json),
+            alert_status = json.loads(alert_status_json),
+            hardware_layout = json.loads(hardware_layout_json),
+            representation_status = json.loads(representation_status_json),
+            house_parameters = json.loads(house_parameters_json),
+            scada_ip_address = scada_ip_address,
+            scada_git_commit = scada_git_commit
+        )    
+
+        if installation.display_name == 'beech':
+            beech_id = installation.id
+
+        db_session.add(installation)
+
+
+gbo_pwd_context = CryptContext(
+    schemes=["bcrypt"],
+    deprecated="auto",
+    bcrypt__rounds=12,
+    bcrypt__ident="2b"
+)
+
+
+admin_pw = None
+while admin_pw is None:
+    admin_pw = getpass('Enter a password for the user "admin":')
+    admin_pw_confirmed = getpass('Enter again to confirm:')
+    if admin_pw != admin_pw_confirmed:
+        admin_pw = None
+
+admin = UserSql(
+    id = uuid.uuid4(),
+    username = "admin",
+    hashed_password = gbo_pwd_context.hash(admin_pw)
+)
+db_session.add(admin)
+
+beech_user_pw = None
+while beech_user_pw is None:
+    beech_user_pw = getpass('Enter a password for the user "beech-user":')
+    beech_user_pw_confirmed = getpass('Enter again to confirm:')
+    if beech_user_pw != beech_user_pw_confirmed:
+        beech_user_pw = None
+
+beech_user = UserSql(
+    id = uuid.uuid4(),
+    username = "beech-user",
+    hashed_password = gbo_pwd_context.hash(beech_user_pw)
+)
+db_session.add(beech_user)
+
+db_session.add(UserInstallationRoleSql(
+    user_id = admin.id,
+    role = "admin"
+))
+
+db_session.add(UserInstallationRoleSql(
+    user_id = beech_user.id,
+    role = "owner",
+    installation_id = beech_id
+))
+
+db_session.commit()

gw_data/db/scripts/_XX_drop_all.sql

@@ -0,0 +1,13 @@
+--DROP DATABASE gridworks WITH (FORCE);
+
+-- This line may have to be done by gw_admin
+DROP SCHEMA gridworks;
+
+REVOKE CONNECT ON DATABASE tsdb FROM gw_visualizer;
+DROP USER gw_visualizer;
+
+REVOKE CONNECT ON DATABASE tsdb FROM gw_journalkeeper;
+DROP USER gw_journalkeeper;
+
+REVOKE ALL ON DATABASE tsdb FROM gw_admin;
+DROP USER gw_admin;

gw_data/db/scripts/seed_data/homes.csv

@@ -0,0 +1,6 @@
+"short_alias","address","primary_contact","secondary_contact","hardware_layout","unique_id","g_node_alias","alert_status","representation_status","scada_ip_address","scada_git_commit","house_parameters","created_at"
+"beech","{""street"": ""123 Beech Street"", ""city"": ""Millinocket"", ""state"": ""ME"", ""zip"": ""04462"", ""country"": ""USA"", ""latitude"": 45.65100, ""longitude"": -68.69}","{""first_name"": ""Bradley"", ""last_name"": ""Beech"", ""phone"": ""555-987-6543"", ""email"": null}","null","null",1,"hw1.isone.me.versant.keene.beech","{""status"": ""ok"", ""message"": null, ""acked"": null, ""acked_by"": null, ""acked_at"": null}","""NotListeningToAtn""","127.0.0.1","unknown","{""alpha"": 8.6, ""beta"": -0.14, ""gamma"": 0.0029, ""intermediate_power_kw"": 3.6, ""intermediate_rswt"": 105.0, ""dd_power_kw"": 8.6, ""dd_rswt"": 140.0, ""dd_delta_t"": 20.0}","2026-01-23 07:04:32.477627-06"
+"oak","{""street"": ""456 Oak Street"", ""city"": ""Millinocket"", ""state"": ""ME"", ""zip"": ""04462"", ""country"": ""USA"", ""latitude"": 45.65200, ""longitude"": -68.65}","{""first_name"": ""Brennan"", ""last_name"": ""Oak"", ""phone"": ""828-674-6164"", ""email"": null}","{""first_name"": ""Carla"", ""last_name"": null, ""phone"": null, ""email"": null}","null",2,"hw1.isone.me.versant.keene.oak","{""status"": ""ok"", ""message"": null, ""acked"": null, ""acked_by"": null, ""acked_at"": null}","""NotListeningToAtn""","127.0.0.1","unknown","{""alpha"": 7.6, ""beta"": -0.13, ""gamma"": 0.0024, ""intermediate_power_kw"": 1.5, ""intermediate_rswt"": 100.0, ""dd_power_kw"": 7.6, ""dd_rswt"": 140.0, ""dd_delta_t"": 20.0}","2026-01-23 07:04:32.477627-06"
+"fir","{""street"": ""7890 Fir Road"", ""city"": ""Millinocket"", ""state"": ""ME"", ""zip"": ""00130"", ""country"": ""USA"", ""latitude"": 45.64500, ""longitude"": -68.72}","{""first_name"": ""Renee"", ""last_name"": ""Fir"", ""phone"": ""207-754-3256"", ""email"": ""reneefir@example.com""}","{""first_name"": ""Kim"", ""last_name"": ""FirFir"", ""phone"": ""207-210-0452"", ""email"": null}","null",3,"hw1.isone.me.versant.keene.fir","{""status"": ""ok"", ""message"": null, ""acked"": null, ""acked_by"": null, ""acked_at"": null}","""NotListeningToAtn""","127.0.0.1","unknown","{""alpha"": 7.5, ""beta"": -0.13, ""gamma"": 0.0022, ""intermediate_power_kw"": 1.5, ""intermediate_rswt"": 94.0, ""dd_power_kw"": 7.5, ""dd_rswt"": 150.0, ""dd_delta_t"": 20.0}","2026-01-23 07:04:32.477627-06"
+"maple","{""street"": ""101 Maple Road"", ""city"": ""Millinocket"", ""state"": ""ME"", ""zip"": ""04462"", ""country"": ""USA"", ""latitude"": 45.64400, ""longitude"": -68.73}","{""first_name"": ""Herman"", ""last_name"": ""Maple"", ""phone"": ""555-444-3333"", ""email"": null}","null","null",4,"hw1.isone.me.versant.keene.maple","{""status"": ""ok"", ""message"": null, ""acked"": null, ""acked_by"": null, ""acked_at"": null}","""NotListeningToAtn""","127.0.0.1","unknown","{""alpha"": 6.3, ""beta"": -0.09, ""gamma"": 0.0007, ""intermediate_power_kw"": 1.5, ""intermediate_rswt"": 118.0, ""dd_power_kw"": 6.3, ""dd_rswt"": 160.0, ""dd_delta_t"": 20.0}","2026-01-23 07:04:32.477627-06"
+"elm","{""street"": ""202 Elm Lane"", ""city"": ""Millinocket"", ""state"": ""ME"", ""zip"": ""04462"", ""country"": ""USA"", ""latitude"": 45.6800, ""longitude"": -68.71}","{""first_name"": ""Mike"", ""last_name"": ""Elm"", ""phone"": ""555-666-7777"", ""email"": null}","{""first_name"": ""Michelle"", ""last_name"": ""Elm"", ""phone"": null, ""email"": null}","null",5,"hw1.isone.me.versant.keene.elm","{""status"": ""ok"", ""message"": null, ""acked"": null, ""acked_by"": null, ""acked_at"": null}","""NotListeningToAtn""","127.0.0.1","unknown","{""alpha"": 7.0, ""beta"": -0.13, ""gamma"": 0.001, ""intermediate_power_kw"": 1.5, ""intermediate_rswt"": 120.0, ""dd_power_kw"": 7.0, ""dd_rswt"": 150.0, ""dd_delta_t"": 20.0}","2026-01-23 07:04:32.477627-06"

gw_data/sema/__init__.py

@@ -0,0 +1,15 @@
+from gw_data.sema.base import (
+    SemaError,
+    SemaType,
+)
+from gw_data.sema.codec import (
+    SemaCodec,
+    get_current_types,
+)
+
+__all__ = [
+    "SemaType",
+    "SemaCodec",
+    "SemaError",
+    "get_current_types",
+]

gw_data/sema/base.py

@@ -0,0 +1,184 @@
+import json
+import re
+from typing import Any, Self, TypeVar
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+
+# ============================================================================
+# UTILITY FUNCTIONS
+# ============================================================================
+
+snake_add_underscore_to_camel_pattern = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+def is_pascal_case(s: str) -> bool:
+    return re.match(r"^[A-Z][a-zA-Z0-9]*$", s) is not None
+
+
+def recursively_pascal(d: dict) -> bool:
+    if isinstance(d, dict):
+        for key, value in d.items():
+            if key and key[0].isalpha() and not is_pascal_case(key):
+                return False
+            if not recursively_pascal(value):
+                return False
+    elif isinstance(d, list):
+        for item in d:
+            if not recursively_pascal(item):
+                return False
+    return True
+
+
+def pascal_to_snake(name: str) -> str:
+    return snake_add_underscore_to_camel_pattern.sub("_", name).lower()
+
+
+def snake_to_pascal(word: str) -> str:
+    return "".join(x.capitalize() or "_" for x in word.split("_"))
+
+
+# ============================================================================
+# BASE EXCEPTIONS
+# ============================================================================
+
+class SemaError(Exception):
+    """Base exception for Sema-related errors."""
+
+
+T = TypeVar("T", bound="SemaType")
+
+
+# ============================================================================
+# STRICT SEMA TYPE
+# ============================================================================
+
+class SemaType(BaseModel):
+    """
+    Base class for strict Sema types.
+    """
+
+    type_name: str
+    version: str | None = None
+
+    model_config = ConfigDict(
+        alias_generator=snake_to_pascal,
+        frozen=True,
+        populate_by_name=True,
+        extra="forbid",
+    )
+
+    # ------------------------------------------------------------------------
+    # Serialization
+    # ------------------------------------------------------------------------
+
+    def to_bytes(self) -> bytes:
+        return self.model_dump_json(exclude_none=True, by_alias=True).encode()
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(exclude_none=True, by_alias=True)
+
+    @classmethod
+    def from_bytes(cls, json_bytes: bytes) -> Self:
+        try:
+            d = json.loads(json_bytes)
+        except TypeError as e:
+            raise SemaError("Type must be string or bytes!") from e
+        return cls.from_dict(d)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Self:
+        if not recursively_pascal(d):
+            raise SemaError("Dictionary must be recursively PascalCase")
+        try:
+            return cls.model_validate(d)
+        except ValidationError as e:
+            raise SemaError(f"Validation failed: {e}") from e
+
+    # ------------------------------------------------------------------------
+    # Introspection
+    # ------------------------------------------------------------------------
+
+    @classmethod
+    def type_name_value(cls) -> str:
+        return cls.model_fields["type_name"].default
+
+    @classmethod
+    def version_value(cls) -> str | None:
+        return cls.model_fields["version"].default
+
+    # ------------------------------------------------------------------------
+    # Versioning
+    # ------------------------------------------------------------------------
+
+    def upgrade(self) -> "SemaType":
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not implement upgrade()"
+        )
+
+    def to_latest(self, registry: dict[str, type["SemaType"]]) -> "SemaType":
+        current = self
+        type_name = self.type_name_value()
+
+        if type_name not in registry:
+            raise SemaError(f"No registry entry for {type_name}")
+
+        latest_cls = registry[type_name]
+        latest_version_str = latest_cls.version_value()
+
+        if current.version is None or latest_version_str is None:
+            raise SemaError(f"Version missing for {type_name}")
+
+        try:
+            current_version_int = int(current.version)
+            latest_version_int = int(latest_version_str)
+        except ValueError:
+            raise SemaError(f"Invalid version format for {type_name}")
+
+        if current_version_int > latest_version_int:
+            raise SemaError(
+                f"Current version {current.version} is greater than latest {latest_version_str}"
+            )
+
+        max_steps = latest_version_int - current_version_int
+        steps = 0
+
+        while current.version != latest_version_str:
+            if steps >= max_steps:
+                raise SemaError(
+                    f"Upgrade loop detected for {type_name}: exceeded {max_steps} steps"
+                )
+            current = current.upgrade()
+            steps += 1
+
+        return current
+
+
+# ============================================================================
+# DEGRADED TYPE
+# ============================================================================
+
+class DegradedSemaType:
+    """
+    Best-effort decoded Sema-like object.
+
+    This is NOT a valid SemaType and MUST NOT be used for control logic.
+    """
+
+    def __init__(
+        self,
+        *,
+        type_name: str,
+        version: str | None,
+        raw: dict[str, Any],
+        known_fields: dict[str, Any],
+        unknown_fields: dict[str, Any],
+    ):
+        self.type_name = type_name
+        self.version = version
+        self.raw = raw
+        self.known_fields = known_fields
+        self.unknown_fields = unknown_fields
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.raw

gw_data/sema/codec.py

@@ -0,0 +1,168 @@
+import json
+import logging
+from importlib import import_module
+from collections import defaultdict
+from pathlib import Path
+from typing import Literal
+
+
+from gw_data.sema.base import (
+    DegradedSemaType,
+    SemaType,
+    pascal_to_snake,
+    recursively_pascal,
+    snake_to_pascal,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SemaCodec:
+
+    def __init__(self) -> None:
+        self.registry = get_current_types()
+        self.old_versions = get_old_versions()
+
+    # ------------------------------------------------------------------------
+    # Decode
+    # ------------------------------------------------------------------------
+
+    def from_dict(
+        self,
+        data: dict,
+        mode: Literal["strict", "degraded"] = "strict",
+        auto_upgrade: bool = True
+    ) -> SemaType | DegradedSemaType:
+
+        if not isinstance(data, dict):
+            raise ValueError("Input must be dict")
+
+        if "TypeName" not in data:
+            raise ValueError("Missing TypeName")
+
+        if not recursively_pascal(data := dict(data)):
+            raise ValueError("Input must be PascalCase")
+
+        type_name = data["TypeName"]
+        version = data.get("Version")
+
+        if type_name not in self.registry:
+            if mode == "degraded":
+                return DegradedSemaType(
+                    type_name=type_name,
+                    version=version,
+                    raw=data,
+                    known_fields={},
+                    unknown_fields=data,
+                )
+            raise ValueError(f"Unknown type {type_name}")
+
+        current_cls = self.registry[type_name]
+        current_version = current_cls.version_value()
+
+        # Fast path
+        if version == current_version:
+            return current_cls.from_dict(data)
+
+        # Old version
+        if (
+            type_name in self.old_versions
+            and version in self.old_versions[type_name]
+        ):
+            old_cls = self.old_versions[type_name][version]
+            old_instance = old_cls.from_dict(data)
+            return old_instance.to_latest(self.registry) if auto_upgrade else old_instance
+
+        # Unknown version
+        if mode == "strict":
+            raise ValueError(
+                f"Unsupported version {version} for {type_name}"
+            )
+
+        # --------------------------------------------------------------------
+        # DEGRADED MODE
+        # --------------------------------------------------------------------
+
+        logger.warning(
+            "Degraded decode for %s v%s (current v%s)",
+            type_name,
+            version,
+            current_version,
+        )
+
+        valid_fields = set()
+        for field_name, field_info in current_cls.model_fields.items():
+            valid_fields.add(snake_to_pascal(field_name))
+            valid_fields.add(field_name)
+            if field_info.alias:
+                valid_fields.add(field_info.alias)
+
+        known = {}
+        unknown = {}
+
+        for key, value in data.items():
+            if key in valid_fields or pascal_to_snake(key) in valid_fields:
+                known[key] = value
+            else:
+                unknown[key] = value
+
+        return DegradedSemaType(
+            type_name=type_name,
+            version=version,
+            raw=data,
+            known_fields=known,
+            unknown_fields=unknown,
+        )
+
+    def from_bytes(
+        self,
+        data: bytes,
+        mode: Literal["strict", "degraded"] = "strict",
+    ) -> SemaType | DegradedSemaType:
+
+        try:
+            d = json.loads(data.decode("utf-8"))
+        except Exception as e:
+            raise ValueError(f"Invalid JSON: {e}") from e
+
+        return self.from_dict(d, mode=mode)
+
+    def to_bytes(self, msg: SemaType) -> bytes:
+        return msg.to_bytes()
+
+
+# ============================================================================
+# AUTO-DISCOVERY
+# ============================================================================
+
+def get_current_types() -> dict[str, type[SemaType]]:
+    from gw_data.sema import types
+    return {
+        getattr(types, name).type_name_value(): getattr(types, name)
+        for name in types.__all__
+    }
+
+
+def get_old_versions() -> dict[str, dict[str | None, type[SemaType]]]:
+    registry: dict[str, dict[str | None, type[SemaType]]] = defaultdict(dict)
+    old_versions_dir = Path(__file__).resolve().parent / "types" / "old_versions"
+
+    for path in sorted(old_versions_dir.glob("*.py")):
+        if path.stem == "__init__":
+            continue
+        module = import_module(f"gw_data.sema.types.old_versions.{path.stem}")
+        for name in dir(module):
+            obj = getattr(module, name)
+            if (
+                isinstance(obj, type)
+                and issubclass(obj, SemaType)
+                and obj is not SemaType
+            ):
+                version = obj.version_value()
+                if version is not None:
+                    registry[obj.type_name_value()][version] = obj
+
+    return registry
+
+
+default_codec = SemaCodec()

gw_data/sema/definitions/enums/base.g.node.class/000.yaml

@@ -0,0 +1,55 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://schemas.electricity.works/enums/base.g.node.class/000"
+
+title: "base.g.node.class"
+type: "string"
+description: >
+  Ontology classification for Grid Nodes (GNodes) used to describe their
+  structural relationship to the physical electric grid. Values identify
+  whether a node represents a physical metered boundary, a physical
+  topological structure, a market coordination constraint, or a purely
+  logical entity.
+
+  Every GNode SHALL declare exactly one base.g.node.class value.
+
+enum:
+  - "TerminalAsset"
+  - "LeafTransactiveNode"
+  - "ConnectivityNode"
+  - "MarketMaker"
+  - "Logical"
+
+default: "Logical"
+
+x-gridworks:
+  owner: "gridworks-energy"
+  version: "000"
+  value_descriptions:
+    "TerminalAsset": >
+      A physical transactive asset such as a heat pump, hot water heater, residential battery, 
+      electric vehicle, or any other end-use device located behind an atomic metered point.
+    
+    "LeafTransactiveNode": >
+      The atomic metered unit of the grid. Represents the smallest indivisible metering
+      boundary capable of participating in markets or entering Dispatch Contracts on
+      behalf of a TerminalAsset. Every TerminalAsset is associated with exactly one
+      LeafTransactiveNode.
+
+    "ConnectivityNode": >
+      A physical topological node in the electric power system where conductors join,
+      split, or change configuration. Conceptually aligned with the ConnectivityNode
+      in the IEC 61970/61968 CIM (Common Information Model), but simplified for
+      distribution-level modeling and OPF applications.
+
+    "MarketMaker": >
+      A physical constraint point in the conductor topology that requires localized market
+      coordination. Identified as a grid location (e.g., feeder constraint, transformer limit)
+      where a MarketMaker actor computes local prices for balancing and constraint compliance.
+      See [market-maker](https://gridworks.readthedocs.io/en/latest/market-maker.html).
+
+    "Logical": >
+      A non-physical Grid Node whose identity carries no inherent conductor-topology or
+      metering semantics. Used for purely logical or service-level nodes such as SCADA,
+      forecasting services, market-maker actors, simulation nodes, or organizational
+      microservices. Logical nodes may coordinate with or operate on physical nodes, but do
+      not themselves represent physical grid structure.

gw_data/sema/definitions/enums/g.node.status/000.yaml

@@ -0,0 +1,35 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://schemas.electricity.works/enums/g.node.status/000"
+
+title: "g.node.status"
+type: string
+description: >
+  Lifecycle status of a Grid Node (GNode) within coordinated systems.
+
+enum:
+  - "Pending"
+  - "Active"
+  - "Suspended"
+  - "PermanentlyDeactivated"
+
+default: "Pending"
+
+x-gridworks:
+  owner: "gridworks-energy"
+  version: "000"
+
+  value_descriptions:
+    "Pending": >
+      The GNode has been created but is not yet authorized to participate
+      in system coordination.
+
+    "Active": >
+      The GNode is authorized to participate in system coordination.
+
+    "Suspended": >
+      The GNode is temporarily disabled. It retains identity but does not
+      participate in active coordination. A Suspended GNode MAY transition back to Active.
+
+    "PermanentlyDeactivated": >
+      The GNode has been permanently retired and does not participate
+      in active coordination. It may not change back to another state.

gw_data/sema/definitions/formats/left.right.dot.yaml

@@ -0,0 +1,27 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://schemas.electricity.works/formats/left.right.dot"
+
+title: "left.right.dot"
+description: |
+  Dot-separated hierarchical identifier composed of lowercase
+  alphanumeric segments. The first segment must begin with a
+  lowercase alphabetic character. Subsequent segments may begin
+  with either a lowercase letter or digit. Hierarchy is expressed
+  from left to right, with the most significant component appearing first.
+  
+type: string
+minLength: 1
+pattern: "^[a-z][a-z0-9]*(\\.[a-z0-9]+)*$"
+
+examples:
+  - "beech.1"
+  - "hw1.isone.me.versant.keene.beech"
+  
+counterexamples:
+  - "scada.multipurpose-sensor" # hyphen not allowed
+  - "2be.or.not"                # cannot start with a number
+  - "a..b"                      # empty segment not allowed
+  - ""                          # empty string invalid
+
+x-gridworks:
+  owner: "gridworks-energy"

gw_data/sema/definitions/formats/uuid4.str.yaml

@@ -0,0 +1,29 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://schemas.electricity.works/formats/uuid4.str"
+
+title: "uuid4.str"
+description: >
+  Canonical lowercase UUID version 4 string in standard hyphenated
+  8-4-4-4-12 format. Enforces version (4) and variant (RFC 4122)
+  and requires lowercase for consistency.
+
+type: string
+pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+minLength: 36
+maxLength: 36
+
+examples:
+  - "9cff2689-eadc-4577-94ea-6d86d0d23e9e"
+  - "4e5a6b1c-2d3e-4f5a-8b9c-1d2e3f4a5b6c"
+  - "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+
+counterexamples:
+  - "not-a-uuid"                              # invalid format
+  - "6ba7b810-9dad-11d1-80b4-00c04fd430c"     # wrong group length (last group too short)
+  - "6ba7b810-9dad-11d1-80b4-00c04fd430c88"   # wrong group length (last group too long)
+  - "6ba7b810-9dad-21d1-80b4-00c04fd430c8"    # wrong version (2 instead of 4)
+  - "6ba7b810-9dad-11d1-70b4-00c04fd430c8"    # wrong variant (7 not allowed)
+  - "6BA7B810-9DAD-11D1-80B4-00C04FD430C8"    # uppercase not allowed
+
+x-gridworks:
+  owner: "gridworks-energy"