[FBumann]

Prompt: I like that. However, could we get closer to the file the user wrote initially?

Prompt: Yes! Implement it

Prompt: We should probably change how this comparision works...

Prompt: The callable claims concept seems to complex...

Prompt: Should we keep g: {description: null}? It might mean an overwrite with null…?

Prompt: Why do we not keep 1. More strict for now?

Prompt: I like the content. But it should be less jargon

Note

The following content was generated by AI.

to_yaml() writes back the fields the file wrote, plus version:. The canonical form leaves out every default. A patch may change three fields of a dimension or a relation its base declares, and no others.

Stacked on #924, which squashes #914, #916 and #921.

What the writer writes

Field	Did the file write it?	Before	to_yaml()	canonical
ordered: false	yes	dropped	kept	dropped
a dimension's dtype: str	no	added	not written	not written
a parameter's dtype: float	no	added	not written	not written
a variable's domain: continuous, missing: absent	no	added	not written	not written
version: 0	no	added	written	written
missing: refused	yes	dropped	kept	dropped

• One rule. Before, four classes each had their own serializer, and each dropped a different default. Now one serializer writes the fields the input set, and leaves out a null and an empty mapping. The four classes that can be written as a bare string keep their own serializer.
• The canonical form leaves out every field that holds its default, except version:. So two files that differ only in a default they write out give the same text.
• An entry that sets no field is still written. generator: {} and generator: {description: null} both write back as generator: {}, because the entry still declares the dimension. An empty kind under given: is not written.
• A merged spec writes the fields its fragments wrote. docs/examples/library/composed.md loses 7 lines of defaults that its fragments never wrote.

What a patch may change

For a dimension or a relation that the base declares, a patch may change these three fields:

Field	On	What the patch may do
description	a dimension or a relation	replace the base's text, or remove it with null
ordered	a dimension	set it to true, but not to false or null where the base has true
missing	a relation	replace the base's value, or put back the default with null

A patch entry that writes only these fields changes only these fields. An entry that writes any other field, or no field, must declare the dimension or the relation as the base does. A field it leaves out reads as its default. This is strict on purpose: a looser rule can come later without breaking a patch that loads now.

Between fragments in merge, nothing changes. Two fragments that declare one dimension or relation must agree on every field except two. A dimension is ordered if one fragment says so. The first description given is kept.

In the code, SETTINGS names ordered and missing. One helper, _same, compares two entries field by field and leaves out the fields its caller names. _declared, _claims, _reading_claims, _joined and the claims= callable are gone.

In the docs, the reading guide says what to_yaml() writes. The how-to on composing has the table above, and its quoted refusals match what the code prints.

Why

Before, to_yaml() added some defaults that a file left out, and dropped others that it wrote. Each class had its own rule, so no one rule said what the writer writes. Now a file reads back as its author wrote it, apart from comments, layout and the sorted lists and entries from #924. Writing every default would not make a change of a default safe, because hand-written files leave defaults out. version: tells a reader which version of the language the file is written in, so the writer always writes it.

Before, a patch was checked as "the same as the base, except for these fields", and each field needed its own decision about which list it was on. The bugs below came from that.

Method, bugs found, gate output, mutation table

Method. pydantic records in model_fields_set the fields that an input sets, a default included. _as_set keeps those fields, except for a null or an empty mapping. Spec's own serializer adds version and removes nulls. A mapping that removing nulls left empty is dropped. A mapping written empty stays.

A branch that read exclude_defaults in the serializer was removed. No input reaches it, because a field that the input did not set still holds its default: no validator sets one after validation. With the branch deleted, the suite stayed green.

Bugs found in review. Each has a test that failed before its fix.

Fixed in	Bug
eb1ae90	g: {description: null} wrote back as nothing, so the written file named a dimension it did not declare.
eb1ae90	given: {parameters: {}} was written back.
eb1ae90	override accepted a patch that gave a dimension or a relation a new description, and then dropped the new text. On the base before this PR, the patch was refused.
9d49497	A patch that wrote description: null kept the base's description.
9d49497	A patch that wrote only a description was refused over a dimension whose dtype is not the default, because the left-out dtype read as the default.
e06f56a	A patch that wrote only ordered: true was refused in the same way.
e06f56a	ordered: null over an ordered dimension failed with a schema error, not with the message that names the fix.

A null in a fragment for merge is not a bug. merge reads each fragment after it loads, and there a null means the field is not set.

846f33c changes only words: the how-to, the module docstring, the refusal message, and the name CLAIMS, which is now SETTINGS.

Tests.

• test_a_spec_writes_the_fields_its_file_wrote_and_its_version replaces test_a_default_is_written_out_and_an_absence_is_not, which asserted the old rule.
• test_a_dimension_writes_ordered_as_its_file_wrote_it replaces test_a_dimension_writes_ordered_only_where_it_is_true. It has three cases: left out, written false, written true.
• test_a_patch_that_withdraws_ordered_is_refused now has three cases: false with the dtype, false alone, and null.
• New: test_the_canonical_form_writes_no_default, test_an_entry_whose_only_field_is_null_still_declares_it, test_an_empty_kind_under_given_is_not_written, test_a_patch_may_add_ordered_alone, and test_a_patch_that_restates_a_shared_entry_gives_it_its_own_description. The last one has five cases: a dimension, a relation, the description alone, and null on a dimension and on a relation.

Moving onto #924. 0c0f1ee merges #924 into this branch. Each conflict resolves to the tree of #921's head, which held #914, #916, #918 and #921 together. 3a461e7 merges #924's changelog commit. Against #924 this PR's diff is its own 10 files again, +304 and −152.

Gates on 3a461e7:

• pixi run lint: passed.
• pixi run test: 3550 passed, 1 skipped.
• pixi run docs-build: passed on 0c0f1ee. 3a461e7 changes only CHANGELOG.md.
• Every generator re-run on 0c0f1ee: no diff.
• compile-tex: did not run here, because Tectonic could not download its bundle in the sandbox. CI runs it.

Mutation table. A script made each change and ran the full suite. It restored the file with git checkout --, deleted __pycache__ before and after each run, and checked that the tree came back clean each time. Rows 1 to 5 ran on eb1ae90, in code that later commits did not change. Rows 6 to 10 ran on e06f56a. 846f33c renames and rewords only. The rows were not re-run after the move onto #924, which changes no line this PR touches in src/.

Change	Caught by
the writer keeps a null field	1 failure: test_an_entry_whose_only_field_is_null_still_declares_it
the writer keeps an empty-mapping field	13 failures, among them test_a_whole_model_writes_no_given_section
_same compares descriptions	13 failures and 12 errors, among them test_the_order_of_the_fragments_reaches_no_canonical_text[an-objective-on-a-sum]
a patch compares missing	2 failures, among them test_a_patch_changes_what_a_key_the_map_leaves_out_means[restated-absent]
fragments do not join ordered	2 failures, among them test_a_patch_restates_a_dimension_as_the_schema_reads_it[widened-to-ordered]
a patch may not change ordered or missing	11 failures, among them test_a_patch_restates_a_dimension_as_the_schema_reads_it[ordered-left-out]
a patch may set ordered to false	3 failures of test_a_patch_that_withdraws_ordered_is_refused
a patch that changes only these fields is checked as a full declaration	6 failures, among them test_a_patch_that_restates_a_shared_entry_gives_it_its_own_description[the-description-alone]
a null the patch writes is kept, not reset to the default	2 failures: test_a_patch_that_withdraws_ordered_is_refused[null] and test_a_patch_changes_what_a_key_the_map_leaves_out_means[null-puts-back-the-default]
fragments compare ordered	2 failures of test_a_dimension_one_fragment_declares_ordered_is_ordered_in_the_composition

Not done

• A looser patch rule, where a field that a patch leaves out keeps the base's value, is not done. It can come later without breaking a patch that loads now. The reverse would break one.
• Comments, quoting and line layout are not kept. That would need a YAML parser that keeps them, ruamel.yaml, which is a new runtime dependency. It would help only a spec that is loaded from one file and written back, and there the file itself is the exact copy.
• Two equal specs can write different text. == does not compare model_fields_set, so a spec that writes ordered: false equals one that leaves it out. The canonical form gives the same text where == is true.
• A 0 bound comes back as 0.0, because the field is a float.
• Whether the loader should require version: in a hand-written file is a separate question for before 1.0.
• Older wording in merge's docs ("claim", "laid over") is not changed, because this PR does not change those rules.
• The PR title names only the writer. The patch rules are a second change that a changelog reader may want to see.
• feat(spec)!: a loaded spec cannot be changed, so the file it writes back out is always the one its program comes from #923 (a frozen spec) conflicts with this PR and feat(spec)!: a loaded spec is sorted by name and cannot be changed, writes back the fields its file wrote, and prints one canonical text for two files that differ only in order or spelling #924 in spec.py.

🤖 Generated with Claude Code

https://claude.ai/code/session_019j1TmBS3MvzmuarWjhCHHu

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #35290109 | 📁 Comparing 3a461e7 against latest (0f892c0)

  🔍 Preview build  

52 files changed · ± 52 modified

± Modified

• index.html
• first-spec/index.html
• several-files/index.html
• examples/commitment/index.html
• examples/dispatch/index.html
• examples/operators/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• howto/compose/index.html
• howto/see-an-expansion/index.html
• and 42 more...

[FBumann]

Prompt: i think the sorting one should replace the others with the clear goal of making everything sorted and pedictable, saying the others are superseeded and making them drafts. Not closing them

Note

The following content was generated by AI.

Superseded by #924. This branch was merged into #924 at 037502a, together with #923 and #927. The write-back and patch rules are unchanged there. This PR stays open as a draft for its review history.

---

Generated by Claude Code