draft: augment yaml definitions with test schema #1659

nirinchev · 2025-04-07T09:24:02Z

This is very much a POC, but I figured I'd open up a PR to get early feedback on the direction we're heading in.

For context, the devtools team wants to use the yaml definitions from the PHP driver to build an autocomplete experience for the aggregation pipelines in mongosh/compass. We've built a tool to convert the yaml to typescript definitions and it seems to be working well for the base case, but to polish it, we'd need to enhance the yaml definitions to allow us to generate more precise type definitions.

Here's a list of the high-level changes we're proposing (will be updated over time):

Update schema.json to remove duplicate $comment fields (since most json parsers are not happy about it).
Update all yaml definitions to add schema information for the test cases.
- The schema shape matches SimplifiedSchema from the mongodb-schema package. This is a little bit verbose since it supports multiple types per field, even though the docs rarely have heterogeneous schemas.
- Schema is generated automatically by crawling the docs website at the link pointed to by the test and then using the mongodb-schema package to infer a probabilistic schema from the example collection.
Removed a few tests that no longer seem to point to anything in the docs - e.g. firstN:Null and Missing Values.

GromNaN

Very good idea to have the schema of the source collection.

GromNaN · 2025-04-07T09:31:36Z

generator/config/accumulator/accumulator.yaml

@@ -1,6 +1,6 @@
 # $schema: ../schema.json
 name: $accumulator
-link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator/'


Is it possible to keep quotes around strings? This style changes make the diff hard to read. Also, I use quotes by default around every string to prevent unexpected parsing rule from Yaml.

Hey, looks like the quotes usage is inconsistent in these files - I'd be inclined to define a prettier rule and reformat them in a separate PR to make this one less noisy if that'd make sense to you. The reason for these getting removed is that the way we're adding the schema information is parsing the yaml, fetching the schema from the docs, then writing it, which results in the file getting reformatted based on the tool conventions (we use https://www.npmjs.com/package/js-yaml here).

Yeah, at least prettier supports YAML out of the box, so that feels like a great way to remove any formatting preference ambiguity

GromNaN · 2025-04-07T09:35:10Z

generator/config/accumulator/percentile.yaml

@@ -25,7 +25,7 @@ arguments:
    -
        name: p
        type:
-            - resolvesToArray # of resolvesToNumber


I was keeping this comments as a note for later, as we would like to extend type definition for generic lists and hashes.

Yeah, that makes sense - same as above, those got removed due to the yaml parser not preserving comments, but will try and find a way to avoid that.

GromNaN · 2025-04-07T09:37:13Z

generator/config/accumulator/stdDevSamp.yaml

        pipeline:
            -
                $sample:
                    size: 100
            -
                $group:
-                    _id: ~
+                    _id: null


Noted that both ~ and null can be used according to the spec.

GromNaN · 2025-04-07T09:38:36Z

generator/config/expression/convert.yaml

+                            onNull:
+                                bytes: !!binary AAAAAAAAAAAAAAAAAABAMA==


This new notation seems less legible to me.

Agreed, will look at tweaking the generator to ensure it preserves the old notation.

GromNaN · 2025-04-07T09:45:36Z

generator/config/accumulator/firstN.yaml

@@ -24,99 +24,122 @@ arguments:
            A positive integral expression that is either a constant or depends on the _id value for $group.
 tests:
    -
-        name: 'Null and Missing Values'
-        link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/firstN/#null-and-missing-values'


Removed a few tests that no longer seem to point to anything in the docs - e.g. "firstN:Null and Missing Values".

This example is in the "Behavior" part of the docs.

https://www.mongodb.com/docs/manual/reference/operator/aggregation/firstN/#null-and-missing-values

GromNaN · 2025-04-07T09:48:20Z

generator/config/schema.json

                    "type": "string",
                    "enum": [
                        "array",
                        "object",
-                        "single",
-                        "search"


Good catch, this value is not used.

GromNaN · 2025-04-07T09:52:11Z

generator/config/schema.json

+                    "enum": [
+                        "Array",
+                        "Binary",
+                        "Boolean",
+                        "Code",
+                        "CodeWScope",
+                        "Date",
+                        "Decimal128",
+                        "Double",
+                        "Int32",
+                        "Int64",
+                        "MaxKey",
+                        "MinKey",
+                        "Null",
+                        "ObjectId",
+                        "BSONRegExp",
+                        "String",
+                        "BSONSymbol",
+                        "Timestamp",
+                        "Undefined",
+                        "Document",
+                        "Number"
+                    ],


We'll have to converge on the same type names for operator return types and argument types. I'm fine with changing the names in expressions.php to be consistent with other tools.

GromNaN · 2025-04-07T09:54:15Z

generator/config/schema.json

+                        "Binary",
+                        "Boolean",
+                        "Code",
+                        "CodeWScope",


Is the CodeWScope type specific to mongosh?

This is the deprecated code_w_s bson type. Realistically, I don't expect any of the more advanced types to be found in the docs, but I generated the schema from the type definitions and opted not to manually edit it to make it easier to maintain if it ever changes. If we wanted to clean it up, we can definitely remove the deprecated types.

@GromNaN: For additional context, PHPC conditionally encodes Code or CodeWScope based on whether the MongoDB\BSON\Javascript object was constructed with a non-null $scope parameter (see: php_phongo_javascript_init).

GromNaN · 2025-04-07T16:24:58Z

generator/config/stage/project.yaml

@@ -11,7 +11,7 @@ arguments:
        name: specification
        type:
            - expression
-        variadic: object
+        variadic: object # XXX: This should somehow allow explicit typings for { fieldName: 1|0 }


The type is "expression", because any expression is accepted to compute a value.

True. For IDE integrations/user support it's still valuable to be able to say "while this can be an arbitrary document, frequently it will have keys that match document keys and values which are either 0 or 1"

So we need an additional type for the projection. Maybe an enum:

0: Suppress 1: Include

And this parameter accepts an union of ProjectEnum|expression

This reverts commit 56a801b.

nirinchev · 2025-06-04T07:27:49Z

generator/config/accumulator/lastN.yaml

-          - resolvesToArray
+          - expression


This was conflicting with the docs, which say that it can be any expression. It was particularly problematic in the $group example since the actual input field doesn't need to be an array, it only becomes one in the context of a $group, which is hard to statically enforce. I've relaxed the requirement in the interest of reducing the false negatives, at the cost of potentially accepting more false positives.

nirinchev · 2025-06-04T07:32:45Z

generator/config/expression/avg.yaml

-                    $avg:
-                        - $quizzes
+                    $avg: $quizzes
                labAvg:
-                    $avg:
-                        - $labs
+                    $avg: $labs


These seem to have been errors, right? At least in the docs, those are field expressions rather than arrays.

nirinchev · 2025-06-04T07:34:02Z

generator/config/query/eq.yaml

@@ -9,7 +9,7 @@ description: |
 arguments:
    - name: value
      type:
-          - any
+          - expression


Not sure why this was any previously, but happy to revert if expression is incorrect here.

addaleax and others added 2 commits February 18, 2025 13:08

WIP

39224b6

add tests schema

56a801b

GromNaN reviewed Apr 7, 2025

View reviewed changes

nirinchev added 13 commits May 20, 2025 13:44

Revert "add tests schema"

7e64509

This reverts commit 56a801b.

run yamlfix

07cd9fc

Reformat after running the js generator

7cb2274

generate schema for accumulators

cb2571c

add test schemas for expressions

e28803d

add test schemas for query

fd06dd6

add search schemas

64a44ad

schema for stages

6a34eda

Update with some refs

cc2c832

type tweaks

c027132

fix names to align with docs

3602303

regenerate test schemas

7978e4f

add searchHighlight as a type

b9b1d19

nirinchev commented Jun 4, 2025

View reviewed changes

Add schema for first/last

c2b1ee5

draft: augment yaml definitions with test schema #1659

Are you sure you want to change the base?

draft: augment yaml definitions with test schema #1659

Uh oh!

Conversation

nirinchev commented Apr 7, 2025

Uh oh!

GromNaN left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GromNaN Apr 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GromNaN May 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

GromNaN Apr 7, 2025 •

edited

Loading

GromNaN May 20, 2025 •

edited

Loading