Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 42 additions & 2 deletions docs/_static/vcr/vcr_v2.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,25 @@ paths:
operationId: "searchVCs"
requestBody:
required: true
description: >
description: |
Searching for VCs is done by passing a JSON-LD document as query.
Each field in the request body must be present in the VC in order for it to be passed as result.
Different JSON-LD contexts can be used allowing for different JSON formats. Consult the node documentation on the supported contexts.
The type of the credential must contain "VerifiableCredential" and the additional Nuts credential type that matches the credentialSubject context.

The node does not search on `@context` and `type`.
So a query with only these two returns all credentials.
To find specific credentials, add fields the credential must have, e.g. `credentialSubject.organization.name`.

Matching rules:
- by default a value must match exactly.
- `"*"` matches any credential in which the field is present (non-empty).
- a value ending with `*` matches values that start with the given string, e.g. `Hospital Amst*`.
- `*` anywhere else in a value is matched as-is.
- wildcards only work on strings.
- the query can contain only one `credentialSubject`.

By default only credentials of trusted issuers are returned, see `searchOptions`.
content:
application/json:
schema:
Expand Down Expand Up @@ -127,11 +141,37 @@ paths:
$ref: '#/components/schemas/IssueVCRequest'
responses:
"200":
description: "New VC has been created successfully. Returns the Verifiable Credential."
description: |
New VC has been created successfully. Returns the Verifiable Credential.
For `ldp_vc` credentials the node adds the `id`, `issuanceDate` and `proof`.
content:
application/json:
schema:
$ref: '#/components/schemas/VerifiableCredential'
examples:
"did:nuts (ldp_vc)":
value:
{
"@context": ["https://www.w3.org/2018/credentials/v1", "https://nuts.nl/credentials/v1"],
"id": "did:nuts:B8PUHs2AUHbFF1xLLK4eZjgErEcMXHxs68FteY7NDtCY#a1d8ee3f-f404-44d5-bd07-71d3b144ce54",
"type": ["NutsOrganizationCredential", "VerifiableCredential"],
"issuer": "did:nuts:B8PUHs2AUHbFF1xLLK4eZjgErEcMXHxs68FteY7NDtCY",
"issuanceDate": "2021-03-05T09:37:05.732811+01:00",
"credentialSubject": {
"id": "did:nuts:9UKf9F9sRtiq4gR3bxfGQAeARtJeU8jvPqfWJcFP6ziN",
"organization": {
"name": "Zorggroep de Nootjes",
"city": "Amandelmere"
}
},
"proof": {
"type": "JsonWebSignature2020",
"created": "2021-03-05T09:37:05.732811+01:00",
"proofPurpose": "assertionMethod",
"verificationMethod": "did:nuts:B8PUHs2AUHbFF1xLLK4eZjgErEcMXHxs68FteY7NDtCY#gSEtbS2dOsS9PSrV13RwaZHz3Ps6OTI14GvLx8dPqgQ",
"jws": "eyJhbGciOiJFUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..s6lxJa7pOpqlhcWhJoKRMJIJiD4i+IUkfmhy+rUvNzZayVHAq+lZaFxBsv9rQCe0ewpZq/6z3hSUOURo6mnHhg=="
}
}
"400":
description: &issueVC400 One or more of the given parameters are invalid
content:
Expand Down
5 changes: 4 additions & 1 deletion docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@
Nuts documentation
##################

This documentation is for deploying and operating the Nuts node.
How to implement a use case with Nuts v5 (Nuts spec v1, ``did:nuts``) and integrate the Nuts node with your EHR is on the wiki: `Implementing a Nuts spec v1 use case <https://wiki.nuts.nl/link/185>`_.
Background information is on the `Nuts wiki <https://wiki.nuts.nl>`_.

.. toctree::
:maxdepth: 1
:caption: Getting Started:
Expand All @@ -18,7 +22,6 @@ Nuts documentation

pages/integrating/api.rst
pages/integrating/api-authentication.rst
pages/integrating/vc.rst
pages/integrating/faq-errors.rst
pages/release_notes.rst
pages/roadmap.rst
Expand Down
15 changes: 14 additions & 1 deletion docs/pages/deployment/verifiable-credentials.rst
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,19 @@ Or it can fetch the context definition from disk, using a mapping from url to pa

The default contexts can be accessed using the embedded file system `assets/contexts`. The contents of this directory can be found on Github: The default loaded contexts can be downloaded from the `Github repo <https://github.com/nuts-foundation/nuts-node/tree/master/vcr/assets/assets/contexts>`_.

The node uses JSON-LD contexts to normalize a credential when it creates or verifies its proof, and to search credentials (``POST /internal/vcr/v2/search``).
So the node must know every context a credential uses; otherwise it can't verify or search it.
Context URLs are identifiers: they don't have to resolve, as long as the node has a local mapping for them.

Built-in contexts (mapped to local files by default, see ``jsonld.contexts.localmapping``):

- ``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://schema.org``
- ``https://nuts.nl/credentials/v1``: Nuts credentials such as ``NutsOrganizationCredential`` and ``NutsAuthorizationCredential``

Background on JSON-LD in Nuts is on the `wiki <https://wiki.nuts.nl/link/196>`_.

Example configuration
^^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -91,7 +104,7 @@ Local mappings can be used to pin a version of a context, so no unseen changes c
Searching and indexing
^^^^^^^^^^^^^^^^^^^^^^

Searching for custom credentials works just as Nuts provided credentials as described in :ref:`searching-vcs`. Note however that the extra fields in the `credentialSubject` added by the custom credential are not indexed by the credential store. Searching for these fields is notably slower (depending on the query and amount of custom credentials). If this becomes a problem, inform the Nuts development team so an appropriate solution can be found.
Searching for custom credentials works just as Nuts provided credentials as described on the `wiki <https://wiki.nuts.nl/link/198>`_. Note however that the extra fields in the `credentialSubject` added by the custom credential are not indexed by the credential store. Searching for these fields is notably slower (depending on the query and amount of custom credentials). If this becomes a problem, inform the Nuts development team so an appropriate solution can be found.

Resources
^^^^^^^^^
Expand Down
17 changes: 3 additions & 14 deletions docs/pages/getting-started/3-configure-your-node.rst
Original file line number Diff line number Diff line change
Expand Up @@ -184,18 +184,7 @@ It will tell you:

You're now set up to exchange data with other nodes.

Care Organizations
******************
Next steps
**********

The DID documents of your care organizations you (as a vendor) want to expose on the Nuts network need to be associated
with your node DID document (a.k.a. vendor DID) through the ``NutsComm`` endpoint.
Its recommended to register the actual ``NutsComm`` endpoint on your vendor DID document (as explained in the previous section),
and register a reference to this endpoint on the DID documents of your vendor's care organizations:

.. code-block:: text

POST <internal-node-address>/internal/didman/v1/did/<care-organization-did>/endpoint
{
"type": "NutsComm",
"endpoint": "<vendor-did>/serviceEndpoint?type=NutsComm"
}
To set up DIDs for your care organizations and implement a use case, see `Implementing a Nuts spec v1 use case <https://wiki.nuts.nl/link/185>`_ on the wiki.
Loading
Loading