json-atom 0.4.0__tar.gz → 0.4.2__tar.gz

{json_atom-0.4.0 → json_atom-0.4.2}/CLAUDE.md

@@ -66,8 +66,8 @@ tests/
 - **Specification**: [JSON Atom v0](https://github.com/ltwlf/json-atom-format/blob/main/spec/v0.md)
 - **Conformance**: Level 2 (Apply + Reversible) — passes all fixtures
 - **Spec is source of truth** — when spec and TypeScript reference diverge, follow the spec
-- **Spec-faithful divergence from TS**: digit-after-dot (`$.items.0`) is a PathError per spec grammar
-- **remove without oldValue**: valid per spec (OPTIONAL), unlike TS which requires it
+- **Shared v5 behavior**: both implementations reject digit-after-dot paths and accept remove operations without `oldValue` (undo still requires it).
+- **Packaging**: PyPI distribution `json-atom`, repository `json-atom-py`, import `json_atom`.
 
 ## Coding Conventions
 

{json_atom-0.4.0 → json_atom-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: json-atom
-Version: 0.4.0
+Version: 0.4.2
 Summary: Python implementation of the JSON Atom v0 specification
 Project-URL: Homepage, https://github.com/ltwlf/json-atom-py
 Project-URL: Repository, https://github.com/ltwlf/json-atom-py
@@ -22,7 +22,7 @@ Description-Content-Type: text/markdown
 # json-atom-py
 
 [![CI](https://github.com/ltwlf/json-atom-py/actions/workflows/ci.yml/badge.svg)](https://github.com/ltwlf/json-atom-py/actions/workflows/ci.yml)
-[![PyPI version](https://badge.fury.io/py/json-atom-py.svg)](https://pypi.org/project/json-atom-py/)
+[![PyPI version](https://badge.fury.io/py/json-atom.svg)](https://pypi.org/project/json-atom/)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -30,7 +30,9 @@ Description-Content-Type: text/markdown
 
 Zero dependencies. Fully typed. Python 3.12+.
 
-> **Ecosystem note:** This project implements the [JSON Atom specification](https://github.com/ltwlf/json-atom-format). It is unrelated to the older `json-atom` package on PyPI.
+Created by [Christian Glessner](https://www.linkedin.com/in/christian-glessner/).
+
+> **Package names:** The repository is `json-atom-py`, the PyPI distribution is [`json-atom`](https://pypi.org/project/json-atom/), and Python imports use `json_atom`. This project implements the [JSON Atom specification](https://github.com/ltwlf/json-atom-format).
 
 ```text
 json-atom-format  (specification)
@@ -40,10 +42,22 @@ json-atom-format  (specification)
 
 The specification defines the wire format. Each language implementation produces and consumes compatible deltas. A TypeScript implementation is also available: [json-diff-ts](https://github.com/ltwlf/json-diff-ts).
 
+## Release 0.4.2
+
+This release aligns edge cases with the TypeScript implementation and the shared JSON Atom fixtures:
+
+- Mixed dot/bracket identity paths preserve literal property names.
+- Nested boolean/number changes are detected using JSON type equality.
+- Root creation/deletion uses `add`/`remove` with `null` as the empty document.
+- Failed moves preserve their source, and equivalent bracket paths cannot bypass move restrictions.
+- Unsupported wire versions are rejected.
+
+Validated with 824 Python tests, all 16 shared conformance fixtures, and 205 document pairs exchanged in both directions with TypeScript, including undo.
+
 ## Installation
 
 ```bash
-pip install json-atom-py
+pip install json-atom
 ```
 
 ## Quick Start
@@ -79,6 +93,25 @@ The delta is a `Delta` instance (a `dict` subclass) — JSON-serializable, stora
 }
 ```
 
+## Sending atoms between Python and TypeScript
+
+The wire envelope is always `{"format": "json-atom", "version": 1, "operations": [...]}`.
+The draft specification filename (`spec/v0.md`) and package versions are independent of this wire version.
+
+Serialize a plain dictionary when writing JSON, including empty deltas:
+
+```python
+payload = json.dumps(dict(delta))
+# For files or streams: json.dump(dict(delta), output_file)
+```
+
+`Delta` deliberately uses operation-count truthiness. Converting to `dict` preserves the envelope when
+Python's streaming or indented JSON encoder encounters a delta with no operations.
+
+TypeScript can consume that payload with `applyAtom(source, JSON.parse(payload))` from
+[`json-diff-ts`](https://github.com/ltwlf/json-diff-ts). Use string identity keys for integers outside
+JavaScript's safe integer range. Diff options are implementation-specific; the emitted format is shared.
+
 ## Typed Models
 
 Delta and Operation are dict subclasses with full IDE support — autocomplete, typed properties, factory methods, and extension attribute access:
@@ -165,7 +198,7 @@ Add    /items/0  ← now it's "NewItem"
 Update /items/1  ← this used to be /items/0
 ```
 
-This makes diffs fragile. You can't store them, replay them reliably, or build audit logs on top of them. This is the fundamental problem with index-based formats like JSON Patch (RFC 6902): paths like `/items/0` are positional, so any insertion, deletion, or reorder invalidates every subsequent path.
+Positional patches apply correctly to their expected source state. Independently reordering the target array can change which item a stored index addresses. Identity-based paths help when items must be addressed by key; they do not provide conflict resolution.
 
 **JSON Atom solves this with key-based identity.** Array elements are matched by a stable key, and paths use JSONPath filter expressions that survive insertions, deletions, and reordering:
 

{json_atom-0.4.0 → json_atom-0.4.2}/README.md

@@ -1,7 +1,7 @@
 # json-atom-py
 
 [![CI](https://github.com/ltwlf/json-atom-py/actions/workflows/ci.yml/badge.svg)](https://github.com/ltwlf/json-atom-py/actions/workflows/ci.yml)
-[![PyPI version](https://badge.fury.io/py/json-atom-py.svg)](https://pypi.org/project/json-atom-py/)
+[![PyPI version](https://badge.fury.io/py/json-atom.svg)](https://pypi.org/project/json-atom/)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -9,7 +9,9 @@
 
 Zero dependencies. Fully typed. Python 3.12+.
 
-> **Ecosystem note:** This project implements the [JSON Atom specification](https://github.com/ltwlf/json-atom-format). It is unrelated to the older `json-atom` package on PyPI.
+Created by [Christian Glessner](https://www.linkedin.com/in/christian-glessner/).
+
+> **Package names:** The repository is `json-atom-py`, the PyPI distribution is [`json-atom`](https://pypi.org/project/json-atom/), and Python imports use `json_atom`. This project implements the [JSON Atom specification](https://github.com/ltwlf/json-atom-format).
 
 ```text
 json-atom-format  (specification)
@@ -19,10 +21,22 @@ json-atom-format  (specification)
 
 The specification defines the wire format. Each language implementation produces and consumes compatible deltas. A TypeScript implementation is also available: [json-diff-ts](https://github.com/ltwlf/json-diff-ts).
 
+## Release 0.4.2
+
+This release aligns edge cases with the TypeScript implementation and the shared JSON Atom fixtures:
+
+- Mixed dot/bracket identity paths preserve literal property names.
+- Nested boolean/number changes are detected using JSON type equality.
+- Root creation/deletion uses `add`/`remove` with `null` as the empty document.
+- Failed moves preserve their source, and equivalent bracket paths cannot bypass move restrictions.
+- Unsupported wire versions are rejected.
+
+Validated with 824 Python tests, all 16 shared conformance fixtures, and 205 document pairs exchanged in both directions with TypeScript, including undo.
+
 ## Installation
 
 ```bash
-pip install json-atom-py
+pip install json-atom
 ```
 
 ## Quick Start
@@ -58,6 +72,25 @@ The delta is a `Delta` instance (a `dict` subclass) — JSON-serializable, stora
 }
 ```
 
+## Sending atoms between Python and TypeScript
+
+The wire envelope is always `{"format": "json-atom", "version": 1, "operations": [...]}`.
+The draft specification filename (`spec/v0.md`) and package versions are independent of this wire version.
+
+Serialize a plain dictionary when writing JSON, including empty deltas:
+
+```python
+payload = json.dumps(dict(delta))
+# For files or streams: json.dump(dict(delta), output_file)
+```
+
+`Delta` deliberately uses operation-count truthiness. Converting to `dict` preserves the envelope when
+Python's streaming or indented JSON encoder encounters a delta with no operations.
+
+TypeScript can consume that payload with `applyAtom(source, JSON.parse(payload))` from
+[`json-diff-ts`](https://github.com/ltwlf/json-diff-ts). Use string identity keys for integers outside
+JavaScript's safe integer range. Diff options are implementation-specific; the emitted format is shared.
+
 ## Typed Models
 
 Delta and Operation are dict subclasses with full IDE support — autocomplete, typed properties, factory methods, and extension attribute access:
@@ -144,7 +177,7 @@ Add    /items/0  ← now it's "NewItem"
 Update /items/1  ← this used to be /items/0
 ```
 
-This makes diffs fragile. You can't store them, replay them reliably, or build audit logs on top of them. This is the fundamental problem with index-based formats like JSON Patch (RFC 6902): paths like `/items/0` are positional, so any insertion, deletion, or reorder invalidates every subsequent path.
+Positional patches apply correctly to their expected source state. Independently reordering the target array can change which item a stored index addresses. Identity-based paths help when items must be addressed by key; they do not provide conflict resolution.
 
 **JSON Atom solves this with key-based identity.** Array elements are matched by a stable key, and paths use JSONPath filter expressions that survive insertions, deletions, and reordering:
 

{json_atom-0.4.0 → json_atom-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "json-atom"
-version = "0.4.0"
+version = "0.4.2"
 description = "Python implementation of the JSON Atom v0 specification"
 readme = "README.md"
 license = "MIT"

{json_atom-0.4.0 → json_atom-0.4.2}/src/json_atom/_identity.py

@@ -14,6 +14,7 @@ from typing import Any, Literal
 
 from json_atom._utils import json_equal
 from json_atom.errors import DiffError
+from json_atom.path import _NESTED_PATH_RE
 
 
 @dataclass(frozen=True, slots=True)
@@ -23,20 +24,28 @@ class IdentityResolver:
     The ``property`` name appears in filter paths: ``[?(@.{property}==...)]``.
     The ``resolve`` callable extracts the identity value from an element.
 
+    Supports nested dot paths like ``positionNumber.value`` which resolves
+    via ``elem["positionNumber"]["value"]``.  When a custom resolver is
+    provided, the stored value is validated using the same dot-path
+    semantics for ``property``.
+
     .. important::
 
         The value returned by ``resolve`` **must** match the value actually
-        stored under ``elem[property]`` for that element.  JSON Atom applies
-        keyed-array filters by testing ``elem[property] == literal``, so if
-        the resolver returns a synthetic or composite value that is not
-        literally stored on the element, the generated delta paths will not
-        match during ``apply_delta`` / ``resolve_path``.
+        stored at the ``property`` path on the element.  JSON Atom applies
+        keyed-array filters by resolving the property path, so if the
+        resolver returns a value that doesn't match the stored value, the
+        generated delta paths will not match during ``apply_delta``.
 
     Example::
 
         # Simple key: use the ``id`` field directly
         IdentityResolver("id", lambda e: e["id"])
 
+        # Nested key: use a dot-separated path
+        IdentityResolver("positionNumber.value",
+                         lambda e: e["positionNumber"]["value"])
+
         # Validation: coerce to int, ensuring consistency
         # (only safe when the stored value round-trips through int)
         IdentityResolver("id", lambda e: int(e["id"]))
@@ -125,6 +134,28 @@ def _normalize_identity_value(value: IdentityKey) -> _ResolvedIdentity:
     )
 
 
+_SENTINEL = object()
+
+
+def _resolve_nested(elem: Any, key_property: str) -> Any:
+    """Resolve a possibly-nested dot path on a dict element.
+
+    Returns ``_SENTINEL`` if any segment is missing.
+    For non-nested keys, falls back to a simple dict lookup.
+    """
+    if not isinstance(elem, dict):
+        return _SENTINEL
+    is_nested = "." in key_property and _NESTED_PATH_RE.match(key_property) is not None
+    if not is_nested:
+        return elem.get(key_property, _SENTINEL)
+    current: Any = elem
+    for seg in key_property.split("."):
+        if not isinstance(current, dict) or seg not in current:
+            return _SENTINEL
+        current = current[seg]
+    return current
+
+
 def extract_identity(
     elem: Any,
     key_property: str,
@@ -133,8 +164,11 @@ def extract_identity(
     """Extract the identity value from an array element.
 
     Uses the custom resolver if provided, otherwise reads the key property
-    directly from the element dict.  The returned value must be a JSON scalar
-    (str, int, float, bool, or None) suitable for use in filter paths.
+    directly from the element dict.  Supports nested dot paths like
+    ``positionNumber.value`` → ``elem["positionNumber"]["value"]``.
+
+    The returned value must be a JSON scalar (str, int, float, bool, or None)
+    suitable for use in filter paths.
 
     Raises:
         DiffError: If the element is missing the key property or the resolver
@@ -147,25 +181,25 @@ def extract_identity(
             raise DiffError(
                 f"Identity resolver for '{key_property}' failed on element {elem!r}: {exc}"
             ) from exc
-        # Verify the element is a dict with the key property and that the
-        # stored value matches the resolved value — apply_delta matches
-        # filter paths via elem[key_property] == literal, so a mismatch
-        # would produce unapplyable deltas.
-        if not isinstance(elem, dict) or key_property not in elem:
+        # Verify the element has the key property and that the stored value
+        # matches the resolved value — apply_delta matches filter paths via
+        # the key property, so a mismatch would produce unapplyable deltas.
+        stored = _resolve_nested(elem, key_property)
+        if stored is _SENTINEL:
             raise DiffError(
                 f"Resolver for '{key_property}' returned {value!r} but element "
-                f"is not a dict with '{key_property}': {elem!r}"
+                f"is missing identity path '{key_property}': {elem!r}"
             )
-        stored = elem[key_property]
         if not json_equal(stored, value):
             raise DiffError(
                 f"Resolver for '{key_property}' returned {value!r} but "
-                f"elem['{key_property}'] is {stored!r} — filter path would not match"
+                f"stored value at '{key_property}' is {stored!r} — filter path would not match"
             )
-    elif not isinstance(elem, dict) or key_property not in elem:
-        raise DiffError(f"Array element missing identity key '{key_property}': {elem!r}")
     else:
-        value = elem[key_property]
+        stored = _resolve_nested(elem, key_property)
+        if stored is _SENTINEL:
+            raise DiffError(f"Array element missing identity key '{key_property}': {elem!r}")
+        value = stored
 
     if not isinstance(value, (str, int, float, bool, type(None))):
         raise DiffError(

{json_atom-0.4.0 → json_atom-0.4.2}/src/json_atom/_utils.py

@@ -47,6 +47,10 @@ def json_equal(a: Any, b: Any) -> bool:
     if type(a) is not type(b):
         return False
 
+    if isinstance(a, dict):
+        return a.keys() == b.keys() and all(json_equal(value, b[key]) for key, value in a.items())
+    if isinstance(a, list):
+        return len(a) == len(b) and all(json_equal(left, right) for left, right in zip(a, b, strict=True))
     return a == b  # type: ignore[no-any-return]
 
 

{json_atom-0.4.0 → json_atom-0.4.2}/src/json_atom/apply.py

@@ -122,6 +122,11 @@ def _apply_move(obj: Any, op: Operation) -> Any:
     # Read value at source
     value = _read_value_at_path(obj, from_path)
 
+    # Preflight on a clone: a failed destination must not consume the source.
+    preview = copy.deepcopy(obj)
+    preview = _apply_operation(preview, Operation(op="remove", path=from_path))
+    _apply_operation(preview, Operation(op="add", path=to_path, value=value))
+
     # Remove from source
     remove_op = Operation(op="remove", path=from_path)
     obj = _apply_operation(obj, remove_op)
@@ -232,19 +237,19 @@ def _resolve_parent(
 _SENTINEL = object()
 
 
-def _resolve_property(obj: Any, key: str, *, literal: bool = False) -> Any:
+def _resolve_property(obj: Any, key: str, *, literal: bool = False, members: tuple[str, ...] | None = None) -> Any:
     """Resolve a property on a dict.
 
     When ``literal`` is False and the key contains dots, traverses nested segments.
     When ``literal`` is True, treats the key as a literal property name.
     Returns ``_SENTINEL`` if the property is missing (distinguishes from ``None``).
     """
-    if literal or "." not in key:
+    if members is None and (literal or "." not in key):
         if isinstance(obj, dict) and key in obj:
             return obj[key]
         return _SENTINEL
     current = obj
-    for seg in key.split("."):
+    for seg in members if members is not None else key.split("."):
         if not isinstance(current, dict) or seg not in current:
             return _SENTINEL
         current = current[seg]
@@ -260,7 +265,7 @@ def _find_key_filter_match(arr: list[Any], seg: KeyFilterSegment, path_str: str)
     """
     matches: list[int] = []
     for idx, elem in enumerate(arr):
-        resolved = _resolve_property(elem, seg.property, literal=seg.literal_key)
+        resolved = _resolve_property(elem, seg.property, literal=seg.literal_key, members=seg.member_path)
         if resolved is not _SENTINEL and json_equal(resolved, seg.value):
             matches.append(idx)
 
@@ -293,9 +298,7 @@ def _find_value_filter_match(arr: list[Any], seg: ValueFilterSegment, path_str:
 # ---------------------------------------------------------------------------
 
 
-def _apply_property_op(
-    parent: Any, name: str, op_type: str, op: Operation, path_str: str
-) -> None:
+def _apply_property_op(parent: Any, name: str, op_type: str, op: Operation, path_str: str) -> None:
     """Apply an operation on an object property."""
     if not isinstance(parent, dict):
         raise ApplyError(f"Cannot apply property operation on {_type_name(parent)}: {path_str}")
@@ -324,9 +327,7 @@ def _apply_property_op(
 # ---------------------------------------------------------------------------
 
 
-def _apply_index_op(
-    parent: Any, index: int, op_type: str, op: Operation, path_str: str
-) -> None:
+def _apply_index_op(parent: Any, index: int, op_type: str, op: Operation, path_str: str) -> None:
     """Apply an operation on an array index."""
     if not isinstance(parent, list):
         raise ApplyError(f"Cannot apply index operation on {_type_name(parent)}: {path_str}")
@@ -371,7 +372,7 @@ def _apply_key_filter_op(
     if op_type == "add":
         # Filter must NOT match any existing element
         for elem in parent:
-            resolved = _resolve_property(elem, seg.property, literal=seg.literal_key)
+            resolved = _resolve_property(elem, seg.property, literal=seg.literal_key, members=seg.member_path)
             if resolved is not _SENTINEL and json_equal(resolved, seg.value):
                 raise ApplyError(f"Key filter already matches an element (use 'replace'): {path_str}")
 
@@ -440,27 +441,20 @@ def _apply_value_filter_op(
 # ---------------------------------------------------------------------------
 
 
-def _validate_keyed_array_consistency(
-    value: Any, seg: KeyFilterSegment, path_str: str
-) -> None:
+def _validate_keyed_array_consistency(value: Any, seg: KeyFilterSegment, path_str: str) -> None:
     """Validate that the value contains the identity property matching the filter.
 
     Applies to 'add' and element-level 'replace' on key-filtered paths
     (no trailing segments after filter).
     """
     if not isinstance(value, dict):
-        raise ApplyError(
-            f"Keyed-array value must be an object, got {_type_name(value)}: {path_str}"
-        )
-    resolved = _resolve_property(value, seg.property, literal=seg.literal_key)
+        raise ApplyError(f"Keyed-array value must be an object, got {_type_name(value)}: {path_str}")
+    resolved = _resolve_property(value, seg.property, literal=seg.literal_key, members=seg.member_path)
     if resolved is _SENTINEL:
-        raise ApplyError(
-            f"Keyed-array value missing identity property '{seg.property}': {path_str}"
-        )
+        raise ApplyError(f"Keyed-array value missing identity property '{seg.property}': {path_str}")
     if not json_equal(resolved, seg.value):
         raise ApplyError(
-            f"Keyed-array value identity mismatch: "
-            f"filter expects {seg.value!r} but value has {resolved!r}: {path_str}"
+            f"Keyed-array value identity mismatch: filter expects {seg.value!r} but value has {resolved!r}: {path_str}"
         )
 
 

{json_atom-0.4.0 → json_atom-0.4.2}/src/json_atom/diff.py

@@ -107,6 +107,14 @@ def _diff_values(
     if json_equal(old, new):
         return
 
+    # At document root, null represents absence (spec Section 6.5).
+    if not segments and old is None:
+        _emit_add(new, segments, operations)
+        return
+    if not segments and new is None:
+        _emit_remove(old, segments, reversible, operations)
+        return
+
     old_is_dict = isinstance(old, dict) and not isinstance(old, bool)
     new_is_dict = isinstance(new, dict) and not isinstance(new, bool)
 

{json_atom-0.4.0 → json_atom-0.4.2}/src/json_atom/models.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import builtins
 import re
 from collections.abc import Callable, Iterator
 from dataclasses import dataclass
@@ -53,6 +54,14 @@ class KeyFilterSegment:
     property: str
     value: Any
     literal_key: bool = False
+    member_path: tuple[str, ...] | None = None
+
+    @builtins.property
+    def members(self) -> tuple[str, ...]:
+        """Unambiguous property names, including mixed bracket/dot access."""
+        if self.member_path is not None:
+            return self.member_path
+        return (self.property,) if self.literal_key else tuple(self.property.split("."))
 
 
 @dataclass(frozen=True, slots=True)

{json_atom-0.4.0 → json_atom-0.4.2}/src/json_atom/path.py

@@ -153,26 +153,32 @@ def _parse_filter(inner: str) -> KeyFilterSegment | ValueFilterSegment:
 
     `inner` is the text between '@' and ')' (exclusive).
     """
-    if inner.startswith("."):
-        # Key filter with dot property: .key==val or .a.b==val (nested per RFC 9535)
-        eq_pos = inner.find("==")
-        if eq_pos == -1:
-            raise PathError(f"Invalid filter expression: missing '==' in @{inner}")
-        key = inner[1:eq_pos]
-        if not key or not _NESTED_PATH_RE.match(key):
-            raise PathError(f"Invalid property name in filter: {key!r}")
-        literal_str = inner[eq_pos + 2 :]
-        return KeyFilterSegment(property=key, value=parse_filter_literal(literal_str))
-
-    if inner.startswith("['"):
-        # Key filter with bracket property: ['dotted.key']==val
-        key, close_quote_idx = _extract_quoted_string(inner, 2)  # after ['
-        # After the closing quote, expect ']==' then the literal
-        rest = inner[close_quote_idx + 1 :]  # from ']' onwards
-        if not rest.startswith("]=="):
-            raise PathError("Invalid bracket filter syntax: expected ']==' after quoted key")
-        literal_str = rest[3:]  # skip ']==
-        return KeyFilterSegment(property=key, value=parse_filter_literal(literal_str), literal_key=True)
+    if inner.startswith((".", "['")):
+        members: list[str] = []
+        i = 0
+        while i < len(inner) and not inner.startswith("==", i):
+            if inner[i] == ".":
+                match = re.match(r"[a-zA-Z_][a-zA-Z0-9_]*", inner[i + 1 :])
+                if match is None:
+                    raise PathError("Invalid property name in filter")
+                members.append(match.group())
+                i += 1 + len(match.group())
+            elif inner.startswith("['", i):
+                key, close = _extract_quoted_string(inner, i + 2)
+                if inner[close + 1 : close + 2] != "]":
+                    raise PathError("Expected ']' after filter property")
+                members.append(key)
+                i = close + 2
+            else:
+                raise PathError("Invalid member access in filter")
+        if not inner.startswith("==", i):
+            raise PathError("Invalid filter expression: missing '=='")
+        value = parse_filter_literal(inner[i + 2 :])
+        if len(members) == 1:
+            return KeyFilterSegment(property=members[0], value=value, literal_key=inner.startswith("['"))
+        if all(_PROPERTY_NAME_RE.fullmatch(member) for member in members):
+            return KeyFilterSegment(property=".".join(members), value=value)
+        return KeyFilterSegment(property=".".join(members), value=value, member_path=tuple(members))
 
     if inner.startswith("=="):
         # Value filter: ==val
@@ -397,19 +403,17 @@ def _resolve_key_filter(arr: Any, seg: KeyFilterSegment) -> int:
 
     _sentinel = object()
 
-    def _resolve(obj: Any, key: str) -> Any:
-        if seg.literal_key or "." not in key:
-            return obj.get(key, _sentinel) if isinstance(obj, dict) else _sentinel
+    def _resolve(obj: Any) -> Any:
         cur = obj
-        for s in key.split("."):
-            if not isinstance(cur, dict) or s not in cur:
+        for member in seg.members:
+            if not isinstance(cur, dict) or member not in cur:
                 return _sentinel
-            cur = cur[s]
+            cur = cur[member]
         return cur
 
     matches: list[int] = []
     for idx, elem in enumerate(arr):
-        resolved = _resolve(elem, seg.property)
+        resolved = _resolve(elem)
         if resolved is not _sentinel and json_equal(resolved, seg.value):
             matches.append(idx)
 
@@ -420,9 +424,7 @@ def _resolve_key_filter(arr: Any, seg: KeyFilterSegment) -> int:
     if len(matches) > 1:
         literal = format_filter_literal(seg.value)
         member = f".{seg.property}" if _NESTED_PATH_RE.match(seg.property) else f"['{seg.property}']"
-        raise PathError(
-            f"Key filter [?(@{member}=={literal})] matched {len(matches)} elements (must be exactly one)"
-        )
+        raise PathError(f"Key filter [?(@{member}=={literal})] matched {len(matches)} elements (must be exactly one)")
     return matches[0]
 
 
@@ -474,7 +476,13 @@ def build_path(
         elif isinstance(seg, KeyFilterSegment):
             prop = seg.property
             literal = format_filter_literal(seg.value)
-            if seg.literal_key and not _PROPERTY_NAME_RE.match(prop):
+            if seg.member_path is not None:
+                member = "".join(
+                    f".{key}" if _PROPERTY_NAME_RE.fullmatch(key) else "['" + key.replace("'", "''") + "']"
+                    for key in seg.members
+                )
+                parts.append(f"[?(@{member}=={literal})]")
+            elif seg.literal_key and not _PROPERTY_NAME_RE.match(prop):
                 # Literal property name that can't use dot notation — bracket
                 escaped_prop = prop.replace("'", "''")
                 parts.append(f"[?(@['{escaped_prop}']=={literal})]")

{json_atom-0.4.0 → json_atom-0.4.2}/src/json_atom/validate.py

@@ -7,7 +7,9 @@ from __future__ import annotations
 
 from typing import Any
 
+from json_atom.errors import PathError
 from json_atom.models import ValidationResult
+from json_atom.path import build_path, parse_path
 
 # Fields defined by the spec for the delta envelope
 _ENVELOPE_REQUIRED = {"format", "version", "operations"}
@@ -44,6 +46,9 @@ def validate_delta(delta: Any) -> ValidationResult:
     elif not isinstance(delta["version"], int) or isinstance(delta["version"], bool):
         errors.append(f"Invalid version: expected integer, got {type(delta['version']).__name__}")
 
+    elif delta["version"] != 1:
+        errors.append(f"Unsupported version: {delta['version']!r}; expected 1")
+
     # Required field: operations
     if "operations" not in delta:
         errors.append("Missing required field: 'operations'")
@@ -68,7 +73,7 @@ def _validate_operation(op: Any, index: int, errors: list[str]) -> None:
     # Required: op
     if "op" not in op:
         errors.append(f"{prefix}: missing required field 'op'")
-    elif op["op"] not in _VALID_OPS:
+    elif not isinstance(op["op"], str) or op["op"] not in _VALID_OPS:
         errors.append(f"{prefix}: invalid op {op['op']!r}, must be one of: {', '.join(sorted(_VALID_OPS))}")
 
     # Required: path
@@ -109,7 +114,7 @@ def _validate_operation(op: Any, index: int, errors: list[str]) -> None:
         from_path = op.get("from")
         to_path = op.get("path")
         if isinstance(from_path, str) and isinstance(to_path, str):
-            if from_path == to_path:
+            if _same_path(from_path, to_path):
                 errors.append(f"{prefix}: 'move' 'from' must differ from 'path'")
             elif _is_path_prefix(from_path, to_path):
                 errors.append(f"{prefix}: 'move' cannot move a value into its own subtree")
@@ -124,11 +129,18 @@ def _validate_operation(op: Any, index: int, errors: list[str]) -> None:
         # Note: value is OPTIONAL on copy (for reversibility)
 
 
-def _is_path_prefix(from_path: str, target_path: str) -> bool:
-    """Check if target_path is a descendant of from_path.
+def _same_path(left: str, right: str) -> bool:
+    try:
+        return build_path(parse_path(left)) == build_path(parse_path(right))
+    except (PathError, ValueError):
+        return left == right
 
-    Root path ('$') is excluded — moving from root to a descendant is valid.
-    """
-    if from_path == "$":
+
+def _is_path_prefix(from_path: str, target_path: str) -> bool:
+    """Compare canonical paths so bracket aliases and root obey subtree rules."""
+    try:
+        source = build_path(parse_path(from_path))
+        target = build_path(parse_path(target_path))
+    except (PathError, ValueError):
         return False
-    return target_path.startswith(from_path + ".") or target_path.startswith(from_path + "[")
+    return target.startswith(source + ".") or target.startswith(source + "[")

json_atom-0.4.2/tests/fixtures/README.md

@@ -0,0 +1,6 @@
+# Shared JSON Atom conformance fixtures
+
+Mirrored from [json-atom-format/fixtures](https://github.com/ltwlf/json-atom-format/tree/main/fixtures).
+The specification repository is the source of truth. Keep the JSON files identical across implementations.
+
+Every fixture validates application; level 2 also validates inversion and round-trip recovery.