Why self host context and documentation?

I created this Github Repo + Website to demonstrate a transparent and secure way of hosting contexts and documentation, for anyone who is blocked by W3C PRs:

https://github.com/transmute-industries/context

I have added examples for linking to ReSpec and Markdown.

If you use JSON-LD (if you have a DID Document with a context field), you should make sure you don't have any broken links, and consider self hosting your context and documentation instead of ignoring broken links.

... You may not be aware of this, but when your DID Document is flattened, a data structure like this is formed:

 [
      {
        "@id": "did:elem:eURSFEEv6J7s3TJ-jhT_ZS4uGRyCDbwc347EWlqpNgw",
        "https://w3id.org/security#publicKey": [
          {
            "@id": "did:elem:eURSFEEv6J7s3TJ-jhT_ZS4uGRyCDbwc347EWlqpNgw#key-0"
          },
          {
            "@id": "did:elem:eURSFEEv6J7s3TJ-jhT_ZS4uGRyCDbwc347EWlqpNgw#key-JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw"
          }
        ]
      },
      {
        "@id": "did:elem:eURSFEEv6J7s3TJ-jhT_ZS4uGRyCDbwc347EWlqpNgw#key-0",
        "@type": [
          "https://w3id.org/security#EcdsaSecp256k1VerificationKey2019"
        ],
        "https://w3id.org/security#publicKeyHex": [
          {
            "@value": "027560af3387d375e3342a6968179ef3c6d04f5d33b2b611cf326d4708badd7770"
          }
        ]
      },
      {
        "@id": "did:elem:eURSFEEv6J7s3TJ-jhT_ZS4uGRyCDbwc347EWlqpNgw#key-JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
        "@type": [
          "https://w3id.org/security#EcdsaSecp256k1VerificationKey2019"
        ],
        "https://context.transmute.org/element/#publicKeyJwk": [
          {
            "@id": "_:b0"
          }
        ]
      }
    ]

If you don't add a context that knows about your key types, you will end up with:

[
        {
          "@id": "did:elem:eURSFEEv6J7s3TJ-jhT_ZS4uGRyCDbwc347EWlqpNgw",
          "https://w3id.org/security#publicKey": [
            {
              "@id": "did:elem:eURSFEEv6J7s3TJ-jhT_ZS4uGRyCDbwc347EWlqpNgw#key-JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw"
            }
          ]
        },
        {
          "@id": "did:elem:eURSFEEv6J7s3TJ-jhT_ZS4uGRyCDbwc347EWlqpNgw#key-JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
          "@type": [
            "/EcdsaSecp256k1VerificationKey2019"
          ]
        }
      ]

This can cause lots of problems, including missing the whole point of JSON-LD, which is to provide links to documentation around the property values, such as:

https://w3id.org/security#publicKey

So while its easy to add properties to a DID Document (its json after all), doing so without defining them can cause issues for interoperability, and its also not sufficient to just create a new context, because the properties defined in the context need to be documented.

For this reason, I recommend self hosting the context and documentation, while waiting for approval from W3C.

transmute-industries / context

Why self host context and documentation? #1