(Design) Extending functions/options/namespacing

[aphillips]

Here is the design document for extending functions and options and the namespacing thereof.

This describes the namespacing elements and some of the normative text needed, along with early ABNF changes.

Note that I extended the reach of namespaces to:

• functions
• options
• expression attributes

[stasm]

A quick first pass of my review, but this is looking very much in line with what I had imagined. Thanks for writing it!

It would be great to also include a list of changes to the spec that we'll need to make as a result of this design, so that we can track them and make sure the PR that follows the design is comprehensive. For example:

• From the use-case about tooling, I gather we'll want to design changes to the data model, too?
• The function resolution section of formatting.md. How are implementations supposed to resolve namespaced functions?
• The error handling section of formatting.md. What happens when a namespace is not known to the runtime?
• Are any changes to the registry required? (It doesn't seem so.)

[stasm]

I'm not sure if nmtoken limits us here. Function names are recognized by the : prefix and function options can only appear in very specific positions.

Instead, it might make sense to add a constraint about : being already used in the syntax. Namespace syntax can leverage this fact (like this proposal suggests, which I like), or attempt to avoid it.

[aphillips]

Added notes.

[stasm]

Ah, I think I understand why we you included this constraint; sorry I missed this earlier. We're effectively saying here that we can't get rid of the : in front of the annotation, even if it's namespaced.

Sounds like something worth documenting in #478.

[stasm]

What's the purpose of the 8 character limit?

[aphillips]

brevity. I meant to include something about the limit, but we should probably make it unlimited.

[aphillips]

Removed limit and changed wording.

[stasm]

All of these requirements combined mean that developer are in control of choosing the namespace name. I think that's by design and desirable, but we should address in the doc the negative impact this can have on portability of messages.

[eemeli]

Do I understand right that with this approach, an implementation could choose to use pretty much any pattern for establishing namespacing, and have it internally work the same as the proposed ns:func?

I'm not really seeing the benefit of explicitly defining a separator sigil, as opposed to providing functionality that would let a name prefix like "ns:" associate itself with a URL defining its functionality.

[stasm]

I think this means that if implementations want to go beyond std:, they need to allow users to namespace addons. The pattern for doing so is ns:func, and that wouldn't change.

[stasm]

I've been thinking about these 3 use-cases, and I think there's a portability risk that we should call out.

I see two groups of users who could be in charge of controlling the namespace name:

• (a) Authors of custom functions bundled in "packages"; this is similar to how C/C++ or Java handle naming.
• (b) Developers who import those packages into their MFv2 implementation of choice; this is in line with how modern languages handle imports and namespaces, via some sort of import ... as mechanism.

The current solution proposed by this PR is to go with (b), and allow developers to adjust the namespace if necessary. The risk this brings is that these custom monikers chosen by developers are then hardcoded inside messages, hurting the portability of messages.

Example: If I choose myFoo as a namespace, this naming choice propagates down to all messages (myFoo:number etc.). These messages then require edits when they're migrated to another project, when codebases merge, or even when I change my mind and rename the namespace to myBar.

We can attempt to avoid or mitigate this risk (or accept it).

• Avoid: Go with (a), i.e. authors choose and control the namespace name. Since this is still likely to produce conflicts, a naming scheme similar to Java's fully qualified names would be recommended. Unfortunately, it means that namespaced names become domain.name.like long.

• Mitigate: Go with (b), i.e. developers importing packages can give them custom names. Embrace the fact that those custom names are then hardcoded in mesasges and make it easy for tooling to work with them and modify them.

[aphillips]

I agree with this callout. The challenge with (a) is that then you need a fairly sizeable namespace that can be made unique by function authors, e.g. it suggests reverse domain naming.

There is a third path, which is basically (b) plus a registry (think: media types). I am not wild about creating a registry, but that would help with the portability and toe-stepping problem (while allowing users to control the prefix for their own space).

Since there is no library ecosystem currently, we can also create the mechanism but not flesh it out for 2.0. That is, we can reserve the syntax but come back later to define its usage. In some ways that's like @eemeli's proposal (it's just a convention), except that it is formally reserved (if you name a function with an interior :, it might not work later)

[catamorphism]

I think this paragraph should come immediately after the heading. As it is, the first sentence after _What is this proposal trying to achieve?_ doesn't answer the question.

[aphillips]

Good point. Moved to start and slightly reworded for context.

[catamorphism]

So can the example use icu:datetime instead?

[aphillips]

Good callout. I made a different change: I made this example use a built-in option and then did icu:skeleton for options after.

[aphillips]

We agreed to merge this today (2023-11-06) as proposed, but asking for one more review before I do that.

[stasm]

Suggested change

	# Design Proposal Template
	# Extending functions and their options

[stasm]

Or more simply:

Suggested change

	# Design Proposal Template
	# Namespacing

[aphillips]

I went with:

Design Proposal: Namespaces for Extending Functions, Options, etc.

[catamorphism]

Suggested change

	- Developers need to add options to the base functions to suit local needs.
	For example, ICU's skeletons as part of the `:datetime` function
	- Developers need to add options to the base functions to suit local needs:
	for example, ICU's skeletons as part of the `:datetime` function.