[RFC] Add note recommending directive names to be namespaced

[tinnou]

As discussed in the 2012-12-05 working group meeting, this informal RFC proposes adding a non-normative note recommending directive names to be namespaced to prevent name collisions when the specification adds new directives.

Motivation / Context

The Custom Scalar Specification URIs RFC was discussed during multiple working group meetings and the potential winning approach involves defining a new standard directive named @specified. Existing GraphQL schemas that already defined this directive would now break as directive names must be unique. To prevent this inconvenience, it was proposed we add an explicit note to the specification recommending schema designers to prefix/namespace directive names to prevent name collisions when upgrading their GraphQL server.

Open Questions

• I couldn't find any nomenclature in the specification to differentiate directives defined by the specification and directives defined by schema designers. I did "hear" terms such as "standard", "built-in" for the former, and "custom" directives for the latter. Maybe it would be a good idea to introduce such terms to make the specification text clearer. Thoughts?
• I added an example but I can remove it if it is deemed unnecessary.

[tinnou]

Implements #646

[sungam3r]

Thus, we are talking about the prefix, and not about the namespace. GraphQL has no concept of namespaces. Perhaps the term namespace is not worth mentioning at all?

[tinnou]

What other term would you use then?

I didn’t want to only use the term  « prefix » because it focuses on the how rather than what we are trying to achieve. One can use any other technique like suffixing if they prefer, to achieve « namespacing ».

[sungam3r]

I say that the term namespace should not be used, because as a rule a certain meaning is invested in it. In addition, some syntax rules are always associated with namespaces. There is nothing here. Despite the fact that someone may not like the term prefix (I don't like it either), it is described here - without clear syntax rules.

[leebyron]

Agreed, especially since there's been past discussion about adding namespaces as a first class concept to GraphQL. We didn't follow that path, but we both want to avoid confusion and make sure that in some rare case we revisit namespaces that we don't accidentally create an ambiguity here.

[eapache]

👍 from me on the intent, just some details to iron out.

I couldn't find any nomenclature in the specification to differentiate directives defined by the specification and directives defined by schema designers. I did "hear" terms such as "standard", "built-in" for the former, and "custom" directives for the latter. Maybe it would be a good idea to introduce such terms to make the specification text clearer. Thoughts?

I could be wrong, but I think the term "custom" and is well-understood in this context already?

[leebyron]

Huge thanks for getting this started and my apologies for the late review.

I'll make some editorial edits and get this merged.

[leebyron]

Agreed, especially since there's been past discussion about adding namespaces as a first class concept to GraphQL. We didn't follow that path, but we both want to avoid confusion and make sure that in some rare case we revisit namespaces that we don't accidentally create an ambiguity here.