SPICE Metadata Discovery

3.1. The layering problem

Effective standards limit optionality, improve interoperability, and connect bounded contexts, [BoundedContexts] through interfaces that require trivial to acquire and well understood tooling.¶

With respect to structured identifiers and content types, the simplest solutions select a single identifier type, and a single content type.¶

For example, a hypothetical AcmeHyperProtocol might rely only on URLs and JSON.¶

Support for AcmeHyperProtocol would be easy, developers would need only to have reliable libraries for working with URLs and JSON.¶

Software does not evolve this way.¶

It is common to see dependencies that solve several seperate problems efficiently, bundled together, such that it is impossible to take a dependency on just the part that is needed.¶

This problem is then reflected in standards, because effective standards describe effective software systems.¶

In OpenID Connect, we see URLs, but we also see URNs; we see application/json, but we also see application/jwt nested inside of it.¶

In DIDs and VCs, we see URLs, but we also see DIDs (URNs); we see application/json, but we also see application/ld+json nested inside of it, even further, we see application/n-quads constraining what application/json can express through the use of application/ld+json. We see URLs contraining what DIDs can express, through reuse of the path, query and fragment. We see a desire to wrap easily understood content types such as application/jwk+json or application/jwt in less easy to understand JSON-LD content types. Where does this nesting come from?¶

[RFC9518] explains in Section 4.7: "standards efforts should focus on providing concrete utility to the majority of their users as published, rather than being a "framework" where interoperability is not immediately available. Internet functions should not make every aspect of their operation extensible; boundaries between modules should be designed in a way that allows evolution, while still offering meaningful functionality."¶

In order to enable consumers leverage their prefered identifiers and content types, some specifications take a "big tent" approach, created an open ended extensibility mechansism, and then providing a single mandatory to implement instantiation of it. In the worst cases, [DIDsFO], standards insist on providing the estensiblity mechanisms, and refuse to provide mandatory to implement instances, and through doing so, ensure no interoperability is achievable without a second document, enabling a profile that is actually usable. It could be argued that OAuth has similar deficiencies, and that OpenID Connect solved this same problem through a suite of secondary documents.¶

It might seem impossible to support extensibility and interoperability simultaneously, but as the authors on [RFC9518] and Martin Fowler in [BoundedContexts] points out, the key to succeeding is ensuring the layering is correct.¶

5.1. Compound Identifiers

Compound identifiers are commonly used to address the challend of expressing relations between distinct identifiers.¶

In URLS for http resources, depending on the content type, the compount identifier https://issuer.example/capabilities#f81d4fae-7dec-11d0-a765-00a0c91e6bf6 might express that "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" is a sub resource of "https://issuer.example/capabilities" which is a sub resource of "https://issuer.example".¶

When constructing compoind identifiers, it is important to consider how negotiation is impacted by leveraging different parts of a structured identifier.¶

For example, a server can assist with negotiation for response types for https://issuer.example/capabilities, but sub resources identified by a fragment have their response type controlled by their parent resource.¶

5.2. Global Uniqueness

Global uniqueness is a deseriable property of structed identifiers.¶

Ensuring global uniquess often tends towards centralization or federation, because some system or entity must ensure that distinct identities are not able to contest, or claim a single unique identifier.¶

One way to achieve global uniqueness is to produce a compound identifier where the authority or structure of the identifier establishes the uniquenss through relation to itself.¶

For example https://issuer.example/f81d4fae-7dec-11d0-a765-00a0c91e6bf6 relies on the authority https://issuer.example to maintain the linkage between resource identifier and resource representations.¶

Another example https://issuer.example/urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 uses a URN namespace to establish a globally unique identifier urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 and then uses https://issuer.example to establish a compound identifier which is globally unique.¶

5.3. Sharing Structured Identifiers

Some systems might wish to share structured identifiers, while maintaining authority for representations.¶

For example https://issuer.example/urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 and https://verifier.example/urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 might both use urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 to express a globally unique identifier for an attribute key or attribute value.¶

When independent entities share globally unique identifiers, they are responsible for ensuring that the identifier is used consistently.¶

For example:¶

https://resolver1.example/identifiers/did:example:123 could serve completely different JSON-LD for did:example:123 than https://resolver2.example/identifiers/did:example:123.¶

Because unlike URLs, URNs are not resolvable by themselves, trust in resources represented with URNs comes from the system you are communicating with, and unlike URLs, there is no commonly understood scheme for communiation, such as http encoded in the identifier.¶

6.1. Structured Suffixes

[RFC7071] defined a JSON based media type for expressing reputation, application/reputon+json.¶

The +json part is a structured suffix as described in [RFC6839].¶

Defining a new media type with a structured suffix, allows for systems that support content type negotiation to respond with more precise content types.¶

This property of responding with less ambigious content types is part of secure system design, and [RFC8725] notes that using more specific types can help protect against certain attacks.¶

Using a more specific content type comes at the cost of being "generally understood", for example application/json is often expected or hard coded in software, and returning application/reputon+json could cause software to fail higher up in the application stack.¶

6.2. Allowing Additional Properties

It is common for content types to rely on map or object datastructures for their top level serializations.¶

This is because a MAP is easily extended with new key value pairs, which when not understood can be ignored, whereas a string or array, might cause processing errors if extended.¶

application/jwk-set+json builds on application/json and expresses a set of cryptographic keys represented by values, that are consistent with application/jwk+json.¶

In cases where additional properties can be present, implementations should take advantage of this and avoid creating new media types, until the number of new properties is substantial enough to justify ensuring security and processing considerations specific to the new type cause faults.¶

For example, consider the following URL and resource expressing "keys that are use to make attribute assertions about a subject".¶

Request:¶

NOTE: '\' line wrapping per RFC 8792

GET /keys/assertion HTTP/1.1
Host: issuer.example
Accept: \
  application/jwk-set+json

Response:¶

NOTE: '\' line wrapping per RFC 8792

HTTP/1.1 200 Ok
Content-Type: \
  application/json

{
  "keys": [
    {
      "kid": "urn:ietf:params:oauth:jwk-thumbprint:sha-256:NzbLsXh8...sRGC9Xs"
      "kty": "EC",
      "crv": "P-256",
      "alg": "ES256",
      "x": "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
      "y": "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"
    }
  ]
}

The keys property is part of application/jwk-set+json, and additional properties can be added at this layer, without creating a new media type, however, those properties will not be well understood in the context of application/jwk-set+json.¶

Similarly inside each key the alg property is optional, but when present it signals the algorithm the key is restricted to be used with.¶

Additional properties might be added to the keys themselves, however, those properties will not be well understood in the context of application/jwk+json.¶