# JSON-LD

[JSON-LD (JSON Linked Data)](https://json-ld.org/) is JSON with a `@context`: a list of contexts, named by URL, that define what each field and type means. Verifiable Credentials can be written in JSON-LD.

## Why it matters for credentials

Credentials come in two formats:

| | JSON-LD (`ldp_vc`) | JWT (`jwt_vc`) |
|---|---|---|
| Signature covers | The credential after JSON-LD processing | The JWT itself |
| Every field must be defined in a context | Yes | No |
| Issuer and verifier need the contexts | Yes, the same ones | No |

For a JSON-LD credential, the signature is made over a normalized form of the credential. To make that form, the node expands every field using the contexts. A field or type that no context defines makes issuing or verifying fail.

Example: a HealthcareProviderRoleTypeCredential has the field `roleCodeNL`, which no JSON-LD context defines. Issuing it as `ldp_vc` fails; issuing it as `jwt_vc` works.

For new use cases, JWT credentials are simpler: no contexts to publish, agree on and configure.

## Contexts in the Nuts node

A context URL is an identifier: a credential names it in `@context`, but it doesn't have to resolve. The Nuts node maps each URL to a copy it includes, so it never fetches these:

| Context URL | Defines |
|---|---|
| `https://www.w3.org/2018/credentials/v1` | W3C Verifiable Credentials |
| `https://w3c-ccg.github.io/lds-jws2020/contexts/lds-jws2020-v1.json` | JsonWebSignature2020 proofs |
| `https://w3id.org/vc/status-list/2021/v1` | StatusList2021 revocation |
| `https://schema.org` | schema.org terms |
| `https://nuts.nl/credentials/v1` | NutsOrganizationCredential, NutsEmployeeCredential, NutsAuthorizationCredential, DiscoveryRegistrationCredential, NutsSelfSignedPresentation, CredentialRevocation |
| `https://nuts.nl/credentials/2024` | NutsUraCredential |

A use case with its own JSON-LD credential types publishes its own context. Every node in the use case must then be configured with it: either map the context URL to a local file, or allow the node to fetch it from that URL. See [Custom credential configuration](https://nuts-node.readthedocs.io/en/latest/pages/deployment/verifiable-credentials.html) in the Nuts node documentation.