From 5be51720d74ffd87188867e78c9aa3ecc292d0dd Mon Sep 17 00:00:00 2001
From: cbullinger <cory.bullinger@mongodb.com>
Date: Thu, 24 Aug 2023 21:52:43 -0400
Subject: [PATCH] Add cheatsheet snippets

---
 .../mongodb/realm/realmkmmapp/DataTypes.kt    | 479 ++++++++++++++++++
 ...Types.snippet.backlinks-embedded-object.kt |   1 +
 ...ataTypes.snippet.backlinks-realm-object.kt |   1 +
 .../kotlin/DataTypes.snippet.bool-optional.kt |   1 +
 .../kotlin/DataTypes.snippet.bool-required.kt |   1 +
 .../kotlin/DataTypes.snippet.byte-optional.kt |   1 +
 .../kotlin/DataTypes.snippet.byte-required.kt |   1 +
 .../kotlin/DataTypes.snippet.char-optional.kt |   1 +
 .../kotlin/DataTypes.snippet.char-required.kt |   1 +
 .../kotlin/DataTypes.snippet.create-uuid.kt   |   2 +
 .../DataTypes.snippet.decimal128-optional.kt  |   1 +
 .../DataTypes.snippet.decimal128-required.kt  |   1 +
 .../DataTypes.snippet.dictionary-required.kt  |   1 +
 .../DataTypes.snippet.double-optional.kt      |   1 +
 .../DataTypes.snippet.double-required.kt      |   1 +
 ...aTypes.snippet.embedded-object-optional.kt |   1 +
 .../DataTypes.snippet.float-optional.kt       |   1 +
 .../DataTypes.snippet.float-required.kt       |   1 +
 .../kotlin/DataTypes.snippet.int-optional.kt  |   1 +
 .../kotlin/DataTypes.snippet.int-required.kt  |   1 +
 .../kotlin/DataTypes.snippet.list-required.kt |   2 +
 .../kotlin/DataTypes.snippet.long-optional.kt |   1 +
 .../kotlin/DataTypes.snippet.long-required.kt |   1 +
 ...aTypes.snippet.mutableRealmInt-optional.kt |   1 +
 ...aTypes.snippet.mutableRealmInt-required.kt |   2 +
 .../DataTypes.snippet.objectId-optional.kt    |   1 +
 .../DataTypes.snippet.objectId-required.kt    |   1 +
 ...DataTypes.snippet.realm-object-optional.kt |   1 +
 .../DataTypes.snippet.realmAny-optional.kt    |   1 +
 ...DataTypes.snippet.realmInstant-optional.kt |   1 +
 ...DataTypes.snippet.realmInstant-required.kt |   1 +
 .../kotlin/DataTypes.snippet.set-required.kt  |   1 +
 .../DataTypes.snippet.short-optional.kt       |   1 +
 .../DataTypes.snippet.short-required.kt       |   1 +
 .../DataTypes.snippet.string-optional.kt      |   1 +
 .../DataTypes.snippet.string-required.kt      |   1 +
 .../kotlin/DataTypes.snippet.uuid-optional.kt |   1 +
 .../kotlin/DataTypes.snippet.uuid-required.kt |   1 +
 .../sdk/kotlin/realm-database/crud/create.txt |   4 +-
 .../realm-database/schemas/relationships.txt  |   3 +
 .../schemas/supported-types.txt               | 462 +++++++++++------
 .../realm-database/write-transactions.txt     |   2 +
 42 files changed, 847 insertions(+), 143 deletions(-)
 create mode 100644 examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/DataTypes.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.backlinks-embedded-object.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.backlinks-realm-object.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.bool-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.bool-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.byte-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.byte-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.char-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.char-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.create-uuid.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.decimal128-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.decimal128-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.dictionary-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.double-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.double-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.embedded-object-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.float-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.float-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.int-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.int-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.list-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.long-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.long-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.mutableRealmInt-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.mutableRealmInt-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.objectId-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.objectId-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.realm-object-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.realmAny-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.realmInstant-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.realmInstant-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.set-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.short-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.short-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.string-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.string-required.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.uuid-optional.kt
 create mode 100644 source/examples/generated/kotlin/DataTypes.snippet.uuid-required.kt

diff --git a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/DataTypes.kt b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/DataTypes.kt
new file mode 100644
index 00000000000..a3afa4d9e21
--- /dev/null
+++ b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/DataTypes.kt
@@ -0,0 +1,479 @@
+package com.mongodb.realm.realmkmmapp
+
+import io.realm.kotlin.Realm
+import io.realm.kotlin.RealmConfiguration
+import io.realm.kotlin.ext.*
+import io.realm.kotlin.internal.platform.runBlocking
+import io.realm.kotlin.query.RealmResults
+import io.realm.kotlin.types.*
+import org.mongodb.kbson.Decimal128
+import org.mongodb.kbson.ObjectId
+import kotlin.test.*
+
+
+class CustomObjectType : RealmObject {
+    var uuid: RealmUUID = RealmUUID.random()
+    // var embeddedProperty1: EmbeddedObjectType = EmbeddedObjectType() //Property 'CustomObjectType.embeddedProperty' of type 'object' must be nullable.
+    // :snippet-start: embedded-object-optional
+    var embeddedProperty: EmbeddedObjectType? = null
+    // :snippet-end:
+    //var embeddedProperties: RealmList<EmbeddedObjectType> = null // [Realm] Error in field embeddedProperties - RealmList does not support nullable realm objects element types.
+}
+
+class AnotherCustomObjectType : RealmObject {
+    var uuid: RealmUUID = RealmUUID.random()
+   // var realmObjectProperty: CustomObjectType = CustomObjectType() // Property 'AnotherCustomObjectType.realmObjectProperty' of type 'object' must be nullable.
+    // :snippet-start: realm-object-optional
+    var realmObjectPropertyOptional: CustomObjectType? = null
+    // :snippet-end:
+}
+
+class EmbeddedObjectType : EmbeddedRealmObject {
+    var uuid: RealmUUID = RealmUUID.random()
+}
+
+class ParentObjectType : RealmObject {
+    var uuid: RealmUUID = RealmUUID.random() // :remove:
+    var children: RealmList<ChildObjectType> = realmListOf()
+    var embeddedChildren: RealmList<EmbeddedChildObjectType> = realmListOf()
+}
+
+class ChildObjectType : RealmObject {
+    var uuid: RealmUUID = RealmUUID.from("11111111-1111-1111-1111-111111111111")
+    // :snippet-start: backlinks-realm-object
+    val child: RealmResults<ParentObjectType> by backlinks(ParentObjectType::children)
+    // :snippet-end:
+}
+
+class EmbeddedChildObjectType : EmbeddedRealmObject {
+    var uuid: RealmUUID = RealmUUID.from("22222222-2222-2222-2222-222222222222")
+    // :snippet-start: backlinks-embedded-object
+    val child: ParentObjectType by backlinks(ParentObjectType::embeddedChildren)
+    // :snippet-end:
+}
+
+class KotlinSupportedTypes : RealmObject {
+    // :snippet-start: bool-required
+    var boolReq: Boolean = false
+    // :snippet-end:
+    // :snippet-start: bool-optional
+    var boolOpt: Boolean? = null
+    // :snippet-end:
+    // :snippet-start: int-required
+    var intReq: Int = 0
+    // :snippet-end:
+    // :snippet-start: int-optional
+    var intOpt: Int? = null
+    // :snippet-end:
+    // :snippet-start: long-required
+    var longReq: Long = 0L
+    // :snippet-end:
+    // :snippet-start: long-optional
+    var longOpt: Long? = null
+    // :snippet-end:
+    // :snippet-start: float-required
+    var floatReq: Float = 0.0f
+    // :snippet-end:
+    // :snippet-start: float-optional
+    var floatOpt: Float? = null
+    // :snippet-end:
+    // :snippet-start: double-required
+    var doubleReq: Double = 0.0
+    // :snippet-end:
+    // :snippet-start: double-optional
+    var doubleOpt: Double? = null
+    // :snippet-end:
+    // :snippet-start: short-required
+    var shortReq: Short = 0
+    // :snippet-end:
+    // :snippet-start: short-optional
+    var shortOpt: Short? = null
+    // :snippet-end:
+    // :snippet-start: string-required
+    var stringReq: String = ""
+    // :snippet-end:
+    // :snippet-start: string-optional
+    var stringOpt: String? = null
+    // :snippet-end:
+    // :snippet-start: byte-required
+    var byteReq: Byte = 0
+    // :snippet-end:
+    // :snippet-start: byte-optional
+    var byteOpt: Byte? = null
+    // :snippet-end:
+    // :snippet-start: char-required
+    var charReq: Char = 'a'
+    // :snippet-end:
+    // :snippet-start: char-optional
+    var charOpt: Char? = null
+    // :snippet-end:
+    //var enumReq: MyEnum = MyEnum.ONE //[Realm] Realm does not support persisting properties of this type. Mark the field with `@Ignore` to suppress this error.
+    // var enumOpt: MyEnum? = null //[Realm] Realm does not support persisting properties of this type. Mark the field with `@Ignore` to suppress this error.
+}
+
+class BSONSupportedTypes : RealmObject {
+    // :snippet-start: decimal128-required
+    var decimal128Req: Decimal128 = Decimal128("123.456")
+    // :snippet-end:
+    // :snippet-start: decimal128-optional
+    var decimal128Opt: Decimal128? = null
+    // :snippet-end:
+    // :snippet-start: objectId-required
+    var objectIdReq: ObjectId = ObjectId()
+    // :snippet-end:
+    // :snippet-start: objectId-optional
+    var objectIdOpt: ObjectId? = null
+    // :snippet-end:
+}
+
+class RealmSupportedTypes : RealmObject {
+
+    // :snippet-start: realmInstant-required
+    var realmInstantReq: RealmInstant = RealmInstant.now()
+    // :snippet-end:
+    // :snippet-start: realmInstant-optional
+    var realmInstantOpt: RealmInstant? = null
+    // :snippet-end:
+    // :snippet-start: mutableRealmInt-required
+    var mutableRealmIntReq: MutableRealmInt =
+        MutableRealmInt.create(0)
+    // :snippet-end:
+    // :snippet-start: mutableRealmInt-optional
+    var mutableRealmIntOpt: MutableRealmInt? = null
+    // :snippet-end:
+    // :snippet-start: list-required
+    var listReq: RealmList<CustomObjectType> = realmListOf()
+    // :snippet-end:
+   // var listOpt: RealmList<CustomObjectType?> = realmListOf() // [Realm] Error in field listOpt - RealmList does not support nullable realm objects element types.
+   // var listOpt: RealmList<String>? = null // [Realm] Error in field listOpt - a RealmList field cannot be marked as nullable.
+    var listOpt1: RealmList<String?> = realmListOf()
+   // var listOpt2: RealmList<CustomObjectType>? = null //null cannot be cast to non-null type io.realm.kotlin.types.RealmList<*>
+    var listOpt3: RealmList<CustomObjectType>? = realmListOf()
+    var listOpt4: RealmList<EmbeddedObjectType>? = realmListOf()
+    //var listOpt5: RealmList<EmbeddedObjectType?> = realmListOf() // [Realm] Error in field listOpt5 - RealmList does not support nullable realm objects element types.
+    // :snippet-start: set-required
+    var setReq: RealmSet<String> = realmSetOf()
+    // :snippet-end:
+    //var setOpt: RealmSet<String>? = null // [Realm] Error in field setOpt - a RealmSet field cannot be marked as nullable.
+    //  val mapReq: RealmMap<String, String> = mapOf("foo" to "bar")
+    // var mapOpt: RealmMap<String, String>? = null //[Realm] Realm does not support persisting properties of this type. Mark the field with `@Ignore` to suppress this error.
+    // :snippet-start: dictionary-required
+    var dictionaryReq: RealmDictionary<String> = realmDictionaryOf()
+    // :snippet-end:
+    // var dictionaryOpt: RealmDictionary<String>? = null //[Realm] Error in field dictionaryOpt - a RealmDictionary field cannot be marked as nullable.
+    var dictionaryOpt: RealmDictionary<String?> = realmDictionaryOf()
+    // :snippet-start: realmAny-optional
+    var realmAnyOpt: RealmAny? = RealmAny.create("foo")
+    // :snippet-end:
+    // :snippet-start: uuid-required
+    var uuidReq: RealmUUID = RealmUUID.random()
+    // :snippet-end:
+    // :snippet-start: uuid-optional
+    var uuidOpt: RealmUUID? = null
+    // :snippet-end:
+}
+
+class SupportedDataTypesTest : RealmTest() {
+
+    @Test
+    fun populateKotlinPropertiesTest() {
+        runBlocking {
+            val config = RealmConfiguration.Builder(setOf(KotlinSupportedTypes::class))
+                .inMemory()
+                .build()
+            val realm = Realm.open(config)
+            Log.v("Successfully opened realm: ${realm.configuration.path}")
+
+            val kotlinSupportedTypes = KotlinSupportedTypes().apply{}
+
+
+            realm.write {
+                copyToRealm(kotlinSupportedTypes)
+
+                val kotlinSupportedTypesResult = query<KotlinSupportedTypes>().find().first()
+                assertFalse(kotlinSupportedTypesResult.boolReq)
+                assertNull(kotlinSupportedTypesResult.boolOpt)
+                assertEquals(0, kotlinSupportedTypesResult.intReq)
+                assertNull(kotlinSupportedTypesResult.intOpt)
+                assertEquals(0L, kotlinSupportedTypesResult.longReq)
+                assertNull(kotlinSupportedTypesResult.longOpt)
+                assertEquals(0.0f, kotlinSupportedTypesResult.floatReq)
+                assertNull(kotlinSupportedTypesResult.floatOpt)
+                assertEquals(0.0, kotlinSupportedTypesResult.doubleReq)
+                assertNull(kotlinSupportedTypesResult.doubleOpt)
+                assertEquals(0, kotlinSupportedTypesResult.shortReq)
+                assertNull(kotlinSupportedTypesResult.shortOpt)
+                assertEquals("", kotlinSupportedTypesResult.stringReq)
+                assertNull(kotlinSupportedTypesResult.stringOpt)
+                assertEquals(0, kotlinSupportedTypesResult.byteReq)
+                assertNull(kotlinSupportedTypesResult.byteOpt)
+                assertEquals('a', kotlinSupportedTypesResult.charReq)
+                assertNull(kotlinSupportedTypesResult.charOpt)
+                delete(kotlinSupportedTypesResult)
+            }
+            realm.close()
+        }
+    }
+
+    @Test
+    fun populateKotlinPropertiesWithValuesTest() {
+        runBlocking {
+            val config = RealmConfiguration.Builder(setOf(KotlinSupportedTypes::class))
+                .inMemory()
+                .build()
+            val realm = Realm.open(config)
+            Log.v("Successfully opened realm: ${realm.configuration.path}")
+
+            val kotlinSupportedTypes = KotlinSupportedTypes().apply {
+                boolReq = true
+                boolOpt = false
+                intReq = 1
+                intOpt = 2
+                longReq = 3L
+                longOpt = 4L
+                floatReq = 5.0f
+                floatOpt = 6.0f
+                doubleReq = 7.0
+                doubleOpt = 8.0
+                shortReq = 9
+                shortOpt = 10
+                stringReq = "string1"
+                stringOpt = "string2"
+                byteReq = 11
+                byteOpt = 12
+                charReq = 'a'
+                charOpt = 'b'
+            }
+            realm.write {
+                copyToRealm(kotlinSupportedTypes)
+            }
+            val kotlinSupportedTypesResult = realm.query<KotlinSupportedTypes>().find().first()
+            assertTrue(kotlinSupportedTypesResult.boolReq)
+            assertFalse(kotlinSupportedTypesResult.boolOpt!!)
+            assertEquals(1, kotlinSupportedTypesResult.intReq)
+            assertEquals(2, kotlinSupportedTypesResult.intOpt!!)
+            assertEquals(3L, kotlinSupportedTypesResult.longReq)
+            assertEquals(4L, kotlinSupportedTypesResult.longOpt!!)
+            assertEquals(5.0f, kotlinSupportedTypesResult.floatReq)
+            assertEquals(6.0f, kotlinSupportedTypesResult.floatOpt!!)
+            assertEquals(7.0, kotlinSupportedTypesResult.doubleReq)
+            assertEquals(8.0, kotlinSupportedTypesResult.doubleOpt!!)
+            assertEquals(9, kotlinSupportedTypesResult.shortReq)
+            assertEquals(10, kotlinSupportedTypesResult.shortOpt!!)
+            assertEquals("string1", kotlinSupportedTypesResult.stringReq)
+            assertEquals("string2", kotlinSupportedTypesResult.stringOpt!!)
+            assertEquals(11, kotlinSupportedTypesResult.byteReq)
+            assertEquals(12, kotlinSupportedTypesResult.byteOpt!!)
+            assertEquals('a', kotlinSupportedTypesResult.charReq)
+            assertEquals('b', kotlinSupportedTypesResult.charOpt!!)
+
+            realm.write {
+                val kotlinSupportedTypes = query<KotlinSupportedTypes>().find().first()
+                delete(kotlinSupportedTypes)
+            }
+            realm.close()
+        }
+    }
+
+    @Test
+    fun populateBSONPropertiesTest() {
+        runBlocking {
+            val config = RealmConfiguration.Builder(setOf(BSONSupportedTypes::class))
+                .inMemory()
+                .build()
+            val realm = Realm.open(config)
+            Log.v("Successfully opened realm: ${realm.configuration.path}")
+
+            val bsonSupportedTypes = BSONSupportedTypes().apply {}
+
+            realm.write {
+                copyToRealm(bsonSupportedTypes)
+                val bsonSupportedTypesResult = query<BSONSupportedTypes>().find().first()
+                assertEquals(Decimal128("123.456"), bsonSupportedTypesResult.decimal128Req)
+                assertNull(bsonSupportedTypesResult.decimal128Opt)
+                assertNotNull(bsonSupportedTypesResult.objectIdReq)
+                assertNull(bsonSupportedTypesResult.objectIdOpt)
+                delete(bsonSupportedTypesResult)
+            }
+            realm.close()
+        }
+    }
+
+    @Test
+    fun populateBSONPropertiesWithValuesTest() {
+        runBlocking {
+            val config = RealmConfiguration.Builder(setOf(BSONSupportedTypes::class))
+                .inMemory()
+                .build()
+            val realm = Realm.open(config)
+            Log.v("Successfully opened realm: ${realm.configuration.path}")
+
+            val oidReq = ObjectId()
+            val oidOpt = ObjectId()
+
+            val bsonSupportedTypes = BSONSupportedTypes().apply{
+                decimal128Req = Decimal128("111.222")
+                decimal128Opt = Decimal128("789.012")
+                objectIdReq = oidReq
+                objectIdOpt = oidOpt
+            }
+            realm.write {
+                copyToRealm(bsonSupportedTypes)
+            }
+            val bsonSupportedTypesResult = realm.query<BSONSupportedTypes>().find().first()
+            assertEquals(Decimal128("111.222"), bsonSupportedTypesResult.decimal128Req)
+            assertEquals(Decimal128("789.012"), bsonSupportedTypesResult.decimal128Opt)
+            assertEquals(oidReq, bsonSupportedTypesResult.objectIdReq)
+            assertEquals(oidOpt, bsonSupportedTypesResult.objectIdOpt)
+
+            realm.write {
+                val bsonSupportedTypes = query<BSONSupportedTypes>().find().first()
+                delete(bsonSupportedTypes)
+            }
+            realm.close()
+        }
+    }
+
+    @Test
+    fun populateRealmPropertiesTest() {
+        runBlocking {
+            val config = RealmConfiguration.Builder(setOf(RealmSupportedTypes::class, CustomObjectType::class, AnotherCustomObjectType::class, EmbeddedObjectType::class))
+                .inMemory()
+                .build()
+            val realm = Realm.open(config)
+            Log.v("Successfully opened realm: ${realm.configuration.path}")
+
+            val realmSupportedTypes = RealmSupportedTypes().apply {}
+            val customObjectType = AnotherCustomObjectType().apply {}
+
+            realm.write {
+                copyToRealm(realmSupportedTypes)
+                copyToRealm(customObjectType)
+
+                val realmSupportedTypesResult = query<RealmSupportedTypes>().find().first()
+                val customObjectTypeResult = query<AnotherCustomObjectType>().find().first()
+                assertNotNull(realmSupportedTypesResult.realmInstantReq)
+                assertNull(realmSupportedTypesResult.realmInstantOpt)
+                assertEquals(0, realmSupportedTypesResult.mutableRealmIntReq.get())
+                assertNull(realmSupportedTypesResult.mutableRealmIntOpt)
+                assertEquals(0, realmSupportedTypesResult.listReq.size)
+                assertEquals(0, realmSupportedTypesResult.setReq.size)
+                assertEquals(0, realmSupportedTypesResult.dictionaryReq.size)
+                realmSupportedTypesResult.realmAnyReq?.let { assertEquals("foo", it.asString()) }
+                assertNull(realmSupportedTypesResult.realmAnyOpt)
+                assertNotNull(realmSupportedTypesResult.uuidReq)
+                assertNull(realmSupportedTypesResult.uuidOpt)
+                assertNotNull(customObjectTypeResult.uuid)
+                assertNull(customObjectTypeResult.realmObjectPropertyOptional)
+                delete(realmSupportedTypesResult)
+                delete(customObjectTypeResult)
+            }
+            realm.close()
+        }
+    }
+
+    @Test
+    fun populateRealmPropertiesWithValuesTest() {
+        runBlocking {
+            val config = RealmConfiguration.Builder(setOf(RealmSupportedTypes::class, CustomObjectType::class, AnotherCustomObjectType::class, EmbeddedObjectType::class))
+                .inMemory()
+                .build()
+            val realm = Realm.open(config)
+            Log.v("Successfully opened realm: ${realm.configuration.path}")
+
+            // :snippet-start: create-uuid
+            val uuid1 = RealmUUID.from("46423f1b-ce3e-4a7e-812f-004cf9c42d76")
+            val uuid2 = RealmUUID.random()
+            // :snippet-end:
+            val date1 = RealmInstant.from(0, 1)
+            val date2 = RealmInstant.from(1, 0)
+            val int1 = MutableRealmInt.create(1)
+            val int2 = MutableRealmInt.create(2)
+
+            val realmSupportedTypes = RealmSupportedTypes().apply {
+                realmInstantReq = date1
+                realmInstantOpt = date2
+                mutableRealmIntReq = int1
+                mutableRealmIntOpt = int2
+                listReq.add(CustomObjectType().apply {
+                    uuid = uuid1
+                    embeddedProperty = EmbeddedObjectType().apply { uuid = uuid2 } })
+                setReq.add("hello")
+                dictionaryReq["bing"] = "bong"
+                realmAnyOpt = RealmAny.create(123)
+                uuidReq = uuid1
+                uuidOpt = uuid2
+            }
+            val customObjectType = CustomObjectType().apply {
+                uuid = uuid1
+                embeddedProperty = EmbeddedObjectType().apply { uuid = uuid1 }
+            }
+
+            val anotherCustomObjectType = AnotherCustomObjectType().apply {
+                uuid = uuid2
+                realmObjectPropertyOptional = customObjectType
+            }
+
+            realm.write {
+                copyToRealm(realmSupportedTypes)
+                copyToRealm(anotherCustomObjectType)
+            }
+
+            val realmSupportedTypesResult = realm.query<RealmSupportedTypes>().find().first()
+            val customObjectTypeResult = realm.query<CustomObjectType>().find().first()
+            assertEquals(date1, realmSupportedTypesResult.realmInstantReq)
+            assertEquals(date2, realmSupportedTypesResult.realmInstantOpt)
+            assertEquals(1, realmSupportedTypesResult.mutableRealmIntReq.get())
+            assertEquals(2, realmSupportedTypesResult.mutableRealmIntOpt!!.get())
+            assertEquals(1, realmSupportedTypesResult.listReq.size)
+            assertEquals(uuid2, realmSupportedTypesResult.listReq.first().embeddedProperty?.uuid)
+            assertEquals(uuid1, realmSupportedTypesResult.listReq.first().uuid)
+            assertEquals(1, realmSupportedTypesResult.setReq.size)
+            assertEquals("hello", realmSupportedTypesResult.setReq.first())
+            assertEquals(1, realmSupportedTypesResult.dictionaryReq.size)
+            assertEquals("bong", realmSupportedTypesResult.dictionaryReq["bing"])
+            assertEquals(123, realmSupportedTypesResult.realmAnyOpt!!.asInt())
+            assertEquals(uuid1, realmSupportedTypesResult.uuidReq)
+            assertEquals(uuid2, realmSupportedTypesResult.uuidOpt)
+            assertEquals(uuid1, customObjectTypeResult.uuid)
+            assertEquals(uuid2, anotherCustomObjectType.uuid)
+
+            realm.write {
+                val realmSupportedTypes = query<RealmSupportedTypes>().find().first()
+                val customObjectType = query<CustomObjectType>().find().first()
+                delete(realmSupportedTypes)
+                delete(customObjectType)
+            }
+            realm.close()
+        }
+
+    }
+
+    @Test
+    fun populateRelationshipPropertiesTest() {
+        runBlocking {
+            val config = RealmConfiguration.Builder(setOf(EmbeddedObjectType::class, ParentObjectType::class, ChildObjectType::class, EmbeddedChildObjectType::class))
+                .inMemory()
+                .build()
+            val realm = Realm.open(config)
+            Log.v("Successfully opened realm: ${realm.configuration.path}")
+
+            val parent = ParentObjectType().apply {
+                children.add(ChildObjectType().apply {})
+                embeddedChildren.add(EmbeddedChildObjectType().apply {})
+            }
+
+            realm.write {
+                copyToRealm(parent)
+                val parentResult = query<ParentObjectType>().find().first()
+
+                assertEquals(1, parentResult.children.size)
+                assertEquals("11111111-1111-1111-1111-111111111111", parentResult.children.first().uuid.toString())
+                assertEquals(1, parentResult.embeddedChildren.size)
+                assertEquals("22222222-2222-2222-2222-222222222222", parentResult.embeddedChildren.first().uuid.toString())
+                delete(parentResult)
+            }
+        }
+    }
+
+}
\ No newline at end of file
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.backlinks-embedded-object.kt b/source/examples/generated/kotlin/DataTypes.snippet.backlinks-embedded-object.kt
new file mode 100644
index 00000000000..b555520e0eb
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.backlinks-embedded-object.kt
@@ -0,0 +1 @@
+val child: ParentObjectType by backlinks(ParentObjectType::embeddedChildren)
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.backlinks-realm-object.kt b/source/examples/generated/kotlin/DataTypes.snippet.backlinks-realm-object.kt
new file mode 100644
index 00000000000..69f98e8fbed
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.backlinks-realm-object.kt
@@ -0,0 +1 @@
+val child: RealmResults<ParentObjectType> by backlinks(ParentObjectType::children)
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.bool-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.bool-optional.kt
new file mode 100644
index 00000000000..b5fdb0e5a07
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.bool-optional.kt
@@ -0,0 +1 @@
+var boolOpt: Boolean? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.bool-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.bool-required.kt
new file mode 100644
index 00000000000..bc734d15ba7
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.bool-required.kt
@@ -0,0 +1 @@
+var boolReq: Boolean = false
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.byte-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.byte-optional.kt
new file mode 100644
index 00000000000..4e2d8911b29
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.byte-optional.kt
@@ -0,0 +1 @@
+var byteOpt: Byte? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.byte-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.byte-required.kt
new file mode 100644
index 00000000000..1311e1ed0b3
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.byte-required.kt
@@ -0,0 +1 @@
+var byteReq: Byte = 0
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.char-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.char-optional.kt
new file mode 100644
index 00000000000..7afc6dc6a62
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.char-optional.kt
@@ -0,0 +1 @@
+var charOpt: Char? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.char-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.char-required.kt
new file mode 100644
index 00000000000..39f878c308a
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.char-required.kt
@@ -0,0 +1 @@
+var charReq: Char = 'a'
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.create-uuid.kt b/source/examples/generated/kotlin/DataTypes.snippet.create-uuid.kt
new file mode 100644
index 00000000000..e3fe6556313
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.create-uuid.kt
@@ -0,0 +1,2 @@
+val uuid1 = RealmUUID.from("46423f1b-ce3e-4a7e-812f-004cf9c42d76")
+val uuid2 = RealmUUID.random()
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.decimal128-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.decimal128-optional.kt
new file mode 100644
index 00000000000..89dbd7c9254
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.decimal128-optional.kt
@@ -0,0 +1 @@
+var decimal128Opt: Decimal128? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.decimal128-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.decimal128-required.kt
new file mode 100644
index 00000000000..d9cabf5cf0e
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.decimal128-required.kt
@@ -0,0 +1 @@
+var decimal128Req: Decimal128 = Decimal128("123.456")
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.dictionary-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.dictionary-required.kt
new file mode 100644
index 00000000000..63d589cac0a
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.dictionary-required.kt
@@ -0,0 +1 @@
+var dictionaryReq: RealmDictionary<String> = realmDictionaryOf()
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.double-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.double-optional.kt
new file mode 100644
index 00000000000..695753a9e91
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.double-optional.kt
@@ -0,0 +1 @@
+var doubleOpt: Double? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.double-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.double-required.kt
new file mode 100644
index 00000000000..cd2ac749a6d
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.double-required.kt
@@ -0,0 +1 @@
+var doubleReq: Double = 0.0
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.embedded-object-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.embedded-object-optional.kt
new file mode 100644
index 00000000000..0eee5b66a3d
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.embedded-object-optional.kt
@@ -0,0 +1 @@
+var embeddedProperty: EmbeddedObjectType? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.float-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.float-optional.kt
new file mode 100644
index 00000000000..e4b9e95a3fc
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.float-optional.kt
@@ -0,0 +1 @@
+var floatOpt: Float? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.float-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.float-required.kt
new file mode 100644
index 00000000000..748fe65cfe5
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.float-required.kt
@@ -0,0 +1 @@
+var floatReq: Float = 0.0f
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.int-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.int-optional.kt
new file mode 100644
index 00000000000..9748bcdab44
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.int-optional.kt
@@ -0,0 +1 @@
+var intOpt: Int? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.int-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.int-required.kt
new file mode 100644
index 00000000000..9c8eabc05a0
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.int-required.kt
@@ -0,0 +1 @@
+var intReq: Int = 0
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.list-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.list-required.kt
new file mode 100644
index 00000000000..b344683eb2e
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.list-required.kt
@@ -0,0 +1,2 @@
+var listReq: RealmList<CustomObjectType> =
+    realmListOf()
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.long-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.long-optional.kt
new file mode 100644
index 00000000000..f75cbb5e336
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.long-optional.kt
@@ -0,0 +1 @@
+var longOpt: Long? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.long-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.long-required.kt
new file mode 100644
index 00000000000..8108da784c5
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.long-required.kt
@@ -0,0 +1 @@
+var longReq: Long = 0L
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.mutableRealmInt-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.mutableRealmInt-optional.kt
new file mode 100644
index 00000000000..a3c441f4754
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.mutableRealmInt-optional.kt
@@ -0,0 +1 @@
+var mutableRealmIntOpt: MutableRealmInt? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.mutableRealmInt-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.mutableRealmInt-required.kt
new file mode 100644
index 00000000000..d3322108f93
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.mutableRealmInt-required.kt
@@ -0,0 +1,2 @@
+var mutableRealmIntReq: MutableRealmInt =
+    MutableRealmInt.create(0)
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.objectId-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.objectId-optional.kt
new file mode 100644
index 00000000000..2b45ce16dda
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.objectId-optional.kt
@@ -0,0 +1 @@
+var objectIdOpt: ObjectId? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.objectId-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.objectId-required.kt
new file mode 100644
index 00000000000..a6c0bf2e236
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.objectId-required.kt
@@ -0,0 +1 @@
+var objectIdReq: ObjectId = ObjectId()
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.realm-object-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.realm-object-optional.kt
new file mode 100644
index 00000000000..4c40fb8e9c9
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.realm-object-optional.kt
@@ -0,0 +1 @@
+var realmObjectPropertyOptional: CustomObjectType? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.realmAny-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.realmAny-optional.kt
new file mode 100644
index 00000000000..2da2336c3d3
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.realmAny-optional.kt
@@ -0,0 +1 @@
+var realmAnyOpt: RealmAny? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.realmInstant-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.realmInstant-optional.kt
new file mode 100644
index 00000000000..2be5bd44a23
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.realmInstant-optional.kt
@@ -0,0 +1 @@
+var realmInstantOpt: RealmInstant? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.realmInstant-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.realmInstant-required.kt
new file mode 100644
index 00000000000..f50391c5841
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.realmInstant-required.kt
@@ -0,0 +1 @@
+var realmInstantReq: RealmInstant = RealmInstant.now()
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.set-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.set-required.kt
new file mode 100644
index 00000000000..6ae5b86f28e
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.set-required.kt
@@ -0,0 +1 @@
+var setReq: RealmSet<String> = realmSetOf()
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.short-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.short-optional.kt
new file mode 100644
index 00000000000..0bd98879110
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.short-optional.kt
@@ -0,0 +1 @@
+var shortOpt: Short? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.short-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.short-required.kt
new file mode 100644
index 00000000000..2678a755f72
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.short-required.kt
@@ -0,0 +1 @@
+var shortReq: Short = 0
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.string-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.string-optional.kt
new file mode 100644
index 00000000000..1fec6ab9135
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.string-optional.kt
@@ -0,0 +1 @@
+var stringOpt: String? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.string-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.string-required.kt
new file mode 100644
index 00000000000..0a1b93a4c61
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.string-required.kt
@@ -0,0 +1 @@
+var stringReq: String = ""
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.uuid-optional.kt b/source/examples/generated/kotlin/DataTypes.snippet.uuid-optional.kt
new file mode 100644
index 00000000000..98d45866b55
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.uuid-optional.kt
@@ -0,0 +1 @@
+var uuidOpt: RealmUUID? = null
diff --git a/source/examples/generated/kotlin/DataTypes.snippet.uuid-required.kt b/source/examples/generated/kotlin/DataTypes.snippet.uuid-required.kt
new file mode 100644
index 00000000000..6a933b3d469
--- /dev/null
+++ b/source/examples/generated/kotlin/DataTypes.snippet.uuid-required.kt
@@ -0,0 +1 @@
+var uuidReq: RealmUUID = RealmUUID.random()
diff --git a/source/sdk/kotlin/realm-database/crud/create.txt b/source/sdk/kotlin/realm-database/crud/create.txt
index cafe153799b..150756d1fab 100644
--- a/source/sdk/kotlin/realm-database/crud/create.txt
+++ b/source/sdk/kotlin/realm-database/crud/create.txt
@@ -50,11 +50,13 @@ To persist a new object to a realm:
    You can also upsert into a realm using specific criteria. See 
    :ref:`Upsert a Realm Object <kotlin-upsert-an-object>`.
 
+.. _kotlin-create-a-collection:
+
 Create a Collection
 -------------------
 
 You can create collections of items using 
-``RealmList``, ``RealmSet``, and ``RealmMap`` types.
+``RealmList``, ``RealmSet``, and ``RealmDictionary`` types.
 
 You can also register a notification handler to listen for changes to a 
 collection. For more information, see 
diff --git a/source/sdk/kotlin/realm-database/schemas/relationships.txt b/source/sdk/kotlin/realm-database/schemas/relationships.txt
index 9e5cc62344a..824917a2fd7 100644
--- a/source/sdk/kotlin/realm-database/schemas/relationships.txt
+++ b/source/sdk/kotlin/realm-database/schemas/relationships.txt
@@ -1,4 +1,5 @@
 .. _kotlin-relationships:
+.. _kotlin-reference-realm-object:
 
 ==========================
 Relationships - Kotlin SDK
@@ -95,6 +96,8 @@ many-to-many and a one-to-many relationship is up to your application.
    instance, if a "Sushi" object has many "Fish" objects, you must specify the
    "Sushi.fishes" as a ``RealmList`` or ``RealmSet`` of ``Fish`` objects.
 
+.. _kotlin-inverse-relationships:
+
 Inverse Relationships
 ---------------------
 
diff --git a/source/sdk/kotlin/realm-database/schemas/supported-types.txt b/source/sdk/kotlin/realm-database/schemas/supported-types.txt
index 0dc25c110bb..1dcf91bacee 100644
--- a/source/sdk/kotlin/realm-database/schemas/supported-types.txt
+++ b/source/sdk/kotlin/realm-database/schemas/supported-types.txt
@@ -11,12 +11,10 @@ Supported Types - Kotlin SDK
    :depth: 2
    :class: singlecol
 
-
 The Kotlin SDK supports `Kotlin types 
 <https://kotlinlang.org/docs/basic-types.html>`__, a limited subset of
 `BSON <https://bsonspec.org/>`__ types, and 
 :wikipedia:`UUID <Universally_unique_identifier>`.
-
 Additionally, the Kotlin SDK offers Realm-specific types, including types 
 that you can use for unique identifiers, timestamps, counters, and collections.
 
@@ -27,12 +25,20 @@ Supported Data Types List
 
 The Realm Kotlin SDK supports the following Kotlin data types, 
 MongoDB BSON types, and Realm-specific types.
-
-You can use these types to define your object model 
-properties.
+You can use these types to define your object model properties.
+For more information, see :ref:`Define an Object Model <kotlin-define-object-model>`.
 
 .. include:: /includes/map-to-bson-type.rst
 
+**Kotlin Data Types**
+
+The following table lists the supported Kotlin data types and examples of 
+how to declare them as required or optional properties in your object model.
+
+Note that Realm stores all non-decimal numeric types as ``Long`` 
+values. Similarly, Realm stores all decimal numeric types as 
+``Double`` values.
+
 .. list-table:: 
    :header-rows: 1
    :stub-columns: 1
@@ -41,33 +47,67 @@ properties.
    * - Kotlin Data Type
      - Required
      - Optional
+
    * - ``String``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.string-required.kt
+         :language: kotlin     
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.string-optional.kt
+         :language: kotlin
+
    * - ``Byte``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.byte-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.byte-optional.kt
+         :language: kotlin
+
    * - ``Short``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.short-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.short-optional.kt
+         :language: kotlin
+
    * - ``Int``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.int-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.int-optional.kt
+         :language: kotlin
+
    * - ``Long``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.long-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.long-optional.kt
+         :language: kotlin
+
    * - ``Float``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.float-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.float-optional.kt
+         :language: kotlin
+
    * - ``Double``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.double-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.double-optional.kt
+         :language: kotlin
+
    * - ``Boolean``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.bool-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.bool-optional.kt
+         :language: kotlin
+
    * - ``Char``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.char-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.char-optional.kt
+         :language: kotlin
+
+**MongoDB BSON Types**
+
+The following table lists the supported MongoDB BSON data types and examples 
+of how to declare them as required or optional properties in your object model.
+To use these types, you must import them from the 
+:github:`org.mongodb.kbson <mongodb/kbson>` package.
 
 .. list-table:: 
    :header-rows: 1
@@ -77,12 +117,24 @@ properties.
    * - MongoDB BSON Type
      - Required
      - Optional
+
    * - :ref:`ObjectId <kotlin-objectid>`
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.objectId-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.objectId-optional.kt
+         :language: kotlin
+
    * - ``Decimal128``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.decimal128-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.decimal128-optional.kt
+         :language: kotlin
+
+**Realm-Specific Types**
+
+The following table lists the supported Realm-specific data types and 
+examples of how oto declare them as required or optional properties in 
+your object model.
 
 .. list-table:: 
    :header-rows: 1
@@ -92,54 +144,59 @@ properties.
    * - Realm-Specific Type
      - Required
      - Optional
+
    * - :ref:`RealmUUID <kotlin-uuid>`
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.uuid-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.uuid-optional.kt
+         :language: kotlin
+
    * - :ref:`RealmInstant <kotlin-timestamps>`
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.realmInstant-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.realmInstant-optional.kt
+         :language: kotlin
+
    * - :ref:`RealmAny <kotlin-realmany>`
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
+     -       N/A
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.realmAny-optional.kt
+         :language: kotlin
+
    * - :ref:`MutableRealmInt <kotlin-mutablerealmint>`
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
-   * - ``RealmObject``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
-   * - ``EmbeddedRealmObject``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
-   * - ``BacklinksDelegate<T>``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
-   * - ``EmbeddedBacklinksDelegate<T>``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
-   * - ``RealmList<T>``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
-   * - ``RealmSet<T>``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
-   * - ``RealmMap<T>``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
-   * - ``RealmDictionary<T>``
-     - ``var name: String = "John"``
-     - ``var name: String? = null``
-
-
-.. note:: Numeric Types
-   
-   Realm stores all non-decimal numeric types as ``Long`` values.
-   Similarly, Realm stores all decimal numeric types as ``Double``
-   values.
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.mutableRealmInt-required.kt
+         :language: kotlin
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.mutableRealmInt-optional.kt
+         :language: kotlin
+
+   * - :ref:`RealmList <kotlin-realm-list>`
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.list-required.kt
+         :language: kotlin
+     -       N/A
+
+   * - :ref:`RealmSet <kotlin-realm-set>`
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.set-required.kt
+         :language: kotlin
+     -       N/A
+
+   * - :ref:`RealmDictionary <kotlin-realm-dictionary>`
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.dictionary-required.kt
+         :language: kotlin
+     -       N/A
+
+   * - :ref:`RealmObject <kotlin-realm-objects-as-properties>`
+     -       N/A
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.realm-object-optional.kt
+         :language: kotlin
+
+   * - :ref:`EmbeddedRealmObject <kotlin-embedded-objects-as-properties>`
+     -       N/A
+     - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.embedded-object-optional.kt
+         :language: kotlin
+
 
 Unique Identifiers
 ------------------
 
-
 .. _kotlin-objectid:
 
 ObjectId
@@ -147,13 +204,15 @@ ObjectId
 
 .. important:: 
 
-   In Realm Kotlin SDK version 1.5.0 and newer, `io.realm.kotlin.types.ObjectId <{+kotlin-local-prefix+}/io.realm.kotlin.types/-object-id/index.html>`__ is deprecated. You must import ``ObjectId`` from :github:`org.mongodb.kbson.ObjectId <mongodb/kbson>` instead.
+   In Realm Kotlin SDK version 1.5.0 and newer, 
+   `io.realm.kotlin.types.ObjectId 
+   <{+kotlin-local-prefix+}/io.realm.kotlin.types/-object-id/index.html>`__ 
+   is deprecated. You must import ``ObjectId`` from 
+   :github:`org.mongodb.kbson.ObjectId <mongodb/kbson>` instead.
 
-``ObjectId`` is a MongoDB-specific 12-byte unique value that you 
-can use as an identifier for objects. 
-
-An ``ObjectId`` is :ref:`indexable <kotlin-indices>` 
-and can be used as a :ref:`primary key <kotlin-primary-keys>`.
+``ObjectId`` is a MongoDB-specific 12-byte globally unique value that you 
+can use as an identifier for objects. An ``ObjectId`` is :ref:`indexable 
+<kotlin-indices>` and can be used as a :ref:`primary key <kotlin-primary-keys>`.
 
 .. _kotlin-uuid:
 
@@ -165,7 +224,9 @@ RealmUUID
 objects. It is :ref:`indexable <kotlin-indices>` and can be used as a 
 :ref:`primary key <kotlin-primary-keys>`. 
 
-Realm creates UUIDs with the `RealmUUID <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-u-u-i-d/index.html>`__ type that:
+Realm creates UUIDs with the `RealmUUID 
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-u-u-i-d/index.html>`__ 
+type that:
 
 - conform to `RFC 4122 version 4 <https://www.rfc-editor.org/info/rfc4122>`_
 - are created with random bytes
@@ -173,7 +234,10 @@ Realm creates UUIDs with the `RealmUUID <{+kotlin-local-prefix+}io.realm.kotlin.
 You can generate a random ``RealmUUID`` using `RealmUUID.random() 
 <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-u-u-i-d/-companion/random.html>`__ 
 or pass a UUID-formatted string to `RealmUUID.from() 
-<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-u-u-i-d/-companion/from.html>`__.
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-u-u-i-d/-companion/from.html>`__:
+
+.. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.create-uuid.kt
+   :language: kotlin
 
 .. include:: /includes/note-using-uuid-instead-of-objectid.rst
 
@@ -185,21 +249,23 @@ MutableRealmInt (Counter)
 The Kotlin SDK offers `MutableRealmInt 
 <{+kotlin-local-prefix+}io.realm.kotlin.types/-mutable-realm-int/index.html>`__ 
 as a special integer type that you can use as a logical counter to accurately 
-synchronize numeric changes across multiple distributed clients using 
-Device Sync. 
+synchronize numeric changes across multiple distributed clients. 
 
 ``MutableRealmInt`` behaves like a ``Long`` but also 
 supports ``increment`` and ``decrement`` methods that implement a 
-:wikipedia:`conflict-free replicated data type <Conflict-free_replicated_data_type>`. This ensures that numeric updates
-can be executed regardless of order to converge to the same value.
+:wikipedia:`conflict-free replicated data type <Conflict-free_replicated_data_type>`. 
+This ensures that numeric updates can be executed regardless of order to 
+converge to the same value.
 
 ``MutableRealmInteger`` fields are backed by traditional numeric types, 
 so no migration is required when changing a field from ``Byte``, ``Short``, 
-``Integer`` or ``Long`` to ``MutableRealmInteger``
+``Int``, or ``Long`` to ``MutableRealmInteger``
 
-A ``MutableRealmInt`` *cannot*: 
-- be used as a :ref:`primary key <kotlin-primary-keys>`
-- store null values, but it can be declared nullable (``MutableRealmInt?``)
+A ``MutableRealmInt`` property: 
+
+- *cannot* be used as a :ref:`primary key <kotlin-primary-keys>`
+- *cannot* store null values, but it can be declared nullable 
+  (``MutableRealmInt?``)
 
 .. _kotlin-timestamps:
 
@@ -224,23 +290,50 @@ example:
 RealmAny (Mixed)
 ----------------
 
-The `RealmAny 
-<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-any/index.html>`__ is a
-mixed data type that represents a polymorphic Realm value. 
-
-You can use the ``RealmAny`` type to create
-Realm object fields that can contain any of several
-underlying types. You can store multiple ``RealmAny`` 
-instances in ``RealmList``, ``RealmDictionary``, or 
-``RealmSet`` fields. To change the value of a 
-``RealmAny`` field, assign a new ``RealmAny`` instance
-with a different underlying value.
-
-``RealmAny``: 
-- are :ref:`indexable <kotlin-indices>`
-- *cannot* be used as a :ref:`primary key <kotlin-primary-keys>`
-- *cannot* store null values, but they *must* be declared nullable (``RealmAny?``)
-- *cannot* store an ``EmbeddedRealmObject`` 
+`RealmAny <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-any/index.html>`__ 
+represents a non-nullable mixed data type. You can use ``RealmAny`` to hold the 
+following data types: 
+
+- Boolean
+- Byte 
+- ByteArray
+- Char
+- Float
+- Double
+- Decimal128
+- Int
+- ObjectID 
+- RealmInstant
+- RealmObject
+- RealmUUID
+- Short
+- String
+
+Additionally, ``RealmAny`` values can be sorted (from lowest to highest): 
+
+#. Boolean
+#. Byte, Short, Int, Long, Float, Double, Decimal128
+#. ByteArray, String
+#. Date
+#. ObjectId
+#. UUID
+#. RealmObject
+
+You can store multiple ``RealmAny`` instances in ``RealmList``, 
+``RealmDictionary``, or ``RealmSet`` fields. 
+
+To change the value of a ``RealmAny`` field, assign a new ``RealmAny`` 
+instance with a different underlying value.
+
+.. Link to Create page once example is added
+
+``RealmAny`` properties: 
+
+- are :ref:`indexable <kotlin-indices>` but *cannot* be used as a 
+  :ref:`primary key <kotlin-primary-keys>`
+- must be declared nullable (``RealmAny?``), but *cannot* store null values
+- can be aggregated. Results are based on the sort order, and the output 
+  type will be a ``RealmAny`` instance containing the corresponding value type.
 
 .. tip:: Handle Polymorphism with Conditional Expressions
 
@@ -253,93 +346,178 @@ with a different underlying value.
 Collection Types
 ----------------
 
-Realm collections can contain zero or more instances of a supported data type.
-Within a Realm collection, all objects are of the same type.
-   
-- 
-- ``RealmSet<T>``
-- ``RealmMap<T>``
-- ``RealmDictionary<T>``
+The Kotlin SDK offers several collection types that you can use as 
+properties in your data model. A collection is an object 
+that contains zero or more instances of one supported data type. 
+Realm collections are homogenous: all objects in a collection are of the 
+same type.
+
+See also :ref:`Create a Collection <kotlin-create-a-collection>`. 
 
 .. _kotlin-realm-list:
 
 RealmLists
 ~~~~~~~~~~
 
+A `RealmList <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-list/index.html>`__
+represents a :ref:`to-many relationship <kotlin-to-many-relationship>` 
+containing any of the supported data types, a `RealmObject 
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__
+or an `EmbeddedRealmObject 
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__.
 
+``RealmList`` implements Kotlin's `List <https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/>`__ 
+interface. Unmanaged lists are backed by an  built-in ``List`` class,
+except managed ``RealmList`` instances persist their contents to a
+realm. See :ref:`Managed vs. Unmanaged Objects <kotlin-managed-vs-unmanaged-objects>`
+for more information.
 
-``RealmList<T>``, where T is any of the supported data types or a   
-`RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__.
-Lists of ``RealmObject`` cannot have null elements. 
+``RealmList<E>`` is a non-null type, where: 
 
-All other types of ``RealmList<T>`` can be nullable (``RealmList<T?>``).
+- Lists of ``RealmObject`` or ``EmbeddedRealmObject`` elements *cannot* 
+  be nullable
+- Lists of any other supported elements can be nullable (``RealmList<E?>``)
 
 .. _kotlin-realm-set:
 
 RealmSets
 ~~~~~~~~~
 
-A `RealmSet() 
-<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html>`__  
-collection represents a 
-:ref:`to-many relationship <kotlin-to-many-relationship>` containing 
-distinct values. 
+A `RealmSet 
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html>`__   
+represents a :ref:`to-many relationship <kotlin-to-many-relationship>` 
+containing distinct values of any of the supported data types, a `RealmObject 
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__
+or an `EmbeddedRealmObject 
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__.
 
 ``RealmSet`` implements Kotlin's 
 `Set <https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/>`__ 
-interface, so it works just like the built-in ``HashSet`` class,
+interface, so it works exactly like the built-in ``HashSet`` class,
 except managed ``RealmSet`` instances persist their contents to a
-realm. 
+realm. See :ref:`Managed vs. Unmanaged Objects <kotlin-managed-vs-unmanaged-objects>`
+for more information.
 
-, where T is any of the supported data types or a
-`RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__.
-Sets of ``RealmObject`` cannot have null elements. 
+``RealmSet<E>`` is a non-null type, where:
 
-All other types of ``RealmSet<T>`` can be nullable (``RealmSet<T?>``).
+- Sets of ``RealmObject`` or ``EmbeddedRealmObject`` elements *cannot* be nullable
+- Sets of any other supported elements can be nullable (``RealmSet<E?>``)
 
 .. _kotlin-realm-dictionary:
 
 RealmMap/RealmDictionaries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A `RealmDictionary 
+A `RealmMap <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-map/index.html>`__  
+is an associative array that contains key-value pairs with unique keys. `RealmDictionary 
 <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-dictionary/index.html>`__ 
-is a specialized 
-`RealmMap <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-map/index.html>`__ 
-where every key is a string. A ``RealmMap`` is an associative array that 
-contains key-value pairs with unique keys. 
-
-, where T is any type of Realm primitive nullable or 
-non-nullable value (``RealmDictionary<T?>``), a
-`RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__,
-or an `EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__.
-Dictionaries of ``RealmObject`` and ``EmbeddedRealmObject`` must be declared nullable.
+is a specialized ``RealmMap`` where every key is a string and values can 
+be any of the supported data types, a `RealmObject
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__
+or an `EmbeddedRealmObject 
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__.
+
+``RealmDictionary`` implements Kotlin's `Map 
+<https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/>`__ 
+interface, so it works exactly like the built-in ``LinkedHashMap`` class,
+except managed ``RealmDictionary`` instances persist their contents to a
+realm. See :ref:`Managed vs. Unmanaged Objects <kotlin-managed-vs-unmanaged-objects>`
+for more information.
+
+``RealmDictionary<K, V>`` is a non-null type, where: 
+
+- Keys must be strings
+- Dictionaries of ``RealmObject`` or ``EmbeddedRealmObject`` values *must* 
+  be nullable (``RealmDictionary<K, V?>``)
+- Dictionaries of any other supported elements can be nullable (``RealmDictionary<K, V?>``)
+
+RealmResults
+~~~~~~~~~~~~
+
+`RealmResults 
+<{+kotlin-local-prefix+}io.realm.kotlin.query/-realm-results/index.html>`__ 
+represents the lazily evaluated results of a ``RealmQuery``. Results are 
+immutable: you cannot add or remove elements on the results collection. 
+Instead, the associated query determines their contents.
+
+``RealmResults<E>`` implements Kotlin's `List 
+<https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/>`__ 
+and behaves in similar ways.
+
+An inverse, to-many relationship property is a ``RealmResults`` list: 
+
+.. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.backlinks-realm-object.kt
+   :language: kotlin
 
+.. _kotlin-realm-objects-as-properties:
 
-.. _kotlin-reference-realm-object:
+RealmObjects as Properties
+--------------------------
 
-RealmObjects
-------------
+You can use `RealmObjects <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__ and any subclasses as properties in your object model.
 
-You can also reference one or more Realm objects from another. 
-Learn more in the
-:ref:`Relationships <kotlin-relationships>` page.
+``RealmObject`` properties:  
 
+- can be used as elements in collections 
+- *cannot* be used as a :ref:`primary key <kotlin-primary-keys>`
 
+You can also reference one or more Realm objects from another through 
+to-one and to-many relationships. 
+For more information, see the :ref:`Relationships <kotlin-relationships>` page.
 
 Backlinks
 ~~~~~~~~~
 
-``BacklinksDelegate<T>``, a `backlinks <{+kotlin-local-prefix+}io.realm.kotlin.ext/backlinks.html>`__
-delegate used to define an inverse relationship between 
-`RealmObjects <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__.
+A backlink represents an :ref:`inverse relationship <kotlin-inverse-relationships>`
+between a ``RealmObject`` and one or more ``RealmObject`` or between a 
+``RealmObject`` and an ``EmbeddedRealmObject``.
+
+You can define a backlink property as a `BacklinksDelegate 
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-backlinks-delegate/index.html>`__ 
+or `EmbeddedBacklinksDelegate 
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-backlinks-delegate/index.html>`__ to the parent object using the ``backlinks()`` method.
+
+Backlinks cannot be null. 
+
+A ``BacklinksDelegate<T>`` property is defined as a ``RealmResults<T>`` list 
+of ``RealmObjects`` :
+
+You can store backlinks for to-many relationships in RealmLists, RealmSets, or 
+RealmDictionaries
+
+.. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.backlinks-realm-object.kt
+   :language: kotlin
+
+An ``EmbeddedBacklinksDelegate<T>`` property is defined as an object that 
+links:
+
+.. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.backlinks-embedded-object.kt
+   :language: kotlin
 
+.. _kotlin-embedded-objects-as-properties:
 
 EmbeddedRealmObject
 ~~~~~~~~~~~~~~~~~~~
 
+An `EmbeddedRealmObject 
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__
+is a special type of `RealmObject 
+<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__. 
+
+``EmbeddedRealmObject`` properties: 
+
+- must be nullable objects within the parent object 
+- *cannot* be nullable elements within a list or set  
+- *cannot* be used as a :ref:`primary key <kotlin-primary-keys>` 
+
+See :ref:`Embedded Objects <kotlin-embedded-objects>` for more information.
 
+.. tip:: Embedded Object Types are Reusable and Composable
 
+   You can use the same embedded object type in multiple parent object types, and
+   you can embed objects inside other embedded objects. You can even
+   recursively reference an embedded object type as an optional property in its
+   own definition.
 
 AsymmetricRealmObject
 ~~~~~~~~~~~~~~~~~~~~~
diff --git a/source/sdk/kotlin/realm-database/write-transactions.txt b/source/sdk/kotlin/realm-database/write-transactions.txt
index 0ebee5cc0a4..695cdac0f93 100644
--- a/source/sdk/kotlin/realm-database/write-transactions.txt
+++ b/source/sdk/kotlin/realm-database/write-transactions.txt
@@ -61,6 +61,8 @@ commits it or cancels it:
   the transaction causes an error, all changes are discarded
   (or "rolled back").
 
+.. _kotlin-managed-vs-unmanaged-objects:
+
 Managed vs. Unmanaged Objects
 -----------------------------