Andrieu/did parameter guidance

[jandrieu]

Removed overly restricting guidance about when to use options verses parameters, clarifying that options override DID parameters, without erroneously suggesting that DID parameters are used only where the parameter needs to be part of a URL that references a resource with more precision than using the DID alone.

Also corrects the incorrect expectation It is expected that DID parameters are not used if the same functionality can be expressed by passing input metadata to a DID resolver as the DID URL author cannot be assumed to be the DID URL client. In fact, the DID URL author only has DID parameters when sending a DID URL to another party for any purpose, such as in a proof in a VC or on a business card.

---

Preview | Diff

[peacekeeper]

We had long discussions in the past about when DID parameters should be used and when options should be used. Maybe the current guidance is right, maybe it is wrong, but we shouldn't simply declare the current text as "erroneous" or "incorrect" and remove it, without explaining and discussing that change.

+1 to defining better which one takes precedence in cases when both are used, this is maybe not sufficiently clear in the current specification.

-1 to language in this PR which says that resolution options are interpreted by a DID URL dereferencer.

+0.5 to defining the term DID URL Author. I don't fully understand why this is needed, but could be useful I guess.

One thing this PR highlights is that we're still using the outdated term "input metadata" (old name for resolution/dereferencing options). I created a separate PR to fix this: #327

[wip-abramson]

I know I keep picking on this - sorry! Appreciate the work gone into these PRs.

I still am not sure you mean [=Resolve=] or [=Dereference=] here.

Instead of referencing terms for Resolve and Dereference, do you mean to link to the relevant sections of the spec?

[jandrieu]

Yes. They should link to what's in the spec.

[wip-abramson]

Suggested change

	<p>If [=Resolve=] or [=Dereference=] is called with a resolution option of the same name as a DID parameter in the input DID URL, the resolution option MUST override the DID parameters, when interpreted by the Resolver or Dereferencer, respectively.</p>
	<p>If [=Resolve=] or [=Dereference=] is called with a resolution option of the same name as a DID parameter in the input DID URL, the resolution option MUST override the DID parameters, when interpreted by the Resolver or Dereferencer, respectively.</p>

Suggested change

	<p>If [=Resolve=] or [=Dereference=] is called with a resolution option of the same name as a DID parameter in the input DID URL, the resolution option MUST override the DID parameters, when interpreted by the Resolver or Dereferencer, respectively.</p>
	<p>If <a href="#resolving">Resolve</a> or <a href="#derferencing">Dereference</a> is called with a resolution option of the same name as a DID parameter in the input DID URL, the resolution option MUST override the DID parameters, when interpreted by the Resolver or Dereferencer, respectively.</p>

Then this is the way to achieve that.

[wip-abramson]

Separately, reading this again what you are saying is that if a DID URL like:

did:example:12345?versionId=55

Is dereferenced along with resolutionOptions that define versionId as 1, then the DID returned MUST be the version 1 DID.

I guess that makes sense, as it is the caller who defines the resolutionOptions. So they know that are explicitly stating they want back v1 regardless of the parameters in the DID URL.