Representation type

[clehner]

When a DID is resolved to a DID document using the abstract resolveRepresentation function, the resolution result is supposed to include DID Resolution Metadata that includes a contentType for the Media Type of the representation used in the didDocumentStream part of the result.

resolveRepresentation could be implemented for did:web by passing through the HTTP response body as didDocumentStream. But what should the resolution metadata contentType be set to?

In other words, is a did:web DID document expected to be in JSON-LD representation, or in JSON representation?

The specific extension ".json" used in did:web suggests JSON, but in the Create (Register) operation, the DID document is referred to as a JSON-LD file. There is also an (obsolete?) section with a JSON-LD context definition.

Should the HTTP response Content-Type header be used to determine the representation contentType? I think this would be consistent with DID document production/consumption rules:

A conforming producer MUST return the Media Type string associated with the representation after the production process completes.

A conforming consumer MUST determine the representation of a DID document using the Media Type input string.

This would mean however that .json files hosted statically with default settings would be considered JSON rather than JSON-LD. So e.g. JSON-LD did:web DID documents on GitHub Pages would not work.

Or should did:web specify that its DID documents should always be considered one representation or the other?

The difference in representation is relevant as the JSON-LD representation is stricter, for example, its production rules require a specific initial value in the @context property. Strict checking of that property, along with an assumption of JSON-LD representation, caused a problem with one did:web implementation and application: haxxnz/nzcp-rust#1 spruceid/ssi#345. There are also semantic and security reasons why the distinction in representation is important.

There is also some discussion about did:web DID documents having multiple representations: #15, #20 (comment)

[gribneau]

This is important, and the JSON vs. JSON-LD issue has been raised before in the context of the file extension in #8.

My personal opinion is that preserving the simplicity of plain JSON is important for ease of adoption, but that JSON-LD will be preferable for a number of use cases. I don't think we muddy the waters too much by supporting both and requiring appropriate filename extensions (.json, .jsonld) and mime types (application/json, application/ld+json).

[gribneau]

This issue is further complicated by the IANA Considerations section of the core spec.

To get into compliance with that language, we would need the following file extensions and mime types:

.didjson
application/did+json

.didjsonld
application/did+ld+json

This would make our very, very simple file naming scheme ( did.json ) oddly cumbersome ( did.didjson, did.didjsonld ).

We might want to consider an update, as supporting multiple file extensions will necessarily involve updating the resolver at the same time anyway.