feat(quotations): describe how a union is written

[xperiandri]

Proposed Changes

Depends on #62, which depends on #61, #60, #59 and #58. The branch is built on the branch of #62, so until those are merged this pull request also shows their fourteen commits; its own are the last two. It targets main because the build workflow runs only for pull requests into main.

The sixth step of phase 1 of ADR 0001 (#34). A query that tests the case of a union and reads a field of it has to know what a value of that case looks like in the document:

<@ fun (o : Order) ->
    match o.Payment with
    | Card (number, _) -> number = wanted
    | Cash -> false @>

FSharp.SystemTextJson writes Card ("1234", 2030) and Cash in a way that its options choose:

Encoding of unions	Card ("1234", 2030)	Cash
the tag next to the fields (the default)	{"Case":"Card","Fields":["1234",2030]}	{"Case":"Cash"}
the same with named fields	{"Case":"Card","Fields":{"number":"1234","year":2030}}	{"Case":"Cash"}
the tag as the name of the fields	{"Card":["1234",2030]}	{"Cash":[]}
the tag before the fields	["Card","1234",2030]	["Cash"]
the tag among named fields	{"Case":"Card","number":"1234","year":2030}	{"Case":"Cash"}
no tag	{"number":"1234","year":2030}	{}
any of these, with a case without fields as its tag alone	as above	"Cash"

IJsonLayout answers one more question, about one case of a union:

type IJsonLayout =
    // from #61 and #62: MemberName, OptionalEncoding, EnumEncoding, TupleEncoding, CollectionEncoding, MapEncoding
    abstract UnionCaseEncoding : memberOfDocument : DocumentMember voption * case : UnionCaseInfo -> UnionCaseEncoding

type UnionCaseEncoding =
    | Written of mark : UnionCaseMark * fields : ImmutableArray<UnionFieldPlace>
    | NotDescribed

type UnionCaseMark =
    | Tag of path : ImmutableArray<JsonStep> * tag : UnionTag   // the value at the path is the tag
    | Property of name : string                                 // the object has a property of this name
    | Null                                                      // the value is null
    | Unmarked                                                  // nothing tells the case

type UnionFieldPlace =
    | Value of path : ImmutableArray<JsonStep>     // the value of the field is at the path
    | Members of path : ImmutableArray<JsonStep>   // the field is a record whose members are in the object at the path

type JsonStep = Property of name : string | Item of index : int
type UnionTag = String of text : string | Number of number : int | Boolean of flag : bool

The mark is what a query tests to know the case: o["Payment"]["Case"] = "Card", o["Payment"][0] = "Card", IS_DEFINED(o["Payment"]["Card"]), or o["Payment"] = "Cash" when the path has no step. A place is the path from the value of the union to the value of a field: ["Fields"][0], ["Card"]["number"], [1]. Both start at the value of the union, so they hold wherever the union is: in a member, in an item of a collection, in a field of another union. The question is asked as the ones of #62 are, with the member that holds the union when a member does.

As before, the layout asks the serializer who writes the type: the contract of the union names the converter, and FSharp.SystemTextJson has a converter class for a union in general, one for a union without any field and one for a union that is written as its one field. The options that the union is written with say the rest; they are found as the ones of a record are (#61), which is one function for both now.

What the library really does, found in its source and by writing documents, and kept as tests:

• A null is null before anything else. The case that a union marked UseNullAsTrueValue represents by null is written as null in every encoding, also where a case without fields is its tag alone. The converter that the library has for a union without any field writes a tag for every case, but it never meets such a null: the compiler lets a union be marked so only when it has a case with fields as well (error FS1196 otherwise). The mark of such a case is Null; how a member that holds the null is written is the question of feat(quotations): describe how the serializer writes a member #61, OptionalEncoding.
• A case without fields is its tag alone only when the encoding says so (UnwrapFieldlessTags), and then in every encoding. Without it such a case is {"Case":"Cash"}, {"Cash":[]}, ["Cash"] or {}.
• One field in place of the fields (UnwrapSingleFieldCases): {"Case":"Circle","Fields":3} and {"Circle":3}. The tag among the fields and the encoding without tags do not do it.
• The members of a record in place of the fields (UnwrapRecordCases): the flag holds the one of named fields, so every case of the union gets named fields with it. Next to an internal tag the object is more than the record, {"Case":"Signed","Name":"n"}, which is the place Members; everywhere else the object is the record as it is written anywhere, which is the place Value. The converter of the union writes the members of such a record itself: with its own options of the serializer, and with the options of the library that it has or that it finds for the record. So the case is described only when the union is written with the common options and the converter among the options that writes the union makes the converter of the record as well. Otherwise what the layout says about the members of the record would not be about this object: a converter that [<JsonFSharpConverter>] on the record makes by itself has no naming policy, and another converter of the library among the options has other options. (The last two found by the review.)
• A union with one case that has one field is the value of that field (UnwrapSingleCaseUnions, on by default): StoredTicket guid is the text of the GUID. Its mark is Unmarked and the place of its field has no step. With several fields or none, the one case is written as a case of any union.
• The tag is the first name of the JsonName attribute of the case, which can be a text, a number or a boolean ({"Case":7}, and "7" and "true" as the name of a property), then the name of its JsonPropertyName, then the name of the case spelled by UnionTagNamingPolicy. The naming policy of the serializer does not reach a tag, and a declared name is not spelled by any policy.
• The name of a field is the name that F# gives it, Item for the one field of a case that the source does not name and Item1, Item2 for several. With UnionFieldNamesFromTypes such a field has the name of its type, and a name that the case then has twice gets a number: Int321, Int322. The case can declare another name for a field with JsonName("x", Field = "Item1"). Without one the name is spelled by UnionFieldNamingPolicy, and by the naming policy of the serializer when there is none.
• A part of the encoding in the attribute of a type is lost. [<JsonFSharpConverter(UnionNamedFields = true, UnionTagName = "kind")>] makes options that say that they inherit the encoding, and the library then takes the whole encoding from the common options: the fields stay an array, and the name of the tag is the one of the attribute. Only an attribute that sets the whole encoding (UnionEncoding = …) keeps it. The same holds for options in the overrides that are made with JsonFSharpOptions.InheritUnionEncoding ().
• System.Text.Json refuses a union, with NotSupportedException when it is to write a value. It writes a null without asking what it is a null of, so the null of a union does not show the refusal.
• A type that FSharp.SystemTextJson refuses arrives wrapped. A case with two JsonName attributes is refused when the converter is made, and the library makes its converters by reflection: the serializer throws TargetInvocationException. The layout takes it for a type that is not described, as the other refusals.

Not described, because nothing shows how the union is written: a member that names a converter of its own, also when that converter is the one of FSharp.SystemTextJson (it is made with options that nothing shows); a union whose contract a resolver of the application makes; a union that a class derived from the converter of FSharp.SystemTextJson writes; an encoding with two places for the tag, which the library fails to write. An option, a value option and a skippable value that are written as their value are no unions to this question: OptionalEncoding describes them. An option that the library writes as a union (UnwrapOption off) is described as any union, with None as its null.

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

The assembly is not packed yet (#58), so the packages are unchanged.

Checklist

• Build and tests pass locally
• I have added tests that prove my fix is effective or that my feature works (if appropriate)
• I have added necessary documentation (if appropriate)

Further comments

• Two commits: the library, then the tests.
• Tests: 126 in JsonLayoutUnionTests (FSharp.Azure.Cosmos.Quotations.Tests has 1637 now). The serializer is the oracle, and the test does not know the rules: it only reads the document.
  • 58 rows, one for every way to set the serializer up: the 31 of the layout tests and 27 that write a union differently (every place for the tag with every way to write the fields, names and naming policies of tags and fields, options for single types). Twelve union types are written, a value of every case: every way to declare a case and its fields, a union without fields with a number and a boolean for a tag, the three kinds of unions with one case, a case that is null, a struct union, private cases, a generic union, and two unions with options in an attribute. For every value the document has to hold the mark that the layout gives its case and the mark of no other case, and at the place of every field the JSON that the serializer writes for the value of the field. A union that the serializer refuses has to be not described.
  • 58 rows that ask the same about the union as the value of a member of a record: the value is looked for under the name that the layout gives the member.
  • 10 tests of what the rows cannot show: that the model is written with every kind of mark and place that there is (otherwise a layout that knows one way would pass), a part of the encoding in an attribute, a union that the library refuses, two places for the tag, a member with a converter of its own, an option as a union and as a value, a record in a case that is not written as the record is by itself, a contract that a resolver makes, a factory derived from the one of the library, and that an answer is kept.
• Can the tests fail? 67 one-line defects are planted in the new code, one at a time, and reverted: a name read from the wrong attribute or spelled by the wrong policy, an unwrapping flag ignored or always applied, a tag at the wrong place, the fields at the wrong index, a converter not recognized, the options of a type taken for the common ones. Each fails at least one test. The 105 defects of feat(quotations): describe how the serializer writes a member #61 and the 43 of feat(quotations): describe how values that are no objects are written #62 are run against this branch too.
• Where this departs from the sketch in the ADR (§10, §20.9):
  • the ADR has one layout for a union, a place for the tag and a way to write the fields. The library decides both for each case: a case without fields can be its tag alone next to cases that are objects, and one field or one record is unwrapped case by case. So the question is about a case;
  • the answer gives paths and no names of encodings, so the translator needs no table of its own, and a layout of another serializer can describe a union that fits none of these names;
  • a union that is written as its one field is no case of its own (ScalarWrapper in the ADR): it is the case Unmarked with a field in place of the union;
  • the encodings that a document was written with in the past (withLegacyUnionEncoding) come with phase 2, as the ADR has them.
• Not in this step:
  • a member of a case as a member of a document: whether a field of a case that is None is left out, and how an enumeration, a tuple, a collection or a map in a field of a case is written. FSharp.SystemTextJson leaves a named field out as it does a field of a record, and never an item of an array; the next step lets OptionalEncoding and the questions of feat(quotations): describe how values that are no objects are written #62 answer for such a member;
  • type discriminators of class hierarchies and Identity, the remaining members of IJsonLayout in the ADR;
  • OverrideMembers of FSharp.SystemTextJson, which gives a case other attributes by its name: the library keeps it internal, so the layout cannot read it (feat(quotations): describe how the serializer writes a member #61 has the same limit for records).
• Verification: dotnet build FSharp.Azure.Cosmos.slnx in Debug and Release with the warnings main has and none in the two Quotations projects, also with -p:WarnOn=3390; the tests pass in both configurations; Fantomas clean; the strict documentation build passes; both commits build, and the second passes the tests.
• No changelog entry: nothing is packed.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Enum-like fieldless unions can report a null mark even though the serializer writes their case tag.

1 open finding

• Null-case mark misclassified for enum-like fieldless unions · New

What changed in this PR

Adds the serializer-aware quotation infrastructure needed to translate F# union operations into Cosmos DB queries.

Changes:

• Adds quotation normalization, evaluation, parameterization, and error reporting.
• Describes serializer layouts for members, values, and union cases.
• Adds extensive unit tests and integrates the project into builds and documentation checks.

File	Description
.github/​copilot-instructions.md	Documents project standards and architecture.
.github/​workflows/​strict-documentation.yml	Adds strict documentation validation.
Directory.Packages.props	Adds centrally managed dependencies.
FSharp.Azure.Cosmos.slnf	Adds the quotation projects.
FSharp.Azure.Cosmos.slnx	Adds the quotation projects.
src/​Cosmos.Quotations/​AssemblyInfo.fs	Defines assembly metadata.
src/​Cosmos.Quotations/​Cosmos.Quotations.fsproj	Configures the quotation library.
src/​Cosmos.Quotations/​Internals.fs	Adds shared internal helpers.
src/​Cosmos.Quotations/​TranslationError.fs	Models translation failures and locations.
src/​Cosmos.Quotations/​Normalizer.fs	Normalizes quotation trees.
src/​Cosmos.Quotations/​Evaluator.fs	Evaluates variable-free expressions.
src/​Cosmos.Quotations/​Query.fs	Identifies query constants and parameters.
src/​Cosmos.Quotations/​Parameterizer.fs	Produces query shapes, templates, and values.
src/​Cosmos.Quotations/​JsonLayout.fs	Describes serializer document layouts.
tests/​Cosmos.Quotations.Tests/​Cosmos.Quotations.Tests.fsproj	Configures the quotation tests.
tests/​Cosmos.Quotations.Tests/​testconfig.json	Enables parallel test execution.
tests/​Cosmos.Quotations.Tests/​TestCategories.fs	Defines test categories.
tests/​Cosmos.Quotations.Tests/​Model.fs	Supplies quotation test models.
tests/​Cosmos.Quotations.Tests/​QuotationAssert.fs	Adds quotation assertion helpers.
tests/​Cosmos.Quotations.Tests/​NormalizerSpellingTests.fs	Tests normalized-expression formatting.
tests/​Cosmos.Quotations.Tests/​NormalizerTests.fs	Tests normalization behavior.
tests/​Cosmos.Quotations.Tests/​NormalizerErrorTests.fs	Tests normalization failures.
tests/​Cosmos.Quotations.Tests/​EvaluatorTests.fs	Tests expression evaluation.
tests/​Cosmos.Quotations.Tests/​ParameterizerShapeTests.fs	Tests query-shape identity.
tests/​Cosmos.Quotations.Tests/​ParameterizerTests.fs	Tests parameter extraction and templates.
tests/​Cosmos.Quotations.Tests/​ModelMembers.fs	Defines serializer member fixtures.
tests/​Cosmos.Quotations.Tests/​StoredModel.fs	Defines stored-document fixtures.
tests/​Cosmos.Quotations.Tests/​StoredValues.fs	Defines serialized value fixtures.
tests/​Cosmos.Quotations.Tests/​StoredUnions.fs	Defines serialized union fixtures.
tests/​Cosmos.Quotations.Tests/​JsonLayoutTests.fs	Tests member and optional layouts.
tests/​Cosmos.Quotations.Tests/​JsonLayoutValueTests.fs	Tests non-object value layouts.
tests/​Cosmos.Quotations.Tests/​JsonLayoutUnionTests.fs	Tests union-case layouts.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Unwrapped records can be described using different converter options than those used by their containing union.

1 open finding

• Avoid describing unwrapped records with mismatched converter options · New

1 resolved since last review

• Null-case mark misclassified for enum-like fieldless unions

🧠 Review effort: Balanced