DESIGN: Add alternative designs to the design doc on function composition

[catamorphism]

This document sketches out some alternatives for the machinery provided to enable function composition.

The goal is to provide an exhaustive list of alternatives.

[catamorphism]

Note: this is still pretty rough, but my goal in submitting this as a PR is to check whether the list of alternatives presented is complete. I wanted to get feedback on that before finishing the doc.

[eemeli]

I am uncomfortable with the further fracturing of this conversation across yet another document, but I guess this is how we're doing this?

I didn't pay particular attention to it before, but indeed the "part 1" of this explicitly notes that it is not going to evolve towards presenting any actual design. Will this document do that, or is it the intent that this too will be just setup for a final design to be presented in the data flow design doc?

I hope that's not the case, and that this document will evolve into a conclusion for this discussion, and that the earlier dataflow document can be dismissed. Otherwise, I would expect for each of these three documents to undergo significant edit work, so that they're significantly condensed. Already now they contain more text than our spec's syntax and formatting sections put together, and that seems disproportionate.

[catamorphism]

I am uncomfortable with the further fracturing of this conversation across yet another document, but I guess this is how we're doing this?

That's a fair point. There was even more that I was going to put into part 2, but I decided to leave everything out except the list of alternatives. Given that, it makes more sense to combine it with part 1, which I've done in a subsequent patch.

I didn't pay particular attention to it before, but indeed the "part 1" of this explicitly notes that it is not going to evolve towards presenting any actual design. Will this document do that, or is it the intent that this too will be just setup for a final design to be presented in the data flow design doc?

The document now presents several designs (with the changes in this PR) and I revised the introduction accordingly.

I hope that's not the case, and that this document will evolve into a conclusion for this discussion, and that the earlier dataflow document can be dismissed. Otherwise, I would expect for each of these three documents to undergo significant edit work, so that they're significantly condensed. Already now they contain more text than our spec's syntax and formatting sections put together, and that seems disproportionate.

I agree that the document needs some more edit work. Potentially the earlier dataflow document could be abandoned. Before I do that, I want to make sure I've identified the full set of alternative designs; the goal of this PR is to provoke that discussion.

I also agree with your observation about the size of these documents compared to the spec itself. I don't see a way around that, though. The alternative is to keep the spec as it is, while allowing the behavior of the use cases in the doc to be implementation-specific. If we do want these use cases to be portable, then I think the complexity is innate. I'm open to any suggestions for making it more concise.

[catamorphism]

For those who haven't read through the whole document before, I suggest just reading the diff and commenting if anything in it is unclear. I'll add cross-references accordingly.

[eemeli]

Note: this is still pretty rough, but my goal in submitting this as a PR is to check whether the list of alternatives presented is complete. I wanted to get feedback on that before finishing the doc.

This is missing the interface presented in #728. The Preservation Model is pretty close, but it includes ValueType and getInput() definitions that I think are unnecessary.

[eemeli]

From context I gather that the "It" that is tagged is ValueType, of which an interface definition is shown. But how can this be a "union of an InputType and a MessageValue" if the former is wholly implementation-defined? For example in a JS context supporting formatted parts, InputType will likely need to be something like the TS any, as all values could conceivably pass through the formatter.

Also, the mixing of "Type" and "Value" suffixes is confusing. Why not InputValue instead of InputType, and e.g. AnyValue instead of ValueType?

[eemeli]

Why does this need a getInput()? Text below mentions that "This solution allows functions to pipeline input,
operate on output, or both", but I don't understand what pipelining input here means, or why the consumer of a MessageValue would need to have access to its input.

[eemeli]

With this alternative, can an annotated value be used as an option value? If so, how does that work?

Can an :integer be "pipelined" into a :number, or a :datetime into a :date?

[eemeli]

It might be best then to name the types as e.g. MessageNumber and MessageString, as the generic names don't make it clear that these types have MF2-specific behaviours attached to them, such as formatting and selection.

I'm also not really sure how this is different from the two subsequent alternatives, except that the methods of a MessageValue are less explicitly defined.

[catamorphism]

I'm converting this back to draft mode. I'm experimenting with the value type in my implementation and I want to finish that before revising this text.

[catamorphism]

I'm inclined to close this PR because I don't think there's anything left that's not addressed by #728 -- any objections?

[aphillips]

I have no objections personally, although we might want to capture the materials (it is a design doc, after all), perhaps with the status "rejected" or "superseded" or "obsolete"?

[catamorphism]

I have no objections personally, although we might want to capture the materials (it is a design doc, after all), perhaps with the status "rejected" or "superseded" or "obsolete"?

I'm fine with adding "obsolete" to the original doc, but the original doc is already in the repo. This PR just adds more content to the doc. So the question is whether it's useful content or not.

[aphillips]

It's a lot of material to drop on the floor. I added it to the agenda for a couple minutes of discussion.

[aphillips]

In the 2024-10-14 call we agreed to merge this material and then mark the design document as obsolete. Approving its merger. I will adjust the page status manually.

[aphillips]

Suggested change

	<dd>2024-06-xx</dd>
	<dd>2024-06-04</dd>

[aphillips]

These are probably invaluable as examples, though. This stuff is difficult to talk about in the abstract.

[aphillips]

This is good, but probably insufficient?

• A declaration's side effects should be consistent across implementations.
• Option passing should be consistent between implementations

I think there is a hidden assumption in your requirement (the function/option set must be implemented and installed in both implementations)

[aphillips]

I'm not sure I agree with your implied logic here.

The getAge function doesn't change $person to a number. It changes (assigns) $age a number value.

The duration function doesn't change $age to a string. It assigns $y a value. In your example, $y is a string, but that might be inconsistent with what a duration formatter does. It's probably better here to use familiar functions, whose operation we know. I would probably replace getAge with getBirthDate and use date or datetime as the function here. If we did that... I'm not sure that $y is a string. I think then that $y is a an annotated date (and the reason for annotation would be to "float" the birthdate to prevent local time zones from changing the value--as well as preparing the value to be formatted later).

That leaves $z, which presumably calls $y's annotation to get a string, or, resolves the value of $y. If $y is still a date, its string representation might be the potentially-surprising ISO format (2024-06-05T00:00:00)

[aphillips]

We have carefully avoided types so far, although we have to some degree handwaved about types in the registry. To wit:

The operand of a number function is either an implementation-defined type or a literal whose contents match the number-literal production in the ABNF. All other values produce a Bad Operand error.

I think a better way to think about this solution is to separate the operand and the resolved value of an annotation. The operand isn't changed by the function, but the resolved value potentially is.