improve software integrity and verification documentation

model/Core/Classes/Hash.md

@@ -8,12 +8,11 @@ A mathematically calculated representation of a grouping of data.
 
 ## Description
 
-A hash is a grouping of characteristics unique to the result
-of applying a mathematical algorithm
-that maps data of arbitrary size to a bit string (the hash)
-and is a one-way function, that is,
-a function which is practically infeasible to invert.
-This is commonly used for integrity checking of data.
+A hash is a grouping of characteristics unique to the result of applying a mathematical algorithm
+that maps data of arbitrary size to a bit string (the hash) and is a one-way function, that is,
+a function which is practically infeasible to invert. This is commonly used for integrity checking of data.
+
+The recommended method to verify the integrity of `SoftwareArtifacts` Elements (including `Files`, `Snippets`, and `Packages`) is to use the SoftwareArtifact’s `contentIdentifier` property. 
 
 ## Metadata
 

model/Core/Classes/IntegrityMethod.md

@@ -13,6 +13,8 @@ of a specific Element that correlates to the data in this SPDX document. This id
 a recipient to determine if anything in the original Element has been changed and eliminates
 confusion over which version or modification of a specific Element is referenced.
 
+The recommended method to verify the integrity of `SoftwareArtifacts` Elements (including `Files`, `Snippets`, and `Packages`) is to use the SoftwareArtifact’s `contentIdentifier` property. 
+
 ## Metadata
 
 - name: IntegrityMethod

model/Core/Properties/verifiedUsing.md

@@ -10,6 +10,8 @@ Provides an IntegrityMethod with which the integrity of an Element can be assert
 
 VerifiedUsing provides an IntegrityMethod with which the integrity of an Element can be asserted.
 
+The recommended method to verify the integrity of `SoftwareArtifacts` Elements (including `Files`, `Snippets`, and `Packages`) is to use the SoftwareArtifact’s `contentIdentifier` property.
+
 ## Metadata
 
 - name: verifiedUsing

model/Software/Properties/contentIdentifier.md

@@ -4,11 +4,14 @@ SPDX-License-Identifier: Community-Spec-1.0
 
 ## Summary
 
-Provides a place to record the canonical, unique, immutable identifier for each software artifact using the artifact's gitoid.
+Used by SPDX producers to record the artifact’s gitoid: a canonical, unique, immutable identifier that can be used for software integrity verification.
+
+Used by SPDX consumers to verify the integrity of a software artifact they received.
 
 ## Description
 
-The contentIdentifier provides a canonical, unique, immutable artifact identifier for each software artifact. SPDX 3.0 describes software artifacts as Snippet, File, or Package Elements. The ContentIdentifier can be calculated for any software artifact and can be recorded for any of these SPDX 3.0 Elements using Omnibor, an attempt to standardize how software artifacts are identified independent of which programming language, version control system, build tool, package manager, or software distribution mechanism is in use.  
+### SPDX Producers
+The contentIdentifier is a canonical, unique, immutable artifact identifier for each software artifact. The ContentIdentifier for any software artifact can be calculated and recorded in SPDX 3.0 Snippet, File, or Package Elements. For additional information, see [OmniBOR](https://omnibor.io): an attempt to standardize how software artifacts are identified independent of which programming language, version control system, build tool, package manager, or software distribution mechanism is in use.  
 
 The contentIdentifier is defined as the [Git Object Identifier](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects) (gitoid) of type `blob` of the software artifact. The use of a git-based version control system is not necessary to calculate a contentIdentifier for any software artifact.
 
@@ -18,7 +21,12 @@ The gitoid is expressed in the ContentIdentifier property by using the IANA [git
 Scheme syntax: gitoid":"<git object type>":"<hash algorithm>":"<hash value>
 ```
 
-The OmniBOR ID for the OmniBOR Document associated with a software artifact should not be recorded in this field. Rather, OmniBOR IDs should be recorded in the SPDX Element's ExternalIdentifier property. See [https://omnibor.io](https://omnibor.io) for more details.
+The OmniBOR ID for the OmniBOR Document associated with a software artifact must NOT be recorded in this field. Rather, OmniBOR IDs should be recorded in the SPDX Element's ExternalIdentifier property. See [https://omnibor.io](https://omnibor.io) for more details.
+
+### SPDX Consumers
+The integrity of software objects can be verified by calculating the gitoid(s) (`git hash-object foo`) of the object(s) and comparing the results to the value stored in the SPDX contentIdentifier field. ContentIdentifiers are canonical: Omnibor specifies a reproducible algorithm for anyone with the software object to perform this calculation. ContentIdentifiers are unique: the gitoid value is the result of a specific implementation of a one-way hash function. If the calculated gitoid value is the same as the gitoid value stored in SPDX, you can be sure it’s the same software. ContentIdentifiers are immutable: if a software object changes the resulting contentIdentifier will differ. These properties enable the verification of software integrity between producer and consumer using SPDX.
+
+
 
 ## Metadata