diff --git a/packages/mongodb-access-adapter/datagrip-access-adapter/src/test/kotlin/com/mongodb/jbplugin/accessadapter/datagrip/adapter/DataGripMongoDbDriverTest.kt b/packages/mongodb-access-adapter/datagrip-access-adapter/src/test/kotlin/com/mongodb/jbplugin/accessadapter/datagrip/adapter/DataGripMongoDbDriverTest.kt
index 6397d645..645aea19 100644
--- a/packages/mongodb-access-adapter/datagrip-access-adapter/src/test/kotlin/com/mongodb/jbplugin/accessadapter/datagrip/adapter/DataGripMongoDbDriverTest.kt
+++ b/packages/mongodb-access-adapter/datagrip-access-adapter/src/test/kotlin/com/mongodb/jbplugin/accessadapter/datagrip/adapter/DataGripMongoDbDriverTest.kt
@@ -193,7 +193,7 @@ class DataGripMongoDbDriverTest {
                         Node(
                             Unit,
                             listOf(
-                                HasFieldReference(HasFieldReference.Known(Unit, "myField")),
+                                HasFieldReference(HasFieldReference.FromSchema(Unit, "myField")),
                                 HasValueReference(
                                     HasValueReference.Constant(Unit, "myVal", BsonString)
                                 ),
@@ -255,7 +255,7 @@ class DataGripMongoDbDriverTest {
                         Node(
                             Unit,
                             listOf(
-                                HasFieldReference(HasFieldReference.Known(Unit, "myField")),
+                                HasFieldReference(HasFieldReference.FromSchema(Unit, "myField")),
                                 HasValueReference(
                                     HasValueReference.Constant(Unit, "myVal", BsonString)
                                 ),
diff --git a/packages/mongodb-dialects/java-driver/src/main/kotlin/com/mongodb/jbplugin/dialects/javadriver/glossary/JavaDriverDialectParser.kt b/packages/mongodb-dialects/java-driver/src/main/kotlin/com/mongodb/jbplugin/dialects/javadriver/glossary/JavaDriverDialectParser.kt
index 13ff98c5..3787604e 100644
--- a/packages/mongodb-dialects/java-driver/src/main/kotlin/com/mongodb/jbplugin/dialects/javadriver/glossary/JavaDriverDialectParser.kt
+++ b/packages/mongodb-dialects/java-driver/src/main/kotlin/com/mongodb/jbplugin/dialects/javadriver/glossary/JavaDriverDialectParser.kt
@@ -122,11 +122,8 @@ object JavaDriverDialectParser : DialectParser<PsiElement> {
         if (currentCall.argumentList.expressionCount > 1) {
             // TODO: we might want to have a component that tells this query is in a transaction
             val startIndex = if (hasMongoDbSessionReference(currentCall)) 2 else 1
-            var updateExpression = currentCall.argumentList.expressions.getOrNull(startIndex)
-
-            if (updateExpression == null) {
-                return emptyList()
-            }
+            val updateExpression = currentCall.argumentList.expressions.getOrNull(startIndex)
+                ?: return emptyList()
 
             val argumentAsUpdates = resolveToUpdatesCall(updateExpression)
             // parse only if it's a call to `updates` methods
@@ -200,7 +197,7 @@ object JavaDriverDialectParser : DialectParser<PsiElement> {
             // - in(field, array) -> valid because of varargs
             // - in(field, iterable) -> valid because of overload
             val valueReference = if (filter.argumentList.expressionCount == 2) {
-                var secondArg = filter.argumentList.expressions[1].meaningfulExpression() as PsiExpression
+                val secondArg = filter.argumentList.expressions[1].meaningfulExpression() as PsiExpression
                 if (secondArg.type?.isJavaIterable() == true) { // case 3
                     filter.argumentList.inferFromSingleVarArgElement(start = 1)
                 } else if (secondArg.type?.isArray() == false) { // case 1
@@ -244,7 +241,7 @@ object JavaDriverDialectParser : DialectParser<PsiElement> {
             }
             val valueExpression = filter.argumentList.expressions[0]
             val valueReference = resolveValueFromExpression(valueExpression)
-            val fieldReference = HasFieldReference.Known(valueExpression, "_id")
+            val fieldReference = HasFieldReference.FromSchema(valueExpression, "_id")
 
             return Node(
                 filter,
@@ -400,7 +397,7 @@ object JavaDriverDialectParser : DialectParser<PsiElement> {
         val fieldNameAsString = expression.tryToResolveAsConstantString()
         val fieldReference =
             fieldNameAsString?.let {
-                HasFieldReference.Known(expression, it)
+                HasFieldReference.FromSchema(expression, it)
             } ?: HasFieldReference.Unknown
 
         return fieldReference
diff --git a/packages/mongodb-dialects/java-driver/src/test/kotlin/com/mongodb/jbplugin/dialects/javadriver/glossary/JavaDriverDialectParserTest.kt b/packages/mongodb-dialects/java-driver/src/test/kotlin/com/mongodb/jbplugin/dialects/javadriver/glossary/JavaDriverDialectParserTest.kt
index fff9c7a4..0701b020 100644
--- a/packages/mongodb-dialects/java-driver/src/test/kotlin/com/mongodb/jbplugin/dialects/javadriver/glossary/JavaDriverDialectParserTest.kt
+++ b/packages/mongodb-dialects/java-driver/src/test/kotlin/com/mongodb/jbplugin/dialects/javadriver/glossary/JavaDriverDialectParserTest.kt
@@ -294,7 +294,7 @@ public final class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "_id",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName
         )
         assertEquals(
             BsonAnyOf(BsonObjectId, BsonNull),
@@ -336,7 +336,7 @@ public final class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "_id",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName
         )
         assertEquals(
             BsonAnyOf(BsonObjectId, BsonNull),
@@ -376,7 +376,7 @@ public final class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "_id",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName
         )
         assertEquals(
             BsonAnyOf(BsonObjectId, BsonNull),
@@ -416,7 +416,7 @@ public final class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "_id",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName
         )
         assertEquals(
             BsonAnyOf(BsonObjectId, BsonNull),
@@ -459,7 +459,7 @@ public class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "myField",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonAnyOf(BsonNull, BsonBoolean),
@@ -504,7 +504,7 @@ public class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "myField",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonNull,
@@ -551,7 +551,7 @@ public class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "myField",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonNull,
@@ -599,7 +599,7 @@ public class Repository {
         val firstEq = andChildren.children[0]
         assertEquals(
             "released",
-            (firstEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (firstEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonAnyOf(BsonNull, BsonBoolean),
@@ -613,7 +613,7 @@ public class Repository {
         val secondEq = andChildren.children[1]
         assertEquals(
             "hidden",
-            (secondEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (secondEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonAnyOf(BsonNull, BsonBoolean),
@@ -666,7 +666,7 @@ public class Repository {
         val firstEq = andChildren.children[0]
         assertEquals(
             "released",
-            (firstEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (firstEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonAnyOf(BsonNull, BsonBoolean),
@@ -680,7 +680,7 @@ public class Repository {
         val secondEq = andChildren.children[1]
         assertEquals(
             "hidden",
-            (secondEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (secondEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonAnyOf(BsonNull, BsonBoolean),
@@ -728,7 +728,7 @@ public class Repository {
         val firstEq = andChildren.children[0]
         assertEquals(
             "released",
-            (firstEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (firstEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonAnyOf(BsonNull, BsonBoolean),
@@ -774,7 +774,7 @@ public class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "released",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonAnyOf(BsonNull, BsonBoolean),
@@ -823,7 +823,7 @@ public class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "released",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonAnyOf(BsonNull, BsonBoolean),
@@ -872,7 +872,7 @@ public class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "released",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonBoolean,
@@ -924,7 +924,7 @@ public class Repository {
         val firstEq = andChildren.children[0]
         assertEquals(
             "released",
-            (firstEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (firstEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonAnyOf(BsonNull, BsonBoolean),
@@ -938,7 +938,7 @@ public class Repository {
         val secondEq = andChildren.children[1]
         assertEquals(
             "hidden",
-            (secondEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (secondEq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonAnyOf(BsonNull, BsonBoolean),
@@ -994,7 +994,7 @@ public class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "released",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonBoolean,
@@ -1005,7 +1005,7 @@ public class Repository {
         assertEquals(Name.UNSET, unset.component<Named>()!!.name)
         assertEquals(
             "field",
-            (unset.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (unset.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
     }
 
@@ -1050,7 +1050,7 @@ public class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "released",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonBoolean,
@@ -1061,7 +1061,7 @@ public class Repository {
         assertEquals(Name.UNSET, unset.component<Named>()!!.name)
         assertEquals(
             "field",
-            (unset.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (unset.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
     }
 
@@ -1106,7 +1106,7 @@ public class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "released",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonBoolean,
@@ -1117,7 +1117,7 @@ public class Repository {
         assertEquals(Name.UNSET, unset.component<Named>()!!.name)
         assertEquals(
             "field",
-            (unset.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (unset.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
     }
 
@@ -1162,7 +1162,7 @@ public class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "released",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonBoolean,
@@ -1173,7 +1173,7 @@ public class Repository {
         assertEquals(Name.SET, unset.component<Named>()!!.name)
         assertEquals(
             "field",
-            (unset.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (unset.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             1,
@@ -1220,7 +1220,7 @@ public class Repository {
         assertEquals(Name.EQ, eq.component<Named>()!!.name)
         assertEquals(
             "released",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonBoolean,
@@ -1270,7 +1270,7 @@ public class Repository {
         assertEquals(Name.IN, eq.component<Named>()!!.name)
         assertEquals(
             "genre",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonArray(BsonAnyOf(BsonNull, BsonString)),
@@ -1312,7 +1312,7 @@ public class Repository {
         assertEquals(Name.IN, eq.component<Named>()!!.name)
         assertEquals(
             "genre",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonArray(BsonAnyOf(BsonNull, BsonString)),
@@ -1355,7 +1355,7 @@ public class Repository {
         assertEquals(Name.IN, eq.component<Named>()!!.name)
         assertEquals(
             "genre",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonArray(BsonAnyOf(BsonNull, BsonString)),
@@ -1398,7 +1398,7 @@ public class Repository {
         assertEquals(Name.IN, eq.component<Named>()!!.name)
         assertEquals(
             "genre",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonArray(BsonAnyOf(BsonNull, BsonString)),
@@ -1447,7 +1447,7 @@ public class Repository {
         assertEquals(Name.IN, eq.component<Named>()!!.name)
         assertEquals(
             "genre",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonArray(BsonAnyOf(BsonNull, BsonString)),
@@ -1496,7 +1496,7 @@ public class Repository {
         assertEquals(Name.IN, eq.component<Named>()!!.name)
         assertEquals(
             "genre",
-            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.Known).fieldName,
+            (eq.component<HasFieldReference<Unit?>>()!!.reference as HasFieldReference.FromSchema).fieldName,
         )
         assertEquals(
             BsonArray(BsonAnyOf(BsonNull, BsonString, BsonInt32)),
diff --git a/packages/mongodb-dialects/mongosh/src/main/kotlin/com/mongodb/jbplugin/dialects/mongosh/MongoshDialectFormatter.kt b/packages/mongodb-dialects/mongosh/src/main/kotlin/com/mongodb/jbplugin/dialects/mongosh/MongoshDialectFormatter.kt
index f80e0d31..7b04c04c 100644
--- a/packages/mongodb-dialects/mongosh/src/main/kotlin/com/mongodb/jbplugin/dialects/mongosh/MongoshDialectFormatter.kt
+++ b/packages/mongodb-dialects/mongosh/src/main/kotlin/com/mongodb/jbplugin/dialects/mongosh/MongoshDialectFormatter.kt
@@ -5,6 +5,8 @@ import com.mongodb.jbplugin.dialects.OutputQuery
 import com.mongodb.jbplugin.dialects.mongosh.backend.MongoshBackend
 import com.mongodb.jbplugin.mql.*
 import com.mongodb.jbplugin.mql.components.*
+import com.mongodb.jbplugin.mql.components.HasFieldReference.FromSchema
+import com.mongodb.jbplugin.mql.components.HasFieldReference.Unknown
 import io.github.z4kn4fein.semver.Version
 import org.owasp.encoder.Encode
 
@@ -256,7 +258,7 @@ private fun <S> MongoshBackend.resolveValueReference(
 ) = when (val ref = valueRef.reference) {
     is HasValueReference.Constant -> registerConstant(ref.value)
     is HasValueReference.Runtime -> registerVariable(
-        (fieldRef?.reference as? HasFieldReference.Known)?.fieldName ?: "value",
+        (fieldRef?.reference as? FromSchema)?.fieldName ?: "value",
         ref.type
     )
 
@@ -268,8 +270,8 @@ private fun <S> MongoshBackend.resolveValueReference(
 
 private fun <S> MongoshBackend.resolveFieldReference(fieldRef: HasFieldReference<S>) =
     when (val ref = fieldRef.reference) {
-        is HasFieldReference.Known -> registerConstant(ref.fieldName)
-        is HasFieldReference.Unknown -> registerVariable("field", BsonAny)
+        is FromSchema -> registerConstant(ref.fieldName)
+        is Unknown -> registerVariable("field", BsonAny)
     }
 
 private fun <S> MongoshBackend.emitCollectionReference(collRef: HasCollectionReference<S>?): MongoshBackend {
diff --git a/packages/mongodb-dialects/mongosh/src/test/kotlin/com/mongodb/jbplugin/dialects/mongosh/MongoshDialectFormatterTest.kt b/packages/mongodb-dialects/mongosh/src/test/kotlin/com/mongodb/jbplugin/dialects/mongosh/MongoshDialectFormatterTest.kt
index a7f794ca..a74db6c8 100644
--- a/packages/mongodb-dialects/mongosh/src/test/kotlin/com/mongodb/jbplugin/dialects/mongosh/MongoshDialectFormatterTest.kt
+++ b/packages/mongodb-dialects/mongosh/src/test/kotlin/com/mongodb/jbplugin/dialects/mongosh/MongoshDialectFormatterTest.kt
@@ -32,7 +32,9 @@ class MongoshDialectFormatterTest {
                             Node(
                                 Unit,
                                 listOf(
-                                    HasFieldReference(HasFieldReference.Known(Unit, "myField")),
+                                    HasFieldReference(
+                                        HasFieldReference.FromSchema(Unit, "myField")
+                                    ),
                                     HasValueReference(
                                         HasValueReference.Constant(Unit, "myVal", BsonString)
                                     )
@@ -64,7 +66,9 @@ class MongoshDialectFormatterTest {
                                 Unit,
                                 listOf(
                                     Named(Name.EQ),
-                                    HasFieldReference(HasFieldReference.Known(Unit, "myField")),
+                                    HasFieldReference(
+                                        HasFieldReference.FromSchema(Unit, "myField")
+                                    ),
                                     HasValueReference(
                                         HasValueReference.Constant(Unit, "myVal", BsonString)
                                     )
@@ -96,7 +100,9 @@ class MongoshDialectFormatterTest {
                             Node(
                                 Unit,
                                 listOf(
-                                    HasFieldReference(HasFieldReference.Known(Unit, "myField")),
+                                    HasFieldReference(
+                                        HasFieldReference.FromSchema(Unit, "myField")
+                                    ),
                                     HasValueReference(
                                         HasValueReference.Constant(Unit, "myVal", BsonString)
                                     )
@@ -129,7 +135,9 @@ class MongoshDialectFormatterTest {
                             Node(
                                 Unit,
                                 listOf(
-                                    HasFieldReference(HasFieldReference.Known(Unit, "myField")),
+                                    HasFieldReference(
+                                        HasFieldReference.FromSchema(Unit, "myField")
+                                    ),
                                     HasValueReference(
                                         HasValueReference.Constant(Unit, "myVal", BsonString)
                                     )
@@ -168,7 +176,10 @@ class MongoshDialectFormatterTest {
                                                 listOf(
                                                     Named(Name.EQ),
                                                     HasFieldReference(
-                                                        HasFieldReference.Known(Unit, "myField")
+                                                        HasFieldReference.FromSchema(
+                                                            Unit,
+                                                            "myField"
+                                                        )
                                                     ),
                                                     HasValueReference(
                                                         HasValueReference.Constant(
@@ -210,7 +221,9 @@ class MongoshDialectFormatterTest {
                                 Unit,
                                 listOf(
                                     Named(Name.from(operator)),
-                                    HasFieldReference(HasFieldReference.Known(Unit, "myField")),
+                                    HasFieldReference(
+                                        HasFieldReference.FromSchema(Unit, "myField")
+                                    ),
                                     HasValueReference(
                                         HasValueReference.Constant(Unit, "myVal", BsonString)
                                     )
@@ -243,7 +256,9 @@ class MongoshDialectFormatterTest {
                                 Unit,
                                 listOf(
                                     Named(Name.from(operator)),
-                                    HasFieldReference(HasFieldReference.Known(Unit, "myField")),
+                                    HasFieldReference(
+                                        HasFieldReference.FromSchema(Unit, "myField")
+                                    ),
                                     HasValueReference(
                                         HasValueReference.Constant(
                                             Unit,
@@ -281,7 +296,9 @@ class MongoshDialectFormatterTest {
                             Node(
                                 Unit,
                                 listOf(
-                                    HasFieldReference(HasFieldReference.Known(Unit, "myField")),
+                                    HasFieldReference(
+                                        HasFieldReference.FromSchema(Unit, "myField")
+                                    ),
                                     HasValueReference(
                                         HasValueReference.Constant(Unit, "myVal", BsonString)
                                     )
@@ -290,7 +307,9 @@ class MongoshDialectFormatterTest {
                             Node(
                                 Unit,
                                 listOf(
-                                    HasFieldReference(HasFieldReference.Known(Unit, "myField2")),
+                                    HasFieldReference(
+                                        HasFieldReference.FromSchema(Unit, "myField2")
+                                    ),
                                     HasValueReference(
                                         HasValueReference.Constant(Unit, "myVal2", BsonString)
                                     )
diff --git a/packages/mongodb-dialects/spring-@query/src/main/kotlin/com/mongodb/jbplugin/dialects/springquery/SpringAtQueryDialectParser.kt b/packages/mongodb-dialects/spring-@query/src/main/kotlin/com/mongodb/jbplugin/dialects/springquery/SpringAtQueryDialectParser.kt
index 1a1fd5e2..8b4a89d6 100644
--- a/packages/mongodb-dialects/spring-@query/src/main/kotlin/com/mongodb/jbplugin/dialects/springquery/SpringAtQueryDialectParser.kt
+++ b/packages/mongodb-dialects/spring-@query/src/main/kotlin/com/mongodb/jbplugin/dialects/springquery/SpringAtQueryDialectParser.kt
@@ -147,7 +147,7 @@ object SpringAtQueryDialectParser : DialectParser<PsiElement> {
 
     private fun resolveToFieldNameReference(fieldName: PsiElement): HasFieldReference<PsiElement> {
         return HasFieldReference(
-            HasFieldReference.Known(fieldName, fieldName.text)
+            HasFieldReference.FromSchema(fieldName, fieldName.text)
         )
     }
 
diff --git a/packages/mongodb-dialects/spring-@query/src/test/kotlin/com/mongodb/jbplugin/dialects/springquery/SpringAtQueryDialectParserTest.kt b/packages/mongodb-dialects/spring-@query/src/test/kotlin/com/mongodb/jbplugin/dialects/springquery/SpringAtQueryDialectParserTest.kt
index aa052b34..7de769e3 100644
--- a/packages/mongodb-dialects/spring-@query/src/test/kotlin/com/mongodb/jbplugin/dialects/springquery/SpringAtQueryDialectParserTest.kt
+++ b/packages/mongodb-dialects/spring-@query/src/test/kotlin/com/mongodb/jbplugin/dialects/springquery/SpringAtQueryDialectParserTest.kt
@@ -78,7 +78,7 @@ public interface SQRepository extends Repository<Comment, ObjectId> {
             }
 
             filterN(0, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("name", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> { assertEquals("name", fieldName) }
                 value<HasValueReference.Constant<PsiElement>> { assertEquals("a", value) }
             }
         }
diff --git a/packages/mongodb-dialects/spring-criteria/src/main/kotlin/com/mongodb/jbplugin/dialects/springcriteria/SpringCriteriaDialectParser.kt b/packages/mongodb-dialects/spring-criteria/src/main/kotlin/com/mongodb/jbplugin/dialects/springcriteria/SpringCriteriaDialectParser.kt
index 82362c85..5523a070 100644
--- a/packages/mongodb-dialects/spring-criteria/src/main/kotlin/com/mongodb/jbplugin/dialects/springcriteria/SpringCriteriaDialectParser.kt
+++ b/packages/mongodb-dialects/spring-criteria/src/main/kotlin/com/mongodb/jbplugin/dialects/springcriteria/SpringCriteriaDialectParser.kt
@@ -1,6 +1,5 @@
 package com.mongodb.jbplugin.dialects.springcriteria
 
-import com.intellij.database.dialects.base.introspector.listOf
 import com.intellij.psi.*
 import com.intellij.psi.util.elementType
 import com.intellij.psi.util.findParentOfType
@@ -277,7 +276,7 @@ object SpringCriteriaDialectParser : DialectParser<PsiElement> {
                 valueFilterExpression,
                 listOf(
                     Named(Name.EQ),
-                    HasFieldReference(HasFieldReference.Known(valueFilterExpression, "_id")),
+                    HasFieldReference(HasFieldReference.FromSchema(valueFilterExpression, "_id")),
                     psiExpressionToValueReference(valueFilterExpression as? PsiExpression)
                 )
             )
@@ -496,7 +495,7 @@ object SpringCriteriaDialectParser : DialectParser<PsiElement> {
             null -> HasFieldReference(
                 HasFieldReference.Unknown as HasFieldReference.FieldReference<PsiElement>
             )
-            else -> HasFieldReference(HasFieldReference.Known<PsiElement>(fieldPsi, field))
+            else -> HasFieldReference(HasFieldReference.FromSchema<PsiElement>(fieldPsi, field))
         }
 
         return fieldReference
diff --git a/packages/mongodb-dialects/spring-criteria/src/test/kotlin/com/mongodb/jbplugin/dialects/springcriteria/SpringCriteriaDialectParserTest.kt b/packages/mongodb-dialects/spring-criteria/src/test/kotlin/com/mongodb/jbplugin/dialects/springcriteria/SpringCriteriaDialectParserTest.kt
index 7e7b036b..817cf08c 100644
--- a/packages/mongodb-dialects/spring-criteria/src/test/kotlin/com/mongodb/jbplugin/dialects/springcriteria/SpringCriteriaDialectParserTest.kt
+++ b/packages/mongodb-dialects/spring-criteria/src/test/kotlin/com/mongodb/jbplugin/dialects/springcriteria/SpringCriteriaDialectParserTest.kt
@@ -61,7 +61,9 @@ class Repository {
             }
 
             filterN(0, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("released", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> {
+                    assertEquals("released", fieldName)
+                }
                 value<HasValueReference.Constant<PsiElement>> {
                     assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                     assertEquals(true, value)
@@ -107,7 +109,9 @@ class Repository {
             }
 
             filterN(0, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("released", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> {
+                    assertEquals("released", fieldName)
+                }
                 value<HasValueReference.Constant<PsiElement>> {
                     assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                     assertEquals(true, value)
@@ -153,7 +157,9 @@ class Repository {
             }
 
             filterN(0, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("released", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> {
+                    assertEquals("released", fieldName)
+                }
                 value<HasValueReference.Runtime<PsiElement>> {
                     assertEquals(BsonBoolean, type)
                 }
@@ -199,7 +205,9 @@ class Repository {
             }
 
             filterN(0, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("released", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> {
+                    assertEquals("released", fieldName)
+                }
                 value<HasValueReference.Runtime<PsiElement>> {
                     assertEquals(BsonBoolean, type)
                 }
@@ -244,7 +252,7 @@ class Repository {
             }
 
             filterN(0, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("_id", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> { assertEquals("_id", fieldName) }
                 value<HasValueReference.Constant<PsiElement>> {
                     assertEquals(BsonAnyOf(BsonNull, BsonString), type)
                     assertEquals("123456", value)
@@ -292,7 +300,9 @@ class Repository {
             }
 
             filterN(0, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("released", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> {
+                    assertEquals("released", fieldName)
+                }
                 value<HasValueReference.Constant<PsiElement>> {
                     assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                     assertEquals(true, value)
@@ -300,7 +310,9 @@ class Repository {
             }
 
             filterN(1, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("hidden", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> {
+                    assertEquals("hidden", fieldName)
+                }
                 value<HasValueReference.Constant<PsiElement>> {
                     assertEquals(BsonAnyOf(BsonNull, BsonInt32), type)
                     assertEquals(0, value)
@@ -352,7 +364,9 @@ class Repository {
             }
 
             filterN(0, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("released", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> {
+                    assertEquals("released", fieldName)
+                }
                 value<HasValueReference.Constant<PsiElement>> {
                     assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                     assertEquals(true, value)
@@ -361,7 +375,9 @@ class Repository {
 
             filterN(1, Name.AND) {
                 filterN(0, Name.EQ) {
-                    field<HasFieldReference.Known<PsiElement>> { assertEquals("hidden", fieldName) }
+                    field<HasFieldReference.FromSchema<PsiElement>> {
+                        assertEquals("hidden", fieldName)
+                    }
                     value<HasValueReference.Constant<PsiElement>> {
                         assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                         assertEquals(false, value)
@@ -369,7 +385,9 @@ class Repository {
                 }
 
                 filterN(1, Name.EQ) {
-                    field<HasFieldReference.Known<PsiElement>> { assertEquals("valid", fieldName) }
+                    field<HasFieldReference.FromSchema<PsiElement>> {
+                        assertEquals("valid", fieldName)
+                    }
                     value<HasValueReference.Constant<PsiElement>> {
                         assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                         assertEquals(true, value)
@@ -421,7 +439,9 @@ class Repository {
             }
 
             filterN(0, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("released", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> {
+                    assertEquals("released", fieldName)
+                }
                 value<HasValueReference.Constant<PsiElement>> {
                     assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                     assertEquals(true, value)
@@ -430,7 +450,9 @@ class Repository {
 
             filterN(1, Name.OR) {
                 filterN(0, Name.EQ) {
-                    field<HasFieldReference.Known<PsiElement>> { assertEquals("hidden", fieldName) }
+                    field<HasFieldReference.FromSchema<PsiElement>> {
+                        assertEquals("hidden", fieldName)
+                    }
                     value<HasValueReference.Constant<PsiElement>> {
                         assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                         assertEquals(false, value)
@@ -438,7 +460,9 @@ class Repository {
                 }
 
                 filterN(1, Name.EQ) {
-                    field<HasFieldReference.Known<PsiElement>> { assertEquals("valid", fieldName) }
+                    field<HasFieldReference.FromSchema<PsiElement>> {
+                        assertEquals("valid", fieldName)
+                    }
                     value<HasValueReference.Constant<PsiElement>> {
                         assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                         assertEquals(true, value)
@@ -491,7 +515,9 @@ class Repository {
             }
 
             filterN(0, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("released", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> {
+                    assertEquals("released", fieldName)
+                }
                 value<HasValueReference.Constant<PsiElement>> {
                     assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                     assertEquals(true, value)
@@ -500,7 +526,9 @@ class Repository {
 
             filterN(1, Name.NOR) {
                 filterN(0, Name.EQ) {
-                    field<HasFieldReference.Known<PsiElement>> { assertEquals("hidden", fieldName) }
+                    field<HasFieldReference.FromSchema<PsiElement>> {
+                        assertEquals("hidden", fieldName)
+                    }
                     value<HasValueReference.Constant<PsiElement>> {
                         assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                         assertEquals(false, value)
@@ -508,7 +536,9 @@ class Repository {
                 }
 
                 filterN(1, Name.EQ) {
-                    field<HasFieldReference.Known<PsiElement>> { assertEquals("valid", fieldName) }
+                    field<HasFieldReference.FromSchema<PsiElement>> {
+                        assertEquals("valid", fieldName)
+                    }
                     value<HasValueReference.Constant<PsiElement>> {
                         assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                         assertEquals(true, value)
@@ -604,7 +634,9 @@ class Repository {
         // ---- with the DSL ----
         SpringCriteriaDialectParser.parse(query).assert(IsCommand.CommandType.COUNT_DOCUMENTS) {
             filterN(0, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("released", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> {
+                    assertEquals("released", fieldName)
+                }
                 value<HasValueReference.Constant<PsiElement>> {
                     assertEquals(BsonAnyOf(BsonNull, BsonBoolean), type)
                     assertEquals(true, value)
@@ -730,17 +762,19 @@ class Repository {
             }
 
             filterN(0, Name.EQ) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("field", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> { assertEquals("field", fieldName) }
                 value<HasValueReference.Constant<PsiElement>> { assertEquals("123456", value) }
             }
 
             updateN(0, Name.SET) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("another", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> {
+                    assertEquals("another", fieldName)
+                }
                 value<HasValueReference.Constant<PsiElement>> { assertEquals(1, value) }
             }
 
             updateN(1, Name.SET) {
-                field<HasFieldReference.Known<PsiElement>> { assertEquals("third", fieldName) }
+                field<HasFieldReference.FromSchema<PsiElement>> { assertEquals("third", fieldName) }
                 value<HasValueReference.Constant<PsiElement>> { assertEquals(3f, value) }
             }
         }
@@ -787,7 +821,9 @@ class Repository {
 
             filterN(0, Name.NOT) {
                 filterN(0, Name.EQ) {
-                    field<HasFieldReference.Known<PsiElement>> { assertEquals("field", fieldName) }
+                    field<HasFieldReference.FromSchema<PsiElement>> {
+                        assertEquals("field", fieldName)
+                    }
                     value<HasValueReference.Constant<PsiElement>> { assertEquals("123456", value) }
                 }
             }
@@ -834,7 +870,7 @@ class Repository {
             }
 
             filterN(0, Name.IN) {
-                field<HasFieldReference.Known<PsiElement>> {
+                field<HasFieldReference.FromSchema<PsiElement>> {
                     assertEquals("field", fieldName)
                 }
                 value<HasValueReference.Constant<PsiElement>> {
@@ -885,7 +921,7 @@ class Repository {
             }
 
             filterN(0, Name.IN) {
-                field<HasFieldReference.Known<PsiElement>> {
+                field<HasFieldReference.FromSchema<PsiElement>> {
                     assertEquals("field", fieldName)
                 }
                 value<HasValueReference.Runtime<PsiElement>> {
@@ -935,7 +971,7 @@ class Repository {
             }
 
             filterN(0, Name.NIN) {
-                field<HasFieldReference.Known<PsiElement>> {
+                field<HasFieldReference.FromSchema<PsiElement>> {
                     assertEquals("field", fieldName)
                 }
                 value<HasValueReference.Runtime<PsiElement>> {
diff --git a/packages/mongodb-linting-engine/src/main/kotlin/com/mongodb/jbplugin/linting/FieldCheckingLinter.kt b/packages/mongodb-linting-engine/src/main/kotlin/com/mongodb/jbplugin/linting/FieldCheckingLinter.kt
index d17e76db..c79b9f46 100644
--- a/packages/mongodb-linting-engine/src/main/kotlin/com/mongodb/jbplugin/linting/FieldCheckingLinter.kt
+++ b/packages/mongodb-linting-engine/src/main/kotlin/com/mongodb/jbplugin/linting/FieldCheckingLinter.kt
@@ -18,7 +18,7 @@ import com.mongodb.jbplugin.mql.parser.components.ParsedValueReference
 import com.mongodb.jbplugin.mql.parser.components.allFiltersRecursively
 import com.mongodb.jbplugin.mql.parser.components.extractValueReference
 import com.mongodb.jbplugin.mql.parser.components.knownCollection
-import com.mongodb.jbplugin.mql.parser.components.knownFieldReference
+import com.mongodb.jbplugin.mql.parser.components.schemaFieldReference
 import com.mongodb.jbplugin.mql.parser.filter
 import com.mongodb.jbplugin.mql.parser.first
 import com.mongodb.jbplugin.mql.parser.map
@@ -102,10 +102,10 @@ object FieldCheckingLinter {
                 is Either.Left -> emptyList()
                 is Either.Right -> {
                     val collectionSchema = querySchema.value
-                    val extractFieldExistenceWarning = knownFieldReference<S>()
+                    val extractFieldExistenceWarning = schemaFieldReference<S>()
                         .map { toFieldNotExistingWarning(collectionSchema, it) }
 
-                    val extractTypeMismatchWarning = knownFieldReference<S>()
+                    val extractTypeMismatchWarning = schemaFieldReference<S>()
                         .filter { collectionSchema.typeOf(it.fieldName) != BsonNull }
                         .zip(extractValueReference())
                         .map { toValueMismatchWarning(collectionSchema, it) }
@@ -127,7 +127,7 @@ object FieldCheckingLinter {
 
     private fun <S> toFieldNotExistingWarning(
         collectionSchema: CollectionSchema,
-        known: HasFieldReference.Known<S>
+        known: HasFieldReference.FromSchema<S>
     ): FieldCheckWarning<S>? {
         val fieldType = collectionSchema.typeOf(known.fieldName)
         return FieldCheckWarning.FieldDoesNotExist(
@@ -139,7 +139,7 @@ object FieldCheckingLinter {
 
     private fun <S> toValueMismatchWarning(
         collectionSchema: CollectionSchema,
-        pair: Pair<HasFieldReference.Known<S>, ParsedValueReference<S, out Any>>
+        pair: Pair<HasFieldReference.FromSchema<S>, ParsedValueReference<S, out Any>>
     ): FieldCheckWarning<S>? {
         val fieldType = collectionSchema.typeOf(pair.first.fieldName)
         val fieldName = pair.first.fieldName
diff --git a/packages/mongodb-linting-engine/src/test/kotlin/com/mongodb/jbplugin/linting/FieldCheckingLinterTest.kt b/packages/mongodb-linting-engine/src/test/kotlin/com/mongodb/jbplugin/linting/FieldCheckingLinterTest.kt
index 2e2065fc..bd1dea8b 100644
--- a/packages/mongodb-linting-engine/src/test/kotlin/com/mongodb/jbplugin/linting/FieldCheckingLinterTest.kt
+++ b/packages/mongodb-linting-engine/src/test/kotlin/com/mongodb/jbplugin/linting/FieldCheckingLinterTest.kt
@@ -49,14 +49,16 @@ class FieldCheckingLinterTest {
                                 Node(
                                     null,
                                     listOf(
-                                        HasFieldReference(HasFieldReference.Known(null, "myString"))
+                                        HasFieldReference(
+                                            HasFieldReference.FromSchema(null, "myString")
+                                        )
                                     )
                                 ),
                                 Node(
                                     null,
                                     listOf(
                                         HasFieldReference(
-                                            HasFieldReference.Known(null, "myBoolean")
+                                            HasFieldReference.FromSchema(null, "myBoolean")
                                         )
                                     )
                                 ),
@@ -106,14 +108,16 @@ class FieldCheckingLinterTest {
                                 Node(
                                     null,
                                     listOf(
-                                        HasFieldReference(HasFieldReference.Known(null, "myString"))
+                                        HasFieldReference(
+                                            HasFieldReference.FromSchema(null, "myString")
+                                        )
                                     )
                                 ),
                                 Node(
                                     null,
                                     listOf(
                                         HasFieldReference(
-                                            HasFieldReference.Known(null, "myBoolean")
+                                            HasFieldReference.FromSchema(null, "myBoolean")
                                         ),
                                         HasValueReference(
                                             HasValueReference.Constant(null, true, BsonBoolean)
@@ -167,7 +171,7 @@ class FieldCheckingLinterTest {
                                     null,
                                     listOf(
                                         HasFieldReference(
-                                            HasFieldReference.Known(null, "myInt")
+                                            HasFieldReference.FromSchema(null, "myInt")
                                         ),
                                         HasValueReference(
                                             HasValueReference.Constant(null, null, BsonNull)
diff --git a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/IndexAnalyzer.kt b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/IndexAnalyzer.kt
index a8118d7d..0a8cd88c 100644
--- a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/IndexAnalyzer.kt
+++ b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/IndexAnalyzer.kt
@@ -43,7 +43,7 @@ object IndexAnalyzer {
         val otherRefs = hasFilter?.children?.flatMap { it.allFieldReferences() } ?: emptyList()
         val fieldRef = component<HasFieldReference<S>>()?.reference ?: return otherRefs
         val valueRef = component<HasValueReference<S>>()?.reference
-        return if (fieldRef is HasFieldReference.Known) {
+        return if (fieldRef is HasFieldReference.FromSchema) {
             otherRefs + (
                 valueRef?.let { reference ->
                     when (reference) {
diff --git a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/Node.kt b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/Node.kt
index a526bb3a..253c9d36 100644
--- a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/Node.kt
+++ b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/Node.kt
@@ -24,6 +24,18 @@ import com.mongodb.jbplugin.mql.components.HasTargetCluster
  */
 interface Component
 
+/**
+ * HasChildren component encapsulates the idea that a Component has children. For example:
+ * ```java
+ * Filters.and(Filters.eq("year", 1994), Filters.eq("name", "something"))
+ * ```
+ * The above query has a filter that have nested filters within it hence the Node that represents
+ * `Filters.and` implements `HasChildren` interface.
+ */
+interface HasChildren<S> : Component {
+    val children: List<Node<S>>
+}
+
 /**
  * Represents the building block of a query in this model. Nodes don't have any semantic per se, but they can
  * hold Components that will give them specific meaning.
diff --git a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasFieldReference.kt b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasFieldReference.kt
index dec51700..18dffeea 100644
--- a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasFieldReference.kt
+++ b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasFieldReference.kt
@@ -2,27 +2,25 @@ package com.mongodb.jbplugin.mql.components
 
 import com.mongodb.jbplugin.mql.Component
 
-/**
- * @param S
- * @property reference
- */
 data class HasFieldReference<S>(
     val reference: FieldReference<S>,
 ) : Component {
-    data object Unknown : FieldReference<Any>
+
+    sealed interface FieldReference<S>
 
     /**
-     * @param S
+     * Encodes a possible FieldReference that cannot be classified as one of the remaining
+     * FieldReference implementations because of us not having enough metadata about it.
      */
-    sealed interface FieldReference<S>
+    data object Unknown : FieldReference<Any>
 
     /**
-     * @param S
-     * @property fieldName
-     * @property source
+     * Encodes a FieldReference that is statically typed in the user code and one that is
+     * expected to reference a field from the target namespace of the query / aggregation.
      */
-    data class Known<S>(
+    data class FromSchema<S>(
         val source: S,
         val fieldName: String,
+        val displayName: String = fieldName,
     ) : FieldReference<S>
 }
diff --git a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasFilter.kt b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasFilter.kt
index 3317861a..b08f4105 100644
--- a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasFilter.kt
+++ b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasFilter.kt
@@ -1,6 +1,6 @@
 package com.mongodb.jbplugin.mql.components
 
-import com.mongodb.jbplugin.mql.Component
+import com.mongodb.jbplugin.mql.HasChildren
 import com.mongodb.jbplugin.mql.Node
 
 /**
@@ -8,5 +8,5 @@ import com.mongodb.jbplugin.mql.Node
  * @property children
  */
 data class HasFilter<S>(
-    val children: List<Node<S>>,
-) : Component
+    override val children: List<Node<S>>,
+) : HasChildren<S>
diff --git a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasUpdates.kt b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasUpdates.kt
index ec39c808..03ad255b 100644
--- a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasUpdates.kt
+++ b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasUpdates.kt
@@ -1,6 +1,6 @@
 package com.mongodb.jbplugin.mql.components
 
-import com.mongodb.jbplugin.mql.Component
+import com.mongodb.jbplugin.mql.HasChildren
 import com.mongodb.jbplugin.mql.Node
 
 /**
@@ -8,5 +8,5 @@ import com.mongodb.jbplugin.mql.Node
  * @property children
  */
 data class HasUpdates<S>(
-    val children: List<Node<S>>,
-) : Component
+    override val children: List<Node<S>>,
+) : HasChildren<S>
diff --git a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasValueReference.kt b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasValueReference.kt
index dbeeea1e..70e49f2f 100644
--- a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasValueReference.kt
+++ b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/components/HasValueReference.kt
@@ -3,25 +3,25 @@ package com.mongodb.jbplugin.mql.components
 import com.mongodb.jbplugin.mql.BsonType
 import com.mongodb.jbplugin.mql.Component
 
-/**
- * @param S
- * @property reference
- */
 data class HasValueReference<S>(
     val reference: ValueReference<S>,
 ) : Component {
-    data object Unknown : ValueReference<Any>
+
+    sealed interface ValueReference<S>
 
     /**
-     * @param S
+     * Encodes a possible ValueReference that cannot be classified as one of the remaining
+     * ValueReference implementations because of us not having enough metadata about it.
      */
-    sealed interface ValueReference<S>
+    data object Unknown : ValueReference<Any>
 
     /**
-     * @param S
-     * @property value
-     * @property type
-     * @property source
+     * Encodes a ValueReference when the value is mentioned statically in the user code.
+     * For Example:
+     * ```
+     * Filters.eq("year", 1994)
+     * ```
+     * ValueReference here is of type Constant
      */
     data class Constant<S>(
         val source: S,
@@ -30,9 +30,12 @@ data class HasValueReference<S>(
     ) : ValueReference<S>
 
     /**
-     * @param S
-     * @property type
-     * @property source
+     * Encodes a ValueReference when the value is mentioned as a variable in the user code and the
+     * specific value can only be known at the runtime. For example:
+     * ```
+     * Filters.eq("year", yearFromFunctionArgs)
+     * ```
+     * Because the exact value of yearFromFunctionArgs is not known, the reference is Runtime
      */
     data class Runtime<S>(
         val source: S,
diff --git a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/parser/components/HasFieldReference.kt b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/parser/components/HasFieldReference.kt
index ed22246c..46b5d34a 100644
--- a/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/parser/components/HasFieldReference.kt
+++ b/packages/mongodb-mql-model/src/main/kotlin/com/mongodb/jbplugin/mql/parser/components/HasFieldReference.kt
@@ -17,4 +17,4 @@ inline fun <reified T : HasFieldReference.FieldReference<S>, S> fieldReference()
     }
 }
 
-fun <S> knownFieldReference() = fieldReference<HasFieldReference.Known<S>, S>()
+fun <S> schemaFieldReference() = fieldReference<HasFieldReference.FromSchema<S>, S>()
diff --git a/packages/mongodb-mql-model/src/test/kotlin/com/mongodb/jbplugin/mql/IndexAnalyzerTest.kt b/packages/mongodb-mql-model/src/test/kotlin/com/mongodb/jbplugin/mql/IndexAnalyzerTest.kt
index c780b34d..d6193649 100644
--- a/packages/mongodb-mql-model/src/test/kotlin/com/mongodb/jbplugin/mql/IndexAnalyzerTest.kt
+++ b/packages/mongodb-mql-model/src/test/kotlin/com/mongodb/jbplugin/mql/IndexAnalyzerTest.kt
@@ -29,7 +29,7 @@ class IndexAnalyzerTest {
                         Node(
                             Unit,
                             listOf(
-                                HasFieldReference(HasFieldReference.Known(Unit, "myField"))
+                                HasFieldReference(HasFieldReference.FromSchema(Unit, "myField"))
                             )
                         )
                     )
@@ -60,19 +60,21 @@ class IndexAnalyzerTest {
                         Node(
                             Unit,
                             listOf(
-                                HasFieldReference(HasFieldReference.Known(Unit, "myField"))
+                                HasFieldReference(HasFieldReference.FromSchema(Unit, "myField"))
                             )
                         ),
                         Node(
                             Unit,
                             listOf(
-                                HasFieldReference(HasFieldReference.Known(Unit, "mySecondField"))
+                                HasFieldReference(
+                                    HasFieldReference.FromSchema(Unit, "mySecondField")
+                                )
                             )
                         ),
                         Node(
                             Unit,
                             listOf(
-                                HasFieldReference(HasFieldReference.Known(Unit, "myField"))
+                                HasFieldReference(HasFieldReference.FromSchema(Unit, "myField"))
                             )
                         )
                     )
diff --git a/packages/mongodb-mql-model/src/test/kotlin/com/mongodb/jbplugin/mql/NodeTest.kt b/packages/mongodb-mql-model/src/test/kotlin/com/mongodb/jbplugin/mql/NodeTest.kt
index 4525df48..ce702890 100644
--- a/packages/mongodb-mql-model/src/test/kotlin/com/mongodb/jbplugin/mql/NodeTest.kt
+++ b/packages/mongodb-mql-model/src/test/kotlin/com/mongodb/jbplugin/mql/NodeTest.kt
@@ -30,9 +30,9 @@ class NodeTest {
             Node<Unit?>(
                 null,
                 listOf(
-                    HasFieldReference(HasFieldReference.Known(null, "field1")),
+                    HasFieldReference(HasFieldReference.FromSchema(null, "field1")),
                     HasFieldReference(
-                        HasFieldReference.Known(
+                        HasFieldReference.FromSchema(
                             null,
                             "field2",
                         ),
@@ -41,8 +41,14 @@ class NodeTest {
             )
         val fieldReferences = node.components<HasFieldReference<Unit?>>()
 
-        assertEquals("field1", (fieldReferences[0].reference as HasFieldReference.Known).fieldName)
-        assertEquals("field2", (fieldReferences[1].reference as HasFieldReference.Known).fieldName)
+        assertEquals(
+            "field1",
+            (fieldReferences[0].reference as HasFieldReference.FromSchema).fieldName
+        )
+        assertEquals(
+            "field2",
+            (fieldReferences[1].reference as HasFieldReference.FromSchema).fieldName
+        )
     }
 
     @Test
@@ -50,7 +56,7 @@ class NodeTest {
         val node =
             Node<Unit?>(
                 null,
-                listOf(HasFieldReference(HasFieldReference.Known(null, "field1"))),
+                listOf(HasFieldReference(HasFieldReference.FromSchema(null, "field1"))),
             )
         val hasFieldReferences = node.hasComponent<HasFieldReference<Unit?>>()
 
@@ -62,7 +68,7 @@ class NodeTest {
         val node =
             Node<Unit?>(
                 null,
-                listOf(HasFieldReference(HasFieldReference.Known(null, "field1"))),
+                listOf(HasFieldReference(HasFieldReference.FromSchema(null, "field1"))),
             )
         val hasNamedComponent = node.hasComponent<Named>()
 
@@ -190,7 +196,7 @@ class NodeTest {
                     HasFieldReference::class.java
                 ),
                 arrayOf(
-                    HasFieldReference(HasFieldReference.Known(null, "abc")),
+                    HasFieldReference(HasFieldReference.FromSchema(null, "abc")),
                     HasFieldReference::class.java
                 ),
                 arrayOf(