Add IANA Considerations section. Fix #1.

[msporny]

This section adds an IANA considerations section, which we need to do in time... but it's being added so we can establish MIME Types for DID Documents, which then describe how fragment identifiers should be interpreted by pointing to the Fragment section in the spec. Doing so will address issue #1.

---

Preview | Diff

[iherman]

I wonder about the fragment definition; there may be several issues.

1. For both media types, the reference is to the DID Core spec section. That section says:

   A generic DID fragment is identical to a URI fragment and MUST conform to the fragment ABNF rule in [RFC3986]. Implementers are strongly discouraged from using a DID fragment for anything other than a method-independent reference into the DID document to identify a component of a DID document (for example, a unique public key description or service endpoint).

   I am afraid that language is not 'normative' enough. It should say something like "The fragment is used to specify this and this and that" whereas the current text begins by saying what implementers are supposed not to do. I do not think that is o.k.

2. The did+ld+json case raised further questions. The relevant section of the JSON-LD 1.1 spec provides a clear definition of the semantics of fragments, referring to its RDF usage. I am not sure it is good practice (although probably doable by the rules) to redefine the fragments for a subtype. If the current definition is not a redefinition (my gut feeling is that it is not, but we should be sure of that!) then this fact should be somehow clearly stated and explained in the IANA consideration section. Ideally, the did+ld+json section shouldn't even have a reference to fragments, just let the definition of the higher-level media type kick in...

[msporny]

@iherman wrote:

It should say something like "The fragment is used to specify this and this and that" whereas the current text begins by saying what implementers are supposed not to do. I do not think that is o.k.

Ok, I'll try refactoring some of that text to be more explicit based on how some other specs have defined fragment identifiers for their media type.

@iherman wrote:

Ideally, the did+ld+json section shouldn't even have a reference to fragments, just let the definition of the higher-level media type kick in.

I considered doing the following:

1. Just referring to JSON-LD's definition of fragment identifiers, but I predict that the JSON-only people will object to doing that.
2. Having the JSON-only media type point to the fragments section in the DID Core spec and then the JSON-LD media type point to the JSON-LD spec, but I expect people will complain that the two fragment mechanisms could be different.
3. This is what I chose, have both media types point to the fragment identifiers section in the DID Core specification, and then add some text in that section that notes that for JSON-LD media types, that the intent is that the DID Core fragments section is intended to have the same semantics, and then state that "in addition to these normative statements, JSON-LD documents have additional implications for the fragment identifier that are compatible with this section, but important to know for JSON-LD developers"... or something like that.

Would you like to see item 3 above expressed more explicitly in the PR?

[iherman]

> Ideally, the did+ld+json section shouldn't even have a reference to fragments, just let the definition of the higher-level media type kick in. I considered doing the following: 1. Just referring to JSON-LD's definition of fragment identifiers, but I predict that the JSON-only people will object to doing that. 2. Having the JSON-only media type point to the fragments section in the DID Core spec and then the JSON-LD media type point to the JSON-LD spec, but I expect people will complain that the two fragment mechanisms could be different. 3. This is what I chose, have both media types point to the fragment identifiers section in the DID Core specification, and then add some text in that section that notes that for JSON-LD media types, that the intent is that the DID Core fragments section is intended to have the same semantics, and then state that "in addition to these normative statements, JSON-LD documents have additional implications for the fragment identifier that are compatible with this section, but important to know for JSON-LD developers"... or something like that. Would you like to see item 3 above expressed more explicitly in the PR?

Yes. And do not say ’the intent is that the DID Core fragments …’ but make it clear that the two are identical, plus some inherited semantics that are relevant for JSON-LD geeks only. I should sound unambiguous (We should not forget that this part is reviewed by IANA reviewers!) Thanks

[msporny]

@iherman wrote:

It should sound unambiguous.

Ok, I have applied your suggestions.

Let me know if you'd like further changes... and if so, via a PR (as I did my best to look at how HTML5, RDF, JSON-LD, and the Generic URI spec does this and attempted to channel the best of each of those specs). I don't know how to improve it beyond what I've done (and keep most of the stuff that others wanted to keep in that section in place).

Normative, multiple reviews, changes made, no objections. Merging.