From 4ab5aff378c196bd27e851fda6959cf82cb4f4e8 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 6 Nov 2024 07:39:49 -0800 Subject: [PATCH 01/16] Provide normative guidance on allowing optional options, values, and functions See #924 for the origin of this PR. --- spec/registry.md | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index eb8fb62972..1f3712383a 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -1,11 +1,34 @@ # MessageFormat 2.0 Default Function Registry -This section describes the functions for which each implementation MUST provide -a _function handler_ to be conformant with this specification. - -Implementations MAY implement additional _functions_ or additional _options_. -In particular, implementations are encouraged to provide feedback on proposed -_options_ and their values. +This section defines the **standard** _functions_ which are REQUIRED for conformance with this specification, +along with **optional** _functions_ that SHOULD be implemented to support +additional functionality. + +Implementations MUST define and support each **standard** _function_ and +MUST accept all _options_ and _option_ values defined as **standard** listed in this specification. + +When defined and supported by an implementation, each **optional** _function_ +MUST accept all _options_ and _option_ values listed as **standard** in this specification. + +Implementations SHOULD implement _options_ and _option_ values that are marked as **optional**. + +Implementations MAY implement _functions_ not defined in this specification. +Such functions MUST use an implementation-defined _namespace_. +In addition, implementations are encouraged to provide mechanisms for users to +register and use user-defined _functions_ and their associated _functional handlers_. + +Implementations MAY implement additional _options_ not defined here. +Such _options_ MUST use an implementation-specific _namespace_. + +Implementations MAY implement additional _option_ values for _options_ defined here, +although care needs to be exercised to ensure interoperability +and to avoid collisions with future standardization. +There is no namespace mechanism for _option_ values, +however, the [stability policy](#stability-policy) for this specification +permits only the ranges a-z, A-Z, and 0-9 in _option_ values. +Implementation-defined values SHOULD use a distinguishing character +or character sequence, such as by prefixing with a `_` U+005F LOW LINE, +to ensure that they don't collide with future standardization. > [!NOTE] > The [Stability Policy](/spec#stability-policy) allows for updates to From eafc74596356b166eb30a0a9c7d2a9535922dc68 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 6 Nov 2024 14:51:08 -0800 Subject: [PATCH 02/16] Update spec/registry.md Co-authored-by: Eemeli Aro --- spec/registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index 1f3712383a..07d4641eb9 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -14,7 +14,7 @@ Implementations SHOULD implement _options_ and _option_ values that are marked a Implementations MAY implement _functions_ not defined in this specification. Such functions MUST use an implementation-defined _namespace_. -In addition, implementations are encouraged to provide mechanisms for users to +In addition, implementations SHOULD provide mechanisms for users to register and use user-defined _functions_ and their associated _functional handlers_. Implementations MAY implement additional _options_ not defined here. From 065666213a2cca58b4062cfb839526d1c4bfba58 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Fri, 8 Nov 2024 09:14:07 -0800 Subject: [PATCH 03/16] Define _accept_ and use that term --- spec/registry.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index 07d4641eb9..3f375cccae 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -4,15 +4,29 @@ This section defines the **standard** _functions_ which are REQUIRED for conform along with **optional** _functions_ that SHOULD be implemented to support additional functionality. -Implementations MUST define and support each **standard** _function_ and -MUST accept all _options_ and _option_ values defined as **standard** listed in this specification. +To **_accept_** a function means that an implementation MUST NOT +emit an _Unknown Function_ error for that _function_'s _identifier_. +To _accept_ an option means that an implementation MUST NOT +emit a _Bad Option_ error for that _option_'s _identifier_ when used with the _function_ +it is defined for +and MUST NOT emit a _Bad Option_ error for any of the _option_ values +(both **standard** and **optional**) +defined for that _option_. +Accepting a _function_ or its _options_ does not mean that any given output is produced. -When defined and supported by an implementation, each **optional** _function_ -MUST accept all _options_ and _option_ values listed as **standard** in this specification. +_Functions_ can define _options_. +An _option_ can be **standard** or **optional**. -Implementations SHOULD implement _options_ and _option_ values that are marked as **optional**. +Implementations MUST _accept_ each **standard** _function_ and +MUST _accept_ all _options_ and _option_ values defined as **standard** for those _functions_. -Implementations MAY implement _functions_ not defined in this specification. +Implementations SHOULD _accept_ each **optional** _function_. +For each such _function_, the implementation MUST accept all _options_ and _option_ values +listed as **standard** for that _function_. + +Implementations SHOULD _accept_ _options_ and _option_ values that are marked as **optional**. + +Implementations MAY _accept_ _functions_ not defined in this specification. Such functions MUST use an implementation-defined _namespace_. In addition, implementations SHOULD provide mechanisms for users to register and use user-defined _functions_ and their associated _functional handlers_. @@ -20,7 +34,7 @@ register and use user-defined _functions_ and their associated _functional handl Implementations MAY implement additional _options_ not defined here. Such _options_ MUST use an implementation-specific _namespace_. -Implementations MAY implement additional _option_ values for _options_ defined here, +Implementations MAY _accept_ additional _option_ values for _options_ defined here, although care needs to be exercised to ensure interoperability and to avoid collisions with future standardization. There is no namespace mechanism for _option_ values, From 0a78c8e710813ef1f9faff712444b7034cc5a28e Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Fri, 8 Nov 2024 09:25:20 -0800 Subject: [PATCH 04/16] Update spec/registry.md --- spec/registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index 3f375cccae..25f21ace06 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -27,7 +27,7 @@ listed as **standard** for that _function_. Implementations SHOULD _accept_ _options_ and _option_ values that are marked as **optional**. Implementations MAY _accept_ _functions_ not defined in this specification. -Such functions MUST use an implementation-defined _namespace_. +Functions not defined by any version of this specification MUST use an implementation-defined _namespace_. In addition, implementations SHOULD provide mechanisms for users to register and use user-defined _functions_ and their associated _functional handlers_. From 380c6ff390fbcffc1458bc9fcc5bd67ab09f6f97 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Fri, 8 Nov 2024 15:13:53 -0800 Subject: [PATCH 05/16] Update spec/registry.md Co-authored-by: Mark Davis --- spec/registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index 25f21ace06..05ce19d738 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -12,7 +12,7 @@ it is defined for and MUST NOT emit a _Bad Option_ error for any of the _option_ values (both **standard** and **optional**) defined for that _option_. -Accepting a _function_ or its _options_ does not mean that any given output is produced. +Accepting a _function_ or its _options_ does not mean that a particular output is produced. _Functions_ can define _options_. An _option_ can be **standard** or **optional**. From 5b0ff59b459f55a8ed96ee36b6686f4ae99477ed Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Sun, 10 Nov 2024 07:58:34 -0800 Subject: [PATCH 06/16] Update spec/registry.md Co-authored-by: Eemeli Aro --- spec/registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index 05ce19d738..b5ea37a7c8 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -6,7 +6,7 @@ additional functionality. To **_accept_** a function means that an implementation MUST NOT emit an _Unknown Function_ error for that _function_'s _identifier_. -To _accept_ an option means that an implementation MUST NOT +To _accept_ an option means that a _function handler_ MUST NOT emit a _Bad Option_ error for that _option_'s _identifier_ when used with the _function_ it is defined for and MUST NOT emit a _Bad Option_ error for any of the _option_ values From 186890fa98ecf8543cb55bc2ec98ba724c66e6aa Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Sun, 10 Nov 2024 08:41:15 -0800 Subject: [PATCH 07/16] Update spec/registry.md Co-authored-by: Eemeli Aro --- spec/registry.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index b5ea37a7c8..87ecbf2cc9 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -31,7 +31,8 @@ Functions not defined by any version of this specification MUST use an implement In addition, implementations SHOULD provide mechanisms for users to register and use user-defined _functions_ and their associated _functional handlers_. -Implementations MAY implement additional _options_ not defined here. +Implementations MAY implement additional _options_ not defined here +for **standard** and **optional** functions. Such _options_ MUST use an implementation-specific _namespace_. Implementations MAY _accept_ additional _option_ values for _options_ defined here, From cd8db87f485d247ea76ffe47ef6e0e30c0ea23ad Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Sun, 10 Nov 2024 08:46:52 -0800 Subject: [PATCH 08/16] Address comments around function namespacing --- spec/registry.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index 87ecbf2cc9..3ea88b3b7e 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -27,9 +27,10 @@ listed as **standard** for that _function_. Implementations SHOULD _accept_ _options_ and _option_ values that are marked as **optional**. Implementations MAY _accept_ _functions_ not defined in this specification. -Functions not defined by any version of this specification MUST use an implementation-defined _namespace_. In addition, implementations SHOULD provide mechanisms for users to register and use user-defined _functions_ and their associated _functional handlers_. +Functions not defined by any version of this specification SHOULD use +an implementation-defined or user-defined _namespace_. Implementations MAY implement additional _options_ not defined here for **standard** and **optional** functions. From 1d7c836558737fc001237f1baac42456a9d13b1a Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 11 Nov 2024 11:45:40 -0800 Subject: [PATCH 09/16] Address 2024-11-11 telecon comments - Define _Unsupported Operation_ error allowance - Remove mentions of the Default Registry - Convert note to text - Incorporate suggestions --- spec/registry.md | 34 ++++++++++++++++------------------ 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index 3ea88b3b7e..2491a49286 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -13,6 +13,8 @@ and MUST NOT emit a _Bad Option_ error for any of the _option_ values (both **standard** and **optional**) defined for that _option_. Accepting a _function_ or its _options_ does not mean that a particular output is produced. +Implementations MAY emit an _Unsupported Operation_ error for _options_ +or _option_ values that they cannot support. _Functions_ can define _options_. An _option_ can be **standard** or **optional**. @@ -36,24 +38,20 @@ Implementations MAY implement additional _options_ not defined here for **standard** and **optional** functions. Such _options_ MUST use an implementation-specific _namespace_. -Implementations MAY _accept_ additional _option_ values for _options_ defined here, -although care needs to be exercised to ensure interoperability -and to avoid collisions with future standardization. -There is no namespace mechanism for _option_ values, -however, the [stability policy](#stability-policy) for this specification -permits only the ranges a-z, A-Z, and 0-9 in _option_ values. -Implementation-defined values SHOULD use a distinguishing character -or character sequence, such as by prefixing with a `_` U+005F LOW LINE, -to ensure that they don't collide with future standardization. - -> [!NOTE] -> The [Stability Policy](/spec#stability-policy) allows for updates to -> Default Registry functions to add support for new options. -> As implementations are permitted to ignore options that they do not support, -> it is possible to write messages using options not defined below -> which currently format with no error, but which could produce errors -> when formatted with a later edition of the Default Registry. -> Therefore, using options not explicitly defined here is NOT RECOMMENDED. +Implementations MAY _accept_ additional _option_ values for _options_ defined here. +However, such values might become defined with a different meaning in the future, +including with a different, incompatible name +or using an incompatible value space. +Supporting implementation-specific _option_ values for **standard** or **optional** functions is NOT RECOMMENDED. + +Future versions of this specification MAY define additional _options_ and _option_ values, +subject to the rules in the [Stability Policy](#stability-policy), +for _functions_ found in this specification. +As implementations are permitted to ignore _options_ that they do not support, +it is possible to write _messages_ using _options_ not defined below +which currently format with no error, but which could produce errors +when formatted with a later edition of this specification. +Therefore, using _options_ not explicitly defined here is NOT RECOMMENDED. ## String Value Selection and Formatting From 2cc3e049636a9783696e867c0b9b66b86bb638ab Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 11 Nov 2024 11:49:19 -0800 Subject: [PATCH 10/16] Add _Unsupported Operation_ error --- spec/errors.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/spec/errors.md b/spec/errors.md index 5782622b2e..f75c0e8746 100644 --- a/spec/errors.md +++ b/spec/errors.md @@ -382,3 +382,9 @@ does not match the expected implementation-defined format. > horse {{The value is a horse.}} > * {{The value is not one.}} > ``` + +### Unsupported Operation + +A **_Unsupported Operation_** error is an implementation-specific error +that occurs when a given _option_, _option_ value, _operand_ value, or some combination +of these are incompatible or not supported by a given _function_ or its _function handler_. From 32bfa3bb4fce29b3e22346be2c47dd6108ab75f5 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 13 Nov 2024 13:41:59 -0800 Subject: [PATCH 11/16] Update spec/registry.md Co-authored-by: Eemeli Aro --- spec/registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index 2491a49286..88df29473f 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -6,7 +6,7 @@ additional functionality. To **_accept_** a function means that an implementation MUST NOT emit an _Unknown Function_ error for that _function_'s _identifier_. -To _accept_ an option means that a _function handler_ MUST NOT +To _accept_ an _option_ means that a _function handler_ MUST NOT emit a _Bad Option_ error for that _option_'s _identifier_ when used with the _function_ it is defined for and MUST NOT emit a _Bad Option_ error for any of the _option_ values From 327ead38e9ca896c730d686736a1477c7a1ba1da Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 13 Nov 2024 13:43:42 -0800 Subject: [PATCH 12/16] Update spec/registry.md Co-authored-by: Eemeli Aro --- spec/registry.md | 1 - 1 file changed, 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index 88df29473f..a18e0c81fd 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -10,7 +10,6 @@ To _accept_ an _option_ means that a _function handler_ MUST NOT emit a _Bad Option_ error for that _option_'s _identifier_ when used with the _function_ it is defined for and MUST NOT emit a _Bad Option_ error for any of the _option_ values -(both **standard** and **optional**) defined for that _option_. Accepting a _function_ or its _options_ does not mean that a particular output is produced. Implementations MAY emit an _Unsupported Operation_ error for _options_ From 0b36edc0d147e4575252adcc077a9ace2780e638 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 13 Nov 2024 13:48:15 -0800 Subject: [PATCH 13/16] Update spec/registry.md Co-authored-by: Eemeli Aro --- spec/registry.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index a18e0c81fd..3dc30770c2 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -33,7 +33,8 @@ register and use user-defined _functions_ and their associated _functional handl Functions not defined by any version of this specification SHOULD use an implementation-defined or user-defined _namespace_. -Implementations MAY implement additional _options_ not defined here +Implementations MAY implement additional _options_ not defined +by any version of this specification for **standard** and **optional** functions. Such _options_ MUST use an implementation-specific _namespace_. From b34fd64a3850f36d913f0e99c1d9241a1486eb2b Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Thu, 14 Nov 2024 08:04:18 -0800 Subject: [PATCH 14/16] Update spec/registry.md Co-authored-by: Eemeli Aro --- spec/registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index 3dc30770c2..db201095ac 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -19,7 +19,7 @@ _Functions_ can define _options_. An _option_ can be **standard** or **optional**. Implementations MUST _accept_ each **standard** _function_ and -MUST _accept_ all _options_ and _option_ values defined as **standard** for those _functions_. +MUST _accept_ all _options_ defined as **standard** for those _functions_. Implementations SHOULD _accept_ each **optional** _function_. For each such _function_, the implementation MUST accept all _options_ and _option_ values From 5dc5067c33b8b54ac6dccee909dabfed6fb0aa6c Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Thu, 14 Nov 2024 08:04:33 -0800 Subject: [PATCH 15/16] Update spec/registry.md Co-authored-by: Eemeli Aro --- spec/registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index db201095ac..e6ec6ffa30 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -22,7 +22,7 @@ Implementations MUST _accept_ each **standard** _function_ and MUST _accept_ all _options_ defined as **standard** for those _functions_. Implementations SHOULD _accept_ each **optional** _function_. -For each such _function_, the implementation MUST accept all _options_ and _option_ values +For each such _function_, the implementation MUST accept all _options_ listed as **standard** for that _function_. Implementations SHOULD _accept_ _options_ and _option_ values that are marked as **optional**. From 1e5a13d7aa46dc50b12b4b0a2194c659991b8f38 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Thu, 14 Nov 2024 08:04:45 -0800 Subject: [PATCH 16/16] Update spec/registry.md Co-authored-by: Eemeli Aro --- spec/registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index e6ec6ffa30..cfb300755d 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -25,7 +25,7 @@ Implementations SHOULD _accept_ each **optional** _function_. For each such _function_, the implementation MUST accept all _options_ listed as **standard** for that _function_. -Implementations SHOULD _accept_ _options_ and _option_ values that are marked as **optional**. +Implementations SHOULD _accept_ _options_ that are marked as **optional**. Implementations MAY _accept_ _functions_ not defined in this specification. In addition, implementations SHOULD provide mechanisms for users to