Object-Entity Mapping (OEM)

text/0072-oem.md

@@ -0,0 +1,97 @@
+# Object-Entity Mapping (OEM)
+
+## Related issues and PRs
+
+- Reference Issues: https://github.com/cedar-policy/cedar/issues/986
+- Implementation PR(s): (leave this empty)
+
+## Timeline
+
+- Started: 2024-06-28
+
+## Summary
+
+Similar to [Object-Relational Mapping (ORM)](https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping), this RFC proposes a macro-based conversion between Rust objects and entities.
+
+## Basic example
+
+The following Rust code defines how type `Team` and type `Member` map to entity type `Example::Team`.
+
+```Rust
+#[derive(Debug, Clone, Cedar)]
+#[cedar(rename="Example::Team")]
+struct Team {
+  #[cedar(eid)]
+  id: String,
+  members: HashSet<Member>
+}
+
+#[derive(Debug, Clone, Cedar)]
+#[cedar(transparent)]
+struct Member {
+  name: String,
+  #[cedar(rename="region")]
+  location: Option<String>,
+}
+```
+An object `Team { id: "A", members: { Member { name: "alice", location: Some("West")}, Member { name: "bob", location: None}}}` is converted to the following entities in JSON,
+
+```JSON
+[
+ {
+    {
+        "uid": { "type": "Team", "id": "A"},
+        "attrs": {
+            "members": [
+                {
+                    "name": "alice",
+                    "location" "West"
+                },
+                {
+                    "name": "bob"
+                }
+            ]
+        },
+        "parents": []
+    }
+ }
+]
+```
+## Motivation
+
+There currently do not exist any convenient methods to programmatically convert Rust objects to entities or vice versa. The status quo of converting a Rust object to an entity is to create an entity without any attributes and then insert attributes. The whole process is akin to that of *manually* serializing Rust objects to JSON, the latter of which is automated by serde. Users should be able to do the same for Rust object to entity conversion. This RFC addresses this need using Rust derive macros.
+
+Moreover, OEM can potentially facilitate the adoption of Cedar on applications using databases. For instance, developers can leverage ORM to seamlessly convert results of database queries into Rust objects and then into entities. That is, developers are able to conveniently construct authorization requests by fetching data from databases.
+
+## Detailed design
+
+Given limited knowledge about Rust macros the proposer has, the design details are subject to significant changes.
+
+The macros over a Rust type eventually expand to implementations of `Into<Entities>`. In the meantime, they also give rise to implementations of `Into<Value>` for this type. By default, the implementation of `Into<Value` for a type produces an entity `uid` unless the type is annotated with the `#[cedar(transparent)]` clause, where it produces a record.
+
+The implementation of `Into<Entities>` for any type annotated with the `#[cedar(transparent)]` clause produces an empty entity slice. Those for types without such annotations construct an entity by iterating its fields. If a field type corresponds to an entity type, the entity slice derived from the field is merged into the final resulting entity slice. That is the reason why a Rust object converts to an entity slice instead of a single entity.
+
+### Value mapping
+
+We require all types of struct fields to implement `Into<Option<Value>>`. The `Option` here is to encode optional attributes. We provide default implementations for various primitive types, `Option<T:Into<Value>>`, `HashMap<S:ToString,T:Into<Value>>`, `HashMap<S:ToString,Option<T:Into<Value>>>`, `HashSet<T:Into<Value>>`.
+
+
+### Entity type and attribute name mapping
+
+We use clause `#[cedar(rename=...)]` to describe entity type/attribute name mappings, where the argument is the string representation of an entity type or attribute name. Entity type/attribute name is the Rust type/field name without such clause.
+
+### Eid mapping
+
+We use clause `#[cedar(eid)]` to denote the field corresponding to the `Eid`. We require the field type to implement `ToString`.
+
+## Drawbacks
+
+Rust macros are unstable and hard to write. Moreover, users may find manual construction of entities not that hard.
+
+## Alternatives
+
+Manual construction of entities.
+
+## Unresolved questions
+
+How do we describe membership relations?