jref_rust

JRef implementation in Rust

A lightweight Rust utility for serializing and deserializing complex object graphs using JSON Pointers (RFC 6901).

Features

• 🔄 Circular Reference Support: Serialize objects that reference themselves without recursion errors.
• 🤝 Object Sharing: Preserve object identity. If multiple keys point to the same object, they will point to the same instance after deserialization.
• 📂 JSON Pointer Syntax: Fully compliant with RFC 6901, including character escaping (~0, ~1).
• 🛠️ Custom Object Support: Automatically handles standard Python classes by serializing their __dict__.
• ⚙️ Customizable: Supply your own reference builders or object identification logic.

Generation Notes

This rust code was generated from the jref_python implementation.

• Identity and Graph Representation: Python's list and dict are inherently reference types that allow shared references and cycles. In Rust, serde_json::Value is a tree-like structure and does not support identity or cycles. To preserve the library's functionality, I introduced JRefValue, which uses Rc<RefCell<...>> for arrays and objects. This allows multiple references to the same data and circular structures, matching Python's behavior.
• serialize Function:
  • In Python, id(subject) is used to track seen objects. In Rust, we use Rc::as_ptr(rc) as usize to get a stable identity for containers.
  • objectnamefield support: If an object (Map) contains the specified field, its value is used as the identity key instead of the pointer address, exactly as in the Python implementation.
  • The pointers map uses an Identity enum to handle both memory addresses and custom names.
• deserialize Function:
  • The Python implementation modifies the structure in-place and relies on Python's reference behavior.
  • The Rust implementation builds the JRefValue graph from the serde_json::Value.
  • To handle circularity and forward/backward references correctly, a location_map tracks location -> JRefValue mappings as objects are created (before their children are fully processed), ensuring that $ref resolution can find partially-built containers.
• JSON Pointer Logic:
  • Implemented escape, unescape, append, and pointer_segments to match Python's logic.
  • apply_segment follows the Python logic, including error messages (mapped to panic! in this translation as an equivalent to Python's TypeError/ValueError when navigating an object).
• URI Encoding:
  • Used urlencoding crate. Note that Python's quote leaves / safe by default. The Rust code replicates this by encoding and then replacing %2F back to / to match the $ref format seen in the tests.
• Types:
  • Python int and float are handled by serde_json::Number.
  • Python None is mapped to JRefValue::Null.
• Testing:
  • Translated all provided unit tests from test_serializer.py into Rust #[test] functions, including scalar tests, reference tests, circularity tests, and custom naming field tests.
  • Identity checks in Rust use Rc::ptr_eq to correspond to Python's is operator.
• Dependencies: The code requires serde, serde_json, and urlencoding.