Updated the PR to answer comments raised above, added a bit of an intro to the description, and marking this as ready for review.

The biggest change is the addition of selection errors. One part of that is notable:

When selection fails to match any Variant, an empty string is used as the formatted string representation of the message and a Missing Fallback error is emitted.

Would it be more appropriate to use a whole-message fallback {???} in this case as well? The rationale with the current text is that not matching any variant means that there's no message content that should be shown.

I've created discussion #322 to continue the other vs * discussion, and have copied there the relevant comments above from @aphillips, @macchiati and myself, which are now hidden here.

@eemeli

Regarding syntax errors, we currently say this:

message-format-wg/spec/syntax.md

Lines 220 to 222 in 92ea19f

	A message satisfying all rules of the grammar is considered _well-formed_.
	Furthermore, a well-formed message can is considered _valid_
	if it meets additional semantic requirements about its structure, defined below.

I see some English grammatical issues with line 221 :-)

Could we separate these so that we'd consider a message that is not well-formed to have a Syntax Error, and a message which is not valid to have a Data Model Error?

Yes and we should formally define these (and other) error types. The set of errors should be as small as possible (but no smaller).

Separating these into different categories would make it easier to also define different error handling for them, in particular with respect to the Data Model Errors, which are in many cases recoverable while the former less so:

message-format-wg/spec/syntax.md

Lines 278 to 281 in 92ea19f

	A well-formed message is considered valid if the following requirements are satisfied:
	- The number of keys on each variant must be equal to the number of selectors.
	- At least one variant's keys must all be equal to the catch-all key (`*`).

This would also allow for Missing Fallback to be considered a Data Model Error.

The question here is whether the fallback is (as currently defined) an error at parse time or only triggers when none of the options are matched.

Updated to add data model errors as a category, along with a note:

Syntax and Data Model errors must be emitted as soon as possible.

Also, references to message identifiers are dropped and syntax errors in options get no special treatment.

Thank you very much for all the work and the patience!
The split between syntax / model / runtime (select format) feels clean, LGTM.

This document covers a lot of the types of errors that could occur, which is great.

It is very much written from the prospective of an "untyped" programming language environment. In many environments (such as templating systems), the message can be analyzed more completely, and many more errors can be "compile-time" errors or "lint" errors instead of "runtime" errors. So it would be good to note that.

For example, the syntax errors and variant key mismatch errors (which are really syntax errors) can easily be detected in such circumstances. When the system has access to the specified Selectors and Functions that are invoked in the course of processing the message, and knows the types of the arguments supplied, then that can also be checked.

If a system has access to the plural selector, then the following is detectable at compile time.
match {(horse) :plural}
when 1 {The value is one.}
...

Same for this one, if there is access to the get formatter.

{Hello, {(horse) :get field=name}!}

Upshot:

1. It would be useful to have some examples of errors that can't be detected by a system that has access to the types of the parameters and to the definitions of the Selection and Format functions that would be in play at runtime. (I don't see any currently in the document).
2. If we can't find such examples, then the document should make it clear that such systems do not have to have a Fallback String representation.

@macchiati:
[...] In many environments (such as templating systems), the message can be analyzed more completely, and many more errors can be "compile-time" errors or "lint" errors instead of "runtime" errors. So it would be good to note that.

I've now added a first paragraph noting this:

Errors in messages and their formatting may occur and be detected at multiple different stages of their processing. Where available, the use of validation tools is recommended, as early detection of errors makes their correction easier.

@macchiati:
1. It would be useful to have some examples of errors that can't be detected by a system that has access to the types of the parameters and to the definitions of the Selection and Format functions that would be in play at runtime. (I don't see any currently in the document).

I've added a fourth example under Formatting errors which I believe demonstrates such an error. I'm not claiming that what it presents is good practice, or that it couldn't be avoided by e.g. a stricter typing of the value of $field, but it's at least technically valid MF2.

@stasm Do you think we could/should include in the function registry some (optional) gating on when/whether a function could fail? It might be useful to be able to determine the complete set of conditions that's required and/or sufficient for formatting a message without any failure. This would be beyond the scope of this PR, but might allow for earlier/easier detection of errors.

Errors in messages and their formatting may occur and be detected at multiple different stages of their processing. Where available, the use of validation tools is recommended, as early detection of errors makes their correction easier.

This isn't quite what I meant, which is something more like:

Where (a) the Selector and Format definitions are accessible, and (b) the number and types of the input parameters are known, proper use of validation tooling can ensure that there will be no runtime errors emitted.

(I don't see your "fourth example under Formatting errors" yet)

@macchiati:
By "fourth example under Formatting errors" do you mean a 4th example under iii ? I was looking for an iv but didn't find it.

The added example is on line 173:

{Your {$field} is {$id :get field=$field}}

The error here relies on line 154, also added in the same commit:

2. provides for the variable reference $field to resolve to a string 'address'

@macchiati:
Where (a) the Selector and Format definitions are accessible, and (b) the number and types of the input parameters are known, proper use of validation tooling can ensure that there will be no runtime errors emitted.

I don't think we can or should guarantee "no runtime errors", because we can't control what sorts of custom functions provided by third parties may be used. For example, there could be an :env function available that finds an environment variable matching its string argument. While we can ensure with that said argument is a string, we can't really ensure before running the code in its environment that every environment variable is available or has an expected shape.

As discussed at the last meeting, let's merge this now that it has general approval and (as far as I can tell) blocker issues have been resolved. We can (and should!) continue to improve this section and the whole spec, but let's do so within the scope of further issues and PRs.

@eemeli Thank you for merging this: I had planned to ask you to do it today, but you beat me to it 🎉

I don't think we can or should guarantee "no runtime errors", because we can't control what sorts of custom functions provided by third parties may be used. For example, there could be an :env function available that finds an environment variable matching its string argument. While we can ensure with that said argument is a string, we can't really ensure before running the code in its environment that every environment variable is available or has an expected shape.

Let me expand on this a bit. Of course, when you reference a Selector or Formatter that throws an error, you can't do anything about that. And that can certainly be the case for custom Selectors and Functions.

The following is still pretty rough, but it is what I'm trying to get at.

A Selector is well-behaved when all of the following conditions are met:

1. It declares a domain of variant keys, (eg "high", "medium", "low"; or integers).
2. It declares a set of modifiers.
3. For any set of modifiers it will return true for at least one element in that domain, and will return true or false for all others (without error).
4. It will always return true for *, with any set of modifiers.

A Function is well-behaved when all of the following conditions are met:

1. It declares a domain of variant keys (eg "high", "medium", "low"; or integers)
2. It declares a set of modifiers.
3. For any set of modifiers it will return a string for each element in that domain. (without error)

Note: implementations of all standard registered Selectors and Functions must be well-behaved.

A message is well-behaved all of the following conditions are met:

1. It is syntactically correct.
2. All of its Selectors and Functions are well-behaved.

Inputs to a message are complete when there is a value for each one of them that is used by a Selector or Function in the message, and that value is in the domain of those Selector or Function.

Well-behaved messages will not produce errors when their inputs are complete. This does not, of course, include extraordinary conditions such as out-of-memory.

Back to your example, an :env function would not be well-behaved, and thus any message that used it might throw errors.

It declares a domain of variant keys, (eg "high", "medium", "low"; or integers).

I believe we should leave syntactic and semantic space for open bound selectors.

An example of such selector:

match {$cityName}
  when "New York" {Nowy Jork}
  when "Paris" {Paryż}
  when * {$cityName}

@macchiati It sounds like we should include an attribute of some sort in the function registry for declaring whether a function is "well-behaved" or not, so that this could be used as input for e.g. validators. Would you be ok with filing this as a separate issue, so that we don't lose track of this conversation at the tail end of a closed PR?

I said I would do this a while back; just added the issue as #377