nodus-schema 0.1.0

Versioned ABI schema validation, parsing, and registry

nodus-schema

Versioned ABI schema validation, parsing, and registry for Nodus AI systems.

Validates payloads against simple-form or JSON Schema object definitions, parses versioned surface names (sys.v1.domain.action), and maintains a thread-safe SchemaRegistry of versioned schemas with stability tracking. No required external dependencies — pure stdlib.

Note on naming: This is the standalone nodus-schema package (C:\dev\nodus-schema). The nodus-lang runtime also ships an in-tree nodus_schema package (src/nodus_schema/) with SyscallSpec, HandlerContract, and VALID_EFFECTS. The two are distinct; check python -c "import nodus_schema; print(nodus_schema.__file__)" to confirm which is active.

Status: v0.1.0 — prepared, not yet published.

---

Install

pip install nodus-schema

---

What it provides

Component	Purpose
validate_payload	Validate a dict against a schema; returns list of error strings
validate_input / validate_output	Aliases for validate_payload
parse_versioned_name	Parse "sys.v1.domain.action" → (version, action)
resolve_version	Find best compatible version from available set
is_stable_version	True for "v1", "v2", etc. (not alpha/beta)
SchemaEntry	One versioned schema with stability and deprecation state
SchemaRegistry	Thread-safe registry of SchemaEntry objects

---

Schema validation

from nodus_schema import validate_payload

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age":  {"type": "integer"},
    },
    "required": ["name"],
}

errors = validate_payload(schema, {"name": "Alice", "age": 30})
# [] — valid

errors = validate_payload(schema, {"age": 30})
# ["Missing required field: 'name'"]

errors = validate_payload(schema, {"name": "Alice", "age": "thirty"})
# ["Field 'age': expected type 'integer', got 'str'"]

Simple-form schema

A flat {field: type_string} dict is also accepted:

errors = validate_payload({"key": "str", "value": "any"}, {"key": "hello"})
# [] — "any" allows any type

Supported type strings: string/str, integer/int, number/float, boolean/bool, object/map/dict, array/list, null/nil, any.

---

Versioned name parsing

from nodus_schema import parse_versioned_name, resolve_version, is_stable_version

version, action = parse_versioned_name("sys.v1.memory.write")
# ("v1", "memory.write")

best = resolve_version("v1", available={"v1", "v2"}, fallback=True)
# "v1"

is_stable_version("v1")      # True
is_stable_version("v1alpha1") # False
is_stable_version("v1beta2")  # False

---

SchemaRegistry

from nodus_schema import SchemaRegistry, SchemaEntry

registry = SchemaRegistry()
registry.register(SchemaEntry(
    name="memory.write",
    version="v1",
    input_schema={"key": "str", "value": "any"},
    output_schema={"stored": "bool"},
    stable=True,
    deprecated=False,
))

entry = registry.get("memory.write", version="v1")  # SchemaEntry | None
versions = registry.versions("memory.write")         # ["v1"]
all_entries = registry.list()                        # list[SchemaEntry]

---

Design

• No required dependencies. Pure stdlib (json, threading, dataclasses).
• Simple-form schemas. Flat {field: type} dicts are normalized to JSON Schema objects automatically.
• Thread-safe. SchemaRegistry uses threading.Lock.

---

Development

pip install -e ".[dev]"
pytest tests/ -q

---

License

MIT — see LICENSE.