Added content about VCs, DIDs, JSON-LD and verification to docs' learn session

docs/learn/concepts/credentials.md

@@ -1,10 +1,8 @@
-"Verifiable Credentials," or "VCs" are standardized, cryptographically-signed documents that attest information about an entity. They provide an interoperable way to attest and authenticate any kind of data in an IDtech application. 
+**Verifiable Credentials** or **VCs** are digital certificates that are standardized and provide a secure and private way to share information online - as they can be verified without revealing any unnecessary details. A verifiable credential is a digital representation of a person's identity information that has been cryptographically signed by an issuer. They provide an interoperable way to attest and authenticate any kind of data in an IDtech application.
 
-> A verifiable credential is a set of tamper-evident claims and metadata that cryptographically prove who issued it.
-- [W3C VC Data Model](https://www.w3.org/TR/vc-data-model/)
-> 
+When someone issues you a verifiable credential, it's stored in an SSI digital wallet, making it easy for you to securely and privately show them to others. A digital wallet is a software application and encrypted database that stores credentials, keys, and other secrets necessary for self-sovereign identity.
 
-Trinsic currently uses a verifiable credential format that complies with the W3C Verifiable Credential Data Model, but we’re watching competing standards as they evolve as well (e.g. IETF ACDCs, ISO 13018-5, Anoncreds, etc). For more details on the standards we use, see [Standards](/learn/platform/standards).
+Trinsic currently uses a verifiable credential format that complies with the [W3C Verifiable Credential Data Model](https://www.w3.org/TR/vc-data-model/) (and that's why they're “standardized”), but we’re watching competing standards as they evolve as well (e.g. IETF ACDCs, ISO 13018-5, Anoncreds, etc). For more details on the standards we use, see [Standards](/learn/platform/standards).
 
 Verifiable credentials are unique from other kinds of digital documents because they enable you to verify the following things:
 
@@ -13,6 +11,24 @@ Verifiable credentials are unique from other kinds of digital documents because
 3. It hasn't been tampered with (the veracity of the data)
 4. Whether the issuer revoked the credential as of a particular point in time (the status of the data)
 
+## Trust Triangle
+
+- **Issuer:** The person/organization that creates the Verifiable Credential and gives it to another person/organization.
+- **Holder:** The person/organization that holds the verifiable credential in their digital wallet.
+- **Verifier:** The person/organization that receives and authenticates the information shared with them instantly.
+
+![Trust Triangle between Issuer, Holder and Verifier.](../../_static/images/trusttriangle.png)
+
+
+An example of an **issuer** is the government, of a **holder** is a person who receives a digital ID from the government and of a **verifier** is a security agent in the airport checking your ID.
+
+## VCs are
+
+- **Portable:** You can easily send a credential online to anyone you.
+- **Verifiable:** You can verify who's the issuer of the credential, who the credential was issued to (holder), if the information within the credential has been tampered with and whether the credential has been revoked
+- **Private:** Zero-knowledge proofs allow you to select which information you wish to share on a credential, providing greater control over your personal data.
+- **Tamperproof:** VCs can’t be altered/forged.
+
 ## Components of a credential
 
 To break down the components of a credential, we'll use a digital driver's license as an example.

docs/learn/concepts/dids.md

@@ -1,36 +1,40 @@
-Identifiers are necessary to assign to each member of an ecosystem. Identity wallets manage identifiers on behalf of the holder(s) that control(s) the wallet. At Trinsic we use “Decentralized identifiers” or “DIDs,” which are globally unique, cryptographically verifiable URIs that are not bound to a centralized registry. DIDs provide a way to separate a public identifier from public keys, which is an important requirement for resilient identity systems.
+Identifiers are necessary to assign to each member of an ecosystem. Identity wallets manage identifiers on behalf of the holder(s) that control(s) the wallet. At Trinsic we use **Decentralized identifiers** or **DIDs**, which are globally unique, cryptographically verifiable URIs that are not bound to a centralized registry. DIDs provide a way to separate a public identifier from public keys, which is an important requirement for resilient identity systems.
 
 Trinsic aims to abstract the complexities of interacting with DIDs. So while this section provides a brief explanation of DIDs, you do not need to fully grok them in order to build an identity product using Trinsic.
 
-## Working with DIDs on Trinsic
+## How DIDs work
 
-Trinsic abstracts away the complexities of working with DIDs and cryptography, allowing you to focus on building a great identity product.
+Examples of centralized identifiers include Student ID, ID number, driver's license number, username, email address, and user ID. These are considered *centralized* because they are provided by an authority, provider, or organization that gets between us and our ability to access certain services. The concept of identity being decentralized means that we become the owners of our data and access without relying on any intermediary organization or central issuing agency.
 
-When a [wallet](https://docs-v2.trinsic.id/learn/concepts/wallets) is created, Trinsic generates a cryptographic keypair and securely stores it; this keypair is what will be used to sign credentials issued by the wallet. Additionally, Trinsic generates a `did:key` DID, which encodes the public information necessary to verify credentials issued by the wallet; this is the `public_did` field of the wallet object.
+### DIDs are
+- **Decentralized**;
+- **Persistent**: They don’t require the continued operation of an underling organization, such as Gmail or the government;
+- **Cryptographically verifiable**: You can prove control of the identifier cryptographically;
+- **Resolvable**: You can discover metadata about the identifier.
 
-### Upgrading wallet DIDs
+### Structure
+An example of DID is `did:example:12345abcdefghijklm`
 
-Providers of an ecosystem may *upgrade* a wallet's DID from `did:key` to any of the supported methods via [a simple API call](https://docs-v2.trinsic.id/reference/services/provider-service/#upgrade-wallet-did). Trinsic handles the complexities of this process for you.
+`did` is the **Scheme** - all DIDs start with it
 
-Many DID methods are based on distributed ledgers (commonly known as "blockchains"), so the following should be kept in mind when registering a DID which uses a ledger:
+`example` is the **Method** - where the DID is stored (blockchain, digital wallet or anywhere else)
 
-**Data Protection & Compliance**
+`12345abcdefghijklm` is the **Identifier** - the unique identifier of the DID
 
-When writing an identifier to a public, permanent resource like a blockchain, it’s important to be extremely sure that you want that data to remain there forever. Permanence is hard to reconcile with “right to be forgotten”, and the jury is out on whether a person’s identifiers are considered personal data (literally).
+Examples of DID methods: `key` (public key is stored directly in the URI, enabling local resolution), `ion` (DID stored in the Bitcoin blockchain), `web`, `indy`.
+The goal of DIDs is to provide a decentralized, method-agnostic way to bundle an **Identifier** together with information about how to communicate and interact securely with the subject attached to said identifier. When you resolve a DID using its DID **Method** and the **Identifier**, you retrieve a **DID Document**, which contains information about how to interact with the subject (chiefly, cryptographic keys associated with the subject which can be used for verifiable communication).
 
-For these reasons, it is ************************not advisable************************ to upgrade DIDs controlled by wallets whose holders are natural persons (in other words, DIDs whose subjects are persons). If doing so is important for your use case, we strongly recommend you work with legal counsel to understand all of the implications before doing so.
+## Working with DIDs on Trinsic
 
-**Fees**
+Trinsic abstracts away the complexities of working with DIDs and cryptography, allowing you to focus on building a great identity product.
 
-Depending on the DID method chosen, registering a DID may incur a transaction fee, which is different for each ledger. **You are responsible for these fees.**
+In an IDtech product, *issuers* and *holders* will have its own DID, which will be specified in the credentials issued/held by it. It signs a cryptographic proof against the contents of the credential (using its own private key) and stores this in the `proof` field of the credential. Critically, the public key associated with the signing private key is stored in the issuer's DID Document.
 
-Documentation of these fees will be visible through our Dashboard and on our pricing page. You should keep this in mind before you programmatically upgrade DIDs through the API.
+When verifying a credential, the verifier looks at the DID in the `issuer` field and resolves it to fetch its associated **DID Document**. Then, they verify that the `proof` field is cryptographically valid and was generated using one of the keys in the DID Document. This process guarantees that the issuer claimed by the credential is indeed the entity that signed the credential and that the credential has not been modified.
 
-**Resolution**
+At Trinsic, when a [wallet](https://docs-v2.trinsic.id/learn/concepts/wallets) is created, we generate a cryptographic keypair and securely stores it; this keypair is what will be used to sign credentials issued by the wallet. Additionally, Trinsic generates a `did:key` DID, which encodes the public information necessary to verify credentials issued by the wallet; this is the `public_did` field of the wallet object.
 
-Newly-registered DIDs may not be immediately resolvable, as distributed ledgers typically cannot provide instantaneous writes.
-
-Issuance and verification of credentials against these DIDs will still function during this time, but only within the Trinsic platform.
+When using this scheme, one must only maintain a list of issuer DIDs which are trusted to issue credentials of a certain type (this might be accomplished by a [Trust Registry](https://docs-v2.trinsic.id/learn/concepts/trust-registries)); the cryptographic guarantees of DIDs and VCs take care of the rest.
 
 ### Supported DID methods
 
@@ -45,27 +49,22 @@ We plan to grow the list of supported DID methods as we move towards general ava
 | did:indy | Distributed Ledger | INDY is a Hyperledger Indy based protocol. Registering a DID will incur charges if on the main (non test) networks [IndyOptions](/reference/proto#services-provider-v1-IndyOptions)                                         |
 | did:sov  | Distributed Ledger | SOV is the Sovrin Foundation implementation of Hyperledger Indy. It is available via `did:indy:sov` prefix Under *IndyOptions* above. Registering a DID will incur charges if on the main (non test / non builder) networks |
 
-## How DIDs work
-
-DIDs serve as identifiers of subjects (most commonly individuals); a DID can be *resolved* to retrieve a *DID Document*, which contains information about how to interact with the subject (chiefly, cryptographic keys associated with the subject which can be used for verifiable communication).
-
-DIDs always start with the `did:` prefix, but can take many forms. For example, `did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK` and `did:ion:test:EiAmZrbqZvA81YBazg3h3ucL6yIYh_OTxaj_W_ggeEEOYA` are both valid DIDs, but have different prefixes. In this example, `key` and `ion` are the *DID methods* of these DIDs, respectively. Other DID Methods include `did:web` and `did:indy`.
+### Upgrading wallet DIDs
 
-The method of a DID determines how to resolve it to retrieve its associated DID Document; there is no common strategy. For example, resolving a `did:ion` DID requires interacting with the Bitcoin blockchain, whereas `did:key` encodes the DID Document information (the public keys) directly into the URI enabling local resolution.
+Providers of an ecosystem may *upgrade* a wallet's DID from `did:key` to any of the supported methods via [a simple API call](https://docs-v2.trinsic.id/reference/services/provider-service/#upgrade-wallet-did). Trinsic handles the complexities of this process for you.
 
-To sum up, the goal of DIDs is to provide a decentralized, method-agnostic way to bundle an identifier together with information about how to communicate and interact securely with the subject attached to said identifier.
+Many DID methods are based on distributed ledgers (commonly known as "blockchains"), so the following should be kept in mind when registering a DID which uses a ledger:
 
-### How DIDs are used with Verifiable Credentials
+**Data Protection & Compliance**
 
-DIDs are an important component of the Verifiable Credential spec; they enable decentralized issuance and verification of credentials.
+When writing an identifier to a public, permanent resource like a blockchain, it’s important to be extremely sure that you want that data to remain there forever. Permanence is hard to reconcile with “right to be forgotten”, and the jury is out on whether a person’s identifiers are considered personal data (literally).
 
-When someone (or something) issues a credential, they set the `issuer` field of the credential to their own DID. They then generate (or "sign") a cryptographic proof against the contents of the credential, using their own private key, and store this in the `proof` field of the credential. Critically, the public key associated with the signing private key is stored in the issuer's DID Document.
+For these reasons, it is ************************not advisable************************ to upgrade DIDs controlled by wallets whose holders are natural persons (in other words, DIDs whose subjects are persons). If doing so is important for your use case, we strongly recommend you work with legal counsel to understand all of the implications before doing so.
 
-To verify a credential, the verifier first looks at the DID contained in the `issuer` field, and resolves it to fetch its associated DID Document. Then, they verify that the `proof` field is cryptographically valid and was generated using one of the keys in the DID Document.
+**Fees**
 
-This scheme enables verifiers to guarantee the following cryptographically:
+Depending on the DID method chosen, registering a DID may incur a transaction fee, which is different for each ledger. **You are responsible for these fees.** Documentation of these fees will be visible through our Dashboard and on our pricing page. You should keep this in mind before you programmatically upgrade DIDs through the API.
 
-1. The `issuer` claimed by the credential is indeed the entity which signed the credential.
-2. The credential has not been modified or tampered with; all of its data is attested to by the issuer.
+**Resolution**
 
-Using this scheme, one must only maintain a list of issuer DIDs which are trusted to issue credentials of a certain type (this might be accomplished by a [Trust Registry](https://docs-v2.trinsic.id/learn/concepts/trust-registries)); the cryptographic guarantees of DIDs and VCs take care of the rest.
+Newly-registered DIDs may not be immediately resolvable, as distributed ledgers typically cannot provide instantaneous writes. Issuance and verification of credentials against these DIDs will still function during this time, but only within the Trinsic platform.

docs/learn/concepts/json-ld.md

@@ -0,0 +1,70 @@
+JSON-LD stands for JavaScript Object Notation for Linked Data. It’s a type of JSON format that is used to encode **linked data** using a set of standards based on the W3C's RDF (Resource Description Framework).
+
+Here’s an example of a JSON-LD file:
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Person",
+  "name": "Jane Doe",
+  "jobTitle": "Developer",
+  "telephone": "(425) 123-4567",
+  "url": "<http://www.janedoe.com>"
+}
+```
+
+In JSON-LD, a vocabulary is a set of terms that define the meaning of JSON-LD data. The vocabulary is defined in a JSON-LD context, which is a JSON object that maps terms to their corresponding IRIs (Internationalized Resource Identifiers).
+
+### The `@context` element
+
+A *vocabulary* is a URL where you can find schemas for structured data to be used online. Each vocabulary source ([https://schema.org/](https://schema.org/), for example) defines entities, relationships between entities and actions. The `@context` element defines the *vocabulary* used in the file, making it more human-readable, easier to understand and helping the browser understand the context of the data and its relationships.
+
+By providing a link to the vocabulary, the `@context` element clarifies what the data represents and ensures that it’s interpreted properly. This makes easier the translation between schemata or systems and the reconstruction of lost or foreign contexts in the case these are lost.
+
+In the previous example, the `@context` says “Hey browser, the vocabulary I’m referencing is [http://schema.org](http://schema.org/)".
+
+### The `@type` element
+
+This element specifies the type of the item being marked up. You can find a list of all the available item types [here](https://schema.org/docs/full.html).
+
+In the previous example, the `@type` says “Hey browser, the item type I’m using is **Person**". You can find it [here](http://schema.org/Person).
+
+### Attribute-value pairs
+
+After defining the vocabulary and the item type, you can define the item properties. Inside an item type's Schema.org page (for example [http://schema.org/Person](http://schema.org/Person)), you will find all available properties that an item **Person** can have. In the previous example, `name`, `jobTitle`, `telephone` and `url` are all its properties.
+
+## JSON-LD and Verifiable Credentials
+
+JSON-LD is a format that allows for easy integration of Verifiable Credentials into existing systems, and it provides a standardized way of representing identity-related information. JSON-LD is the perfect format to help ensure VCs interoperability, usability and easy manageablity.
+
+Here's an example of a verifiable credential in JSON-LD format:
+
+```json
+{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1"
+  ],
+  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
+  "issuer": "https://example.edu/issuers/14",
+  "issuanceDate": "2021-06-01T17:00:00Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "degree": {
+      "type": "BachelorDegree",
+      "name": "Bachelor of Science and Arts",
+      "degreeType": "BachelorDegree",
+      "college": "College of Engineering and Applied Science",
+      "university": "Example University"
+    }
+  },
+  "proof": {
+    "type": "Ed25519Signature2018",
+    "created": "2021-06-01T17:00:00Z",
+    "proofPurpose": "assertionMethod",
+    "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1",
+    "jws": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6ZXhhbXBsZTpiMzllZjJhZjM1NzY2ZGE2M2Q5MmUxMzAwMjQyMmVjMzIyNjVhYTE3IiwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmVkdS9pc3N1ZXJzLzE0IiwiaWF0IjoxNjIyMjAzMTM4LCJleHAiOjE2MjIyMDMxNzgsImp3ayI6eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2In19..5uMz5N5R5C5vK1V7Bp5G9fWbq3qkijxHx6GpUudKdJqAywq6HnGX6kGPEA9KjZlYi4f4sH4b4C8QsFyj-oCg"
+  }
+}
+```
+
+This Verifiable Credential is a University Degree Credential, issued by Example University to a specific individual identified by a [DID](https://docs.trinsic.id/learn/concepts/dids/). The credential contains information about the degree earned, including the degree type, name, college and university. The credential also includes a proof that it was issued by Example University and that the information it contains has not been tampered with.