Merge pull request #1 from w3c/gh-pages

Merging head fork back into mine

Author: Grant Noble

index.html

@@ -155,7 +155,7 @@ <h2>Introduction</h2>
       <p>
 It is currently difficult to express banking account information,
 education qualifications, healthcare data, and other sorts of machine-readable
-personal information that has been verified by a 3rd party on the Web and this
+personal information that was verified by a third-party on the Web and this
 makes it difficult to receive the same benefits from the Web that physical
 credentials provide us in the physical world.
       </p>
@@ -166,47 +166,47 @@ <h2>Introduction</h2>
 and machine-verifiable.
       </p>
       <p>
-For those that are unfamiliar with the concepts related to verifiable
+For those who are unfamiliar with the concepts related to verifiable
 credentials, the following sections provide an overview of:
       </p>
-      <ol>
+      <ul>
         <li>
-the components that constitute a <a>verifiable credential</a>,
+The components that constitute a <a>verifiable credential</a>
         </li>
         <li>
-the components that constitutes a <a>verifiable presentation</a>,
+The components that constitute a <a>verifiable presentation</a>
         </li>
         <li>
-an ecosystem where verifiable credentials and verifiable presentations are
-expected to be useful, and
+An ecosystem where verifiable credentials and verifiable presentations are
+expected to be useful
         </li>
         <li>
-the use cases and requirements that informed this specification.
+The use cases and requirements that informed this specification.
         </li>
-      </ol>
+      </ul>
       </p>
 
     <section>
       <h3>What is a Verifiable Credential?</h3>
 
       <p>
-In the physical world, a credential may consist of:
+In the physical world, a credential might consist of:
       </p>
 
       <ul>
         <li>
-information related to the subject of the credential (e.g., photo, name, and
-identification number),
+Information related to the subject of the credential (for example, a photo,
+name, and identification number)
         </li>
         <li>
-information related to the issuing authority (e.g., city government,
-national agency, or certification body),
+Information related to the issuing authority (for example, a city government,
+national agency, or certification body)
         </li>
         <li>
-evidence related to how the credential was derived, and
+Evidence related to how the credential was derived
         </li>
         <li>
-information related to expiration dates.
+Information related to expiration dates.
         </li>
       </ul>
 
@@ -220,16 +220,16 @@ <h3>What is a Verifiable Credential?</h3>
 presentations can be rapidly transmitted, making them more convenient than
 their physical counterparts when establishing trust at a distance.
       </p>
-        <p>
-            The persistence of digital information, and the ease with which
-            disparate sources of digital data may be collected and correlated,
-            comprise a privacy concern that the use of verifiable and easily
-            machine-readable credentials threatens to exacerbate. A <a href="#privacy-considerations">Privacy Considerations</a>
-            section addresses these issues. Items of particular concern in
-            this specification may also be noted in the text. Examples of
-            how to use this data model using privacy-enhancing technologies
-            such as zero-knowledge proofs are also provided.
-        </p>
+      <p>
+The persistence of digital information, and the ease with which disparate 
+sources of digital data can be collected and correlated, comprise a privacy 
+concern that the use of verifiable and easily machine-readable credentials 
+threatens to make worse. A <a href="#privacy-considerations">Privacy Considerations</a>
+section addresses these issues. Items of particular concern in this 
+specification are noted in the text. Examples of how to use this data model 
+using privacy-enhancing technologies, such as zero-knowledge proofs, are also 
+provided.
+      </p>
     </section>
     <section>
       <h3>Ecosystem Overview</h3>
@@ -238,53 +238,58 @@ <h3>Ecosystem Overview</h3>
 
       <p>
 This section outlines a basic set of roles and an ecosystem where verifiable
-credentials are expected to be useful. In this section, we distinguish the essential
-roles of core actors and the relationships between them; how do they interact?
-A role is an abstraction that might be implemented in many different ways. The
-separation of roles suggests likely interfaces and/or protocols for
-standardization. The following roles are introduced in this specification:
+credentials are expected to be useful. In this section, we describe the 
+essential roles of the core actors and the relationships between them; how do 
+they interact? A role is an abstraction that might be implemented in many 
+different ways. The separation of roles suggests likely interfaces and 
+protocols for standardization. The following roles are introduced in this 
+specification:
       </p>
 
       <dl>
         <dt><a>holder</a></dt>
         <dd>
-A role an <a>entity</a> may perform by possessing one or more
+A role an <a>entity</a> might perform by possessing one or more
 <a>verifiable credentials</a> and generating <a>presentations</a> from them.
 Examples of holders include students, employees, and customers.
         </dd>
         <dt><a>issuer</a></dt>
         <dd>
-A role an <a>entity</a> may perform by creating a <a>verifiable credential</a>,
-associating it with a particular <a>subject</a>, and transmitting it to
-a <a>holder</a>. Examples of issuers include corporations, non-profits,
-trade associations, governments, and individuals.
+A role an <a>entity</a> might perform by creating a 
+<a>verifiable credential</a>, associating it with a specific <a>subject</a>, 
+and transmitting it to a <a>holder</a>. Examples of issuers include 
+corporations, non-profit organizations, trade associations, governments, and 
+individuals.
         </dd>
         <dt><a>verifier</a></dt>
         <dd>
-A role an <a>entity</a> may perform by requesting and receiving a
-<a>verifiable presentation</a> that proves the holder possesses the required verifiable credentials with certain characteristics.
-Examples of verifiers include employers, security personnel, and websites.
+A role an <a>entity</a> might perform by requesting and receiving a
+<a>verifiable presentation</a> that proves the holder possesses the required 
+<a>verifiable credentials</a> with certain characteristics. Examples of 
+verifiers include employers, security personnel, and websites.
         </dd>
         <dt><a>identifier registry</a></dt>
         <dd>
-A role a system may perform by mediating the creation and verification of <a>issuer</a> identifiers,
-keys and other relevant data required to use verifiable credentials. Some configurations may require correlatable
-identifiers for subjects. Examples of such data repositories include trusted databases,
-decentralized databases, government ID databases, and distributed ledgers.
+A role a system might perform by mediating the creation and verification of 
+<a>issuer</a> identifiers, keys, and other relevant data required to use 
+<a>verifiable credentials</a>. Some configurations might require correlatable
+identifiers for <a>subjects</a>. Examples of such data repositories include 
+trusted databases, decentralized databases, government ID databases, and 
+distributed ledgers.
         </dd>
       </dl>
 
       <figure>
         <img style="margin: auto; display: block;" width="75%" src="diagrams/ecosystem.svg">
         <figcaption style="text-align: center;">
-The roles and information flows that form the basis for this specification.
+The roles and information flows forming the basis for this specification.
         </figcaption>
       </figure>
 
       <p class="note">
-The ecosystem above is provided as an example to the reader in order to ground
-the rest of the concepts in this specification. Other ecosystems exist, such as
-protected environments or proprietary systems, where verifiable credentials also
+The ecosystem above is provided as an example to ground the rest of the 
+concepts in this specification. Other ecosystems exist, such as protected 
+environments or proprietary systems, where <a>verifiable credentials</a> also
 provide benefit.
       </p>
 
@@ -324,41 +329,41 @@ <h3>Use Cases and Requirements</h3>
 
       <p>
 The Verifiable Credentials Use Cases [[VC-USECASES]] document outlines a number of
-key topics that readers may find useful, including:
+key topics that readers might find useful, including:
       </p>
       <ul>
         <li>
-a more thorough explanation of the
+A more thorough explanation of the
 <a href="https://www.w3.org/TR/verifiable-claims-use-cases/#user-roles">roles</a>
-introduced above,
+introduced above
         </li>
         <li>
-the
+The
 <a href="https://www.w3.org/TR/verifiable-claims-use-cases/#user-needs">needs</a>
-identified in market verticals like education, finance, healthcare, retail,
-professional licensing, and government,
+identified in market verticals, such as education, finance, healthcare, retail,
+professional licensing, and government
         </li>
         <li>
-common
+Common
 <a href="https://www.w3.org/TR/verifiable-claims-use-cases/#user-tasks">tasks</a>
 performed by the roles in the ecosystem, as well as their associated
-requirements, and
+requirements
         </li>
         <li>
-common
+Common
 <a href="https://www.w3.org/TR/verifiable-claims-use-cases/#user-sequences">sequences and flows</a>
 identified by the Working Group.
         </li>
       </ul>
       <p>
 As a result of documenting and analyzing the use cases document, a number of
-desirable ecosystem characteristics have been identified for this
-specification, namely:
+desirable ecosystem characteristics were identified for this specification, 
+specifically:
       </p>
       <ul>
         <li>
 <a>Holders</a> receive and store <a>verifiable credentials</a> from
-<a>issuers</a>. <a>Holders</a> may interact with an issuer through an
+<a>issuers</a>. <a>Holders</a> might interact with an issuer through an
 agent that the issuer needn't trust.
         </li>
         <li>
@@ -367,44 +372,47 @@ <h3>Use Cases and Requirements</h3>
 to <a>verifiers</a>.
         </li>
         <li>
-<a>Holders</a> may interact with <a>verifiers</a> through an agent that
-verifiers needn't trust; verifiers only need to trust
-<a>issuers</a>.
+<a>Holders</a> might interact with <a>verifiers</a> through an agent that
+verifiers need not trust; verifiers only need to trust <a>issuers</a>.
         </li>
         <li>
 <a>Verifiable credentials</a> are associated with <a>subjects</a>, not
-particular services; <a>holders</a> decide how to aggregate and manage
+specific services; <a>holders</a> decide how to aggregate and manage
 <a>verifiable credentials</a> and the <a>verifiable presentations</a>
 associated with them.
         </li>
         <li>
-<a>Holders</a> are able to easily control and own their own identifiers.
+<a>Holders</a> can easily control and own their own identifiers.
         </li>
         <li>
 <a>Holders</a> control which <a>verifiable credentials</a> to use and when.
         </li>
         <li>
-<a>Holders</a> are able to freely choose and change the agents they employ
-to help them manage their <a>verifiable credentials</a> and generate and share <a>verifiable presentations</a>.
+<a>Holders</a> can freely choose and change the agents they employ to help 
+them manage their <a>verifiable credentials</a> and generate and share 
+<a>verifiable presentations</a>.
         </li>
         <li>
-<a>Holders</a> can share <a>verifiable presentations</a> that can be verified without revealing
-the identity of the <a>verifier</a> to the <a>issuer</a>.
+<a>Holders</a> can share <a>verifiable presentations</a> that can be verified 
+without revealing the identity of the <a>verifier</a> to the <a>issuer</a>.
         </li>
         <li>
-<a>Holders</a> in <a>presentations</a> can either disclose the attributes or satisfy <a>predicates</a>
-requested by the <a>verifier</a>. <a>Predicates</a> are boolean conditions like greater/less than or
-equal to, is in set, etc.
+<a>Holders</a> in <a>presentations</a> can either disclose the attributes or 
+satisfy <a>predicates</a> requested by the <a>verifier</a>. <a>Predicates</a> 
+are boolean conditions like greater/less than or equal to, is in set, and so 
+on.
         </li>
         <li>
-<a>Verifiable credentials</a> and <a>verifiable presentations</a> are expressed in one or more standard,
-machine-readable data formats which can also be extended with minimal coordination.
+<a>Verifiable credentials</a> and <a>verifiable presentations</a> are 
+expressed in one or more standard, machine-readable data formats, which can 
+also be extended with minimal coordination.
         </li>
         <li>
-Issuers issue <a>verifiable credentials</a>, and holders store them.
-Holders offer <a>verifiable presentations</a>, and verifiers verify them.
-Issuance of credentials, storage of credentials, the generation and sharing
-of presentations, and the verification of them are each independent processes.
+<a>Issuers</a> issue <a>verifiable credentials</a>, and <a>holders</a> store 
+them. <a>Holders</a> offer <a>verifiable presentations</a>, and 
+<a>verifiers</a> verify them. Issuing of credentials, storage of credentials, 
+generation and sharing of presentations, and verification of presentations are 
+each independent processes.
         </li>
         <li>
 <a>Verifiable Credentials</a> can be revoked by the <a>issuer</a>.
@@ -1573,7 +1581,7 @@ <h2>Terms of Use</h2>
   ],
   "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
   "type": "VerifiablePresentation",
-  "credential": [{
+  "verifiableCredential": [{
     "id": "http://dmv.example.gov/credentials/3732",
     "type": ["VerifiableCredential", "ProofOfAgeCredential"],
     "issuer": "https://dmv.example.gov/issuers/14",
@@ -1875,7 +1883,7 @@ <h3> Passing on a Verifiable Credential </h3>
 {
   "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
   "type": ["VerifiablePresentation"],
-  "credential": [{
+  "verifiableCredential": [{
       "id": "http://example.gov/credentials/3732",
       "type": ["VerifiableCredential", "PrescriptionCredential"],
       "issuer": "https://dmv.example.gov",