# Docs - Learn
## Decentralized Identifiers (DIDs)
*5 minute read*

Alice and Bob want to participate in the decentralized web. We're going to learn about how Alice and Bob do that using Web5 and the concepts that make up the Web5 ecosystem.

### What are DIDs?
#### DID TL;DR

Alice and Bob decide to get DIDs so they can participate in the decentralized internet.

They need DIDs so that others can easily find them on the decentralized web. This is just like how someone would find a website by typing a URL into a web browser, or a person by searching for their handle on a social media platform. Once they find Alice or Bob through their DIDs, they can do things like save them to their contact list, or message them through decentralized channels.

#### Let's learn more

A [Decentralized Identifier (DID)](https://www.w3.org/TR/did-core/) is an address representing who you are on the decentralized web. It can point to a person, organization, thing, data model, or abstract entity. It's through your DID that others can send messages and data, and be granted access to information you wish to share.

A DID is a "type of identifier that enables verifiable, decentralized digital identity" ([DID Core Spec](https://www.w3.org/TR/did-core/)). It is created and managed independently of any centralized authority or organization. The basic idea behind a DID is to give individuals and organizations control over their own identity information and to allow them to share that information selectively and securely with others as needed. This means that they can choose when and how to share their identity information, and with whom.

DIDs are typically represented as a unique resource identifier (URI) and are designed to be used for identity verification, authentication, and authorization.

*Example of a Decentralized Identifier, from [W3C DID Core Specification](https://www.w3.org/TR/did-core/#a-simple-example)*

The key difference between a traditional centralized identifier, such as a username or email address, and a decentralized identifier is that the latter is not tied to a specific service provider or organization. An example of a centralized identifier you might have would be your Twitter handle or Google email address, where Twitter or Google are the centralized authority.

#### Why we need it?
We need an identifier that isn't tied to a centralized authority, that we can take anywhere with us, and that can be used to identify us across any platform.
### Methods
Now that Alice and Bob know that they need a DID lets take a look at the different kinds of DIDs they can have.

There are lots of different implementations of DIDs (called [DID methods](https://www.w3.org/TR/did-core/#methods)) with different use cases. Web5 currently supports a few methods.

#### did:key
A [did:key](https://w3c-ccg.github.io/did-method-key/) is free and fast to spin up. Since it can be created, but not updated or deleted, it is useful for single, ephemeral interactions.

#### did:web
[did:web](https://w3c-ccg.github.io/did-method-web/) is somewhat centralized because you need a website to have one. You host your DID Document at a specified location in your website. Here's an example of [TBD's did:web](https://www.tbd.website/.well-known/did.json).

It supports the ability to create, read, update, and deactivate a DID.

#### did:ion
[did:ion](https://identity.foundation/sidetree/spec/) is an implementation of the [sidetree](https://identity.foundation/sidetree/spec/) protocol, which logs DID actions on any decentralized anchoring system, like a blockchain or other distributed ledger. In particular, did:ion anchors actions on the Bitcoin blockchain.

did:ion is a very robust, very decentralized platform for anchoring your DIDs. It supports the ability to create, update, recover, and deactivate a DID.

### DID Documents
Now that Alice and Bob have gone through one of the methods and they have their DIDs, they now need a DID document to store those DIDs. Lets learn about DID documents, what they are and what fields we might see in them.
#### What is it?
A DID Document is a small `json` object that has a field for your DID, called `id`.

{
  "@context": [
    "https://www.w3.org/ns/did/v1"
  ],
  "id": "did:example:123456789abcdefghi"
}

Every DID can be *resolved* to a corresponding DID document. A DID resolver is a mechanism that allows you to look up and retrieve the DID document associated with a particular DID.

If you type a URL into your browser, it resolves to a web page. Similarly, you can use a service to resolve a DID to a DID document. The document includes fields that help authenticate interactions with the DID.

#### What should be in it?
The only required field is the `id` field. This value is your DID. You might find many other fields in a DID Document, such as authentication material, encryption key material, and pointers to your DWN. Read more about the fields [here](https://www.w3.org/TR/did-core/#core-properties).

#### Controller - Subject relationship
*Example of a Controller Subject relationship diagram, from [W3C DID Core Spec](https://www.w3.org/TR/did-core/)*

One of the fields you might find in a DID Document is the `verificationMethod`, which is an array of objects each representing a controlling entity of the DID. The `controller` field contains controlling entity's DID.

{
  "@context": [
    "https://www.w3.org/ns/did/v1"
  ],
  "id": "did:example:123456789abcdefghi",
  "verificationMethod": [{
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "Ed25519VerificationKey2020", 
    "controller": "did:example:pqrstuvwxyz0987654321",
    "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }]
}

The easiest way to describe the controller-subject relationship is by coming back to Alice and Bob for an analogy.

Alice and Bob (controller group) have a baby. They decide to get their baby a DID. The baby is the *subject* of the DID, but may not be ready for the responsibility of managing the DID yet. Alice and Bob can use their own DID's verification methods to control their baby's DID on behalf of their baby.

### DID Key Management
Your DIDs are secured with public-private key pairs. You should not let anyone have your private key, because the key material used to secure your DID is how you prove ownership of your DID. You should find a secure way to store your private key, such as through a secured keystore.

Alice and Bob have successfully created their DIDs, while learning all about the different methods. They each have their DID documents and are ready to join in on the decentralized fun. Take a look at the next steps section to learn more.

### Next Steps:
(Link to how to make DID guide)
(Link to Decentralized Web Node learn page)

## Decentralized Web Nodes
*3 minute read*

A Decentralized Web Node is a self-sovereign data storage and message relay mechanism that entities can use to locate public or private permissioned data related to a given DID.

### Personal Data Store
A DWN is a self-sovereign personal data store. This means you can:
- **Own your data:** You decide where to host your node. You control who has access.
- **Back up your data:** Host multiple nodes in different places, keep them all synced. If one goes down, you have your back up. When it comes back up, the sync is effortless.
- **Send and receive data:** Alice controls her DWN using her DID. Bob controls his DWN with his DID. Alice can send data to Bob just by resolving his DID.

*Topology of an exchange between Decentralized Web Nodes, from [DIF Decentralized Web Node Spec](https://identity.foundation/decentralized-web-node/spec/#topology)*

### Authorization
DWNs have two mechanisms to allow others access to read, write, or delete data on you node.
- **Permissions:** Allow someone access to read, write, or delete specific data records on your node.
- **Protocols:** Install a protocol that lets you define data types and authorization for a decentralized web app.

The easiest way to understand this distinction is to think of permissions as active, explicit, and manual, whereas protocols are passive, syntactic, and contractual.

### Data Model
Data types are bound to known schemas, letting applications agree on data models. This opens the door to applications working together in ways that's been much more difficult in traditional development platform.

### Messaging
All communication is done through simple JSON objects called messages. Web5 constructs messages and helps you send them to their destination by resolving a recipient's DID and getting the address of their Decentralized Web Node. A message can install protocols, grant permissions, and read, write, query, or delete a record. For example, a message writing a record to a DWN may look like the example below.

{ // Message
  "recordId": "b65b7r8n7bewv5w6eb7r8n7t78yj7hbevsv567n8r77bv65b7e6vwvd67b6",
  "descriptor": {
    "parentId": CID(PREVIOUS_DESCRIPTOR),
    "dataCid": CID(data),
    "dateCreated": 123456789,
    "published": true,
    "encryption": "jwe",
    "interface": "Records",
    "method": "Write",
    "schema": "https://schema.org/SocialMediaPosting",
    "commitStrategy": "json-merge",
    "dataFormat": DATA_FORMAT
  }
}

See the [DWN spec](https://identity.foundation/decentralized-web-node/spec/#messages) for a detailed explanation of each field.