Define resolution function with data types, property values, and full metadata structures #299
Conversation
…ructure properties.
| Any transformations MUST be bidirectional and lossless. | ||
| Implementations MUST NOT expose these transformations to callers of the <a>DID resolution</a> function and | ||
| MUST NOT require callers of the <a>DID resolution</a> function to know about the transformations in order to call the function. | ||
| For example, an implementation could prepend the string <code>DID-Document-</code> to the names of all <a href="did-document-metadata-properties"></a> |
There was a problem hiding this comment.
I'm having trouble groking this section, and wording like:
"MUST NOT require callers of the DID resolution function to know about the transformations in order to call the function."
I feel like this language is not necessary, so long as the response interface is defined... callers are required to understand the interface... right?
As a DID Method author, I define support for JSON / CBOR / JSON-LD... resolve returns a representation (singular)... we believe that the representation can be transformed in a lossless bi-directional manner if we believe that the contract interface and registry are all that is needed to support that....This feels like we are now saying that DID Method implementers are responsible for ensuring that resolve supports all 3... instead of relying on the registry and the WG to make that transparent.... using post resolution middleware... in other words, all DID Methods are now required to produce all representations?...
I guess what I am trying to say is: "Any transformations MUST be bidirectional and lossless. "... I would like to see a proof that its possible for at least JSON /JSON-LD/CBOR, before I see normative text saying its a requirement... I'm not sure I believe its possible.... and if its not, then we will end with 3 non interoperable DID Representations... Yikes!
There was a problem hiding this comment.
So this is the metadata, not the document itself. The metadata is not in JSON/CBOR/etc. The metadata is a map of strings: so a Javascript hash object, a python dict, a java Map<String, String>, etc.
The transformation in question here is to and from that data structure into whatever underlying format there needs to be. That's one of the reasons that I think it's important for the metadata structure to be a LIMITED data structure in terms of Map[String -> String] and not objects, arrays, numbers, or anything else. This is representable in any possible underlying system in a deterministic way.
The reversible transforms basically just means that if your protocol needs to use "DID-Resolution-Content-Type" to represent a field, you can't have someone call you with "DID-Resolution-Content-Type", you have to let them call you with "content-type", and you need to return "content-type" in the resulting map. This needs to be a strict requirement, but I'm struggling how to make it normatively enforceable. Thus the "MUST NOT expose" language above as an attempt to get to that.
I think a number of people are getting lost on this point, especially that the metadata is intended to be completely independent of the underlying representation. Is there a way to rephrase this to make it more clear what's going on here?
There was a problem hiding this comment.
This sections feels to me like it's delving a little bit too deep into the internals of the resolve function. It seems out of scope of did-core.
if your protocol needs to use "DID-Resolution-Content-Type" to represent a field, you can't have someone call you with "DID-Resolution-Content-Type", you have to let them call you with "content-type", and you need to return "content-type" in the resulting map.
Understood. However, I still question its pertinence to did-core. This belongs in a transport-specific did-resolution spec.
There was a problem hiding this comment.
I can see how it can be read that way, but that's not the intent. The intent isn't to describe how any mapping can happen, but instead put limits on what a mapping can do. The real requirement here is that if a property is named foo-bar, then I should be able to call this function with a property named foo-bar and get the expected behavior (defined by the property) regardless of how the implementation represents foo-bar under the hood. I'll put in an alternative phrasing for this requirement that might capture it better.
| Any transformations MUST be bidirectional and lossless. | ||
| Implementations MUST NOT expose these transformations to callers of the <a>DID resolution</a> function and | ||
| MUST NOT require callers of the <a>DID resolution</a> function to know about the transformations in order to call the function. |
There was a problem hiding this comment.
| Any transformations MUST be bidirectional and lossless. | |
| Implementations MUST NOT expose these transformations to callers of the <a>DID resolution</a> function and | |
| MUST NOT require callers of the <a>DID resolution</a> function to know about the transformations in order to call the function. | |
| Implementations MUST accept metadata properties by their registered names as inputs and MUST produce metadata properties by their registered names as outputs, regardless of any internal transformation that could occur within the implementation. |
|
Since there were a lot of comments on the transformation section but not the requirements section, I've made another pull request that includes the requirements but not the transformation language in case that's a better place to make the cut: #300 |
|
|
||
| <p><code> | ||
| resolve ( did, did-resolution-input-metadata ) <br> | ||
| -> ( did-resolution-metadata, did-document-stream, did-document-metadata ) |
There was a problem hiding this comment.
What format is the did-resolution-metadata argument? (I assume the did-document-stream is in the format that the metadata specifies.)
There was a problem hiding this comment.
The did-resolution-metadata is a map of strings. It's not in any particular serialized format as it's not expected to be parsed outside of this function, just read/used. This could be a javascript hash, a python dict, or a java Map<String, String>, or any number of other hash-table-style data structures that can store strings under unique string keys. The goal was to be a simple enough data structure that we wouldn't need to agree on a serialization format -- that's why it doesn't allow arrays, objects, numbers, or other things that would need serialization/parsing rules.
There was a problem hiding this comment.
That would be fine with me. I would suggest doing that kind of work as a separate pull request as it's more editorial at that point.
There was a problem hiding this comment.
Do we want to make mention of where metadata properties will be defined? I'm thinking we may want to follow the registry pattern for this, but I could easily be talked out of this because I don't hold this position too strongly.
Missed the section that does this. Approved.
| Property names MUST be unique within a given set. | ||
| Each property name MUST map unambiguously to a single value within the set. | ||
| Property names MUST be compared by the exact byte value. | ||
| The value of a property MUST be a single string. |
There was a problem hiding this comment.
Properties must be able to be any JSON type - including arrays, booleans, objects, and yes strings.
OAuth metadata contains all of these. There's no reason to believe that DID metadata won't.
|
I feel like this PR has been superseded by #331 and #347. I think we should close this. If there is anything in this PR that we want to get into the spec (e.g. language around lossless transformation of metadata in underlying protocols), then this can still be added on top of the current spec in a separate PR. @jricher do you agree? |
|
Closing this in 48 hours if we don't hear back from the PR author. |
|
No response from original PR author, closing. |
This adapts the DID Resolution functional definition defined by #253 into a single typed function with requirements for the function signature and implementation conformance. Property values for input and output metadata structures are defined here, with pointers to the DID registry for management of properties. Requirements for when and how to return each value are also added.
Simple metadata structures are defined here, including requirements for conformance, transformation, and transmission.
This builds on #295, #296, #297, #298, and #300.
Preview | Diff