Repository navigation
[cdac] data contract spec follow up items and open questions #100162
Description
(Part of #99298 )
This is a summary of the remaining unsettled questions from the discussion on #99936.
The intention is to merge the initial version of the spec and to address each of these in follow-up PRs or separate discussions.
- Do we need different types of contracts? Can we just have algorithm contracts and a globals+type layout descriptor while still maintaining a compact payload in a target runtime. Spec update in [cdac] Data Descriptor Spec #100253
- Can we generate the data descriptor compositionally.
There is a proposal in Initial spec for the meaning and relationships between data contracts #99936 (comment) and parent comments for how to do this. PR, following the proposal [cdac] cdac-build-tool #100650 - Should we make the contract partly machine readable by including some yaml frontmatter metadata? That will allow us to validate certain kinds of spelling/version mistakes as we build the tooling. There is a proposal in Initial spec for the meaning and relationships between data contracts #99936 (comment) and parent comments.
- We need a physical descriptor layout spec. [cdac] Publish data stream spec #99299
- Do we need major/minor versions on contracts? TBD.
- How frequently is it acceptable for the runtime to introduce breaking changes in the future? Discussion in Initial spec for the meaning and relationships between data contracts #99936 (comment) and Initial spec for the meaning and relationships between data contracts #99936 (comment)
- Style for defining algorithmic contracts. Merge the data structures and api into one section and make it look more like a typical C# API? Omit the Dac prefix on data structure definitions? Initial spec for the meaning and relationships between data contracts #99936 (comment)
Activity
[cdac] Data Descriptor Spec (#100253)
[cdac] Data Descriptor Spec (dotnet#100253)
[cdac] Data Descriptor Spec (dotnet#100253)
noahfalk commentedon Jul 30, 2026
I think these questions have been resolved at one point or another:
Do we need different types of contracts? No
Can we generate the data descriptor compositionally - No current plan.
Should we make the contract partly machine readable by including some yaml frontmatter metadata? There is some machine generated markup for the data fields in the data contract markdown, but nothing else is machine readable.
We need a physical descriptor layout spec. Done in #99299
Do we need major/minor versions on contracts? Not at this time. Contracts are named and contract implementations are named, but there is currently no explicit version in the sense that it is numeric, ordered, or follows a convention like semver. For a given contract name and contract implementation we expect readers either recognize it or don't recognize it.
How frequently is it acceptable for the runtime to introduce breaking changes in the future? Breaking changes during development of a new major runtime version are acceptable though we should try to keep them infrequent. Once a given runtime reaches RC breaking changes should no longer occur throughout its servicing lifetime.
Style for defining algorithmic contracts. Merge the data structures and api into one section and make it look more like a typical C# API? Omit the Dac prefix on data structure definitions? We've implicitly converged on some documentation conventions used in the data contract markdown. Nothing prevents us from changing this in the future if we think a different documentation style would be more effective.