use a bulleted list for rules in many places

annotations.md

@@ -5,14 +5,14 @@ This property contains arbitrary metadata.
 
 ## Rules
 
-Annotations MUST be a key-value map where both the key and value MUST be strings.
-While the value MUST be present, it MAY be an empty string.
-Keys MUST be unique within this map, and best practice is to namespace the keys.
-Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`.
-The prefix `org.opencontainers` is reserved for keys defined in Open Container Initiative (OCI) specifications and MUST NOT be used by other specifications and extensions.
-Keys using the `org.opencontainers.image` namespace are reserved for use in the OCI Image Specification and MUST NOT be used by other specifications and extensions, including other OCI specifications.
-If there are no annotations then this property MUST either be absent or be an empty map.
-Consumers MUST NOT generate an error if they encounter an unknown annotation key.
+* Annotations MUST be a key-value map where both the key and value MUST be strings.
+* While the value MUST be present, it MAY be an empty string.
+* Keys MUST be unique within this map, and best practice is to namespace the keys.
+* Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`.
+* The prefix `org.opencontainers` is reserved for keys defined in Open Container Initiative (OCI) specifications and MUST NOT be used by other specifications and extensions.
+* Keys using the `org.opencontainers.image` namespace are reserved for use in the OCI Image Specification and MUST NOT be used by other specifications and extensions, including other OCI specifications.
+* If there are no annotations then this property MUST either be absent or be an empty map.
+* Consumers MUST NOT generate an error if they encounter an unknown annotation key.
 
 ## Pre-Defined Annotation Keys
 

config.md

@@ -11,17 +11,17 @@ This specification uses the following terms:
 
 ### [Layer](layer.md)
 
-Image filesystems are composed of *layers*.
-Each layer represents a set of filesystem changes in a tar-based [layer format](layer.md), recording files to be added, changed, or deleted relative to its parent layer.
-Layers do not have configuration metadata such as environment variables or default arguments - these are properties of the image as a whole rather than any particular layer.
-Using a layer-based or union filesystem such as AUFS, or by computing the diff from filesystem snapshots, the filesystem changeset can be used to present a series of image layers as if they were one cohesive filesystem.
+* Image filesystems are composed of *layers*.
+* Each layer represents a set of filesystem changes in a tar-based [layer format](layer.md), recording files to be added, changed, or deleted relative to its parent layer.
+* Layers do not have configuration metadata such as environment variables or default arguments - these are properties of the image as a whole rather than any particular layer.
+* Using a layer-based or union filesystem such as AUFS, or by computing the diff from filesystem snapshots, the filesystem changeset can be used to present a series of image layers as if they were one cohesive filesystem.
 
 ### Image JSON
 
-Each image has an associated JSON structure which describes some basic information about the image such as date created, author, as well as execution/runtime configuration like its entrypoint, default arguments, networking, and volumes.
-The JSON structure also references a cryptographic hash of each layer used by the image, and provides history information for those layers.
-This JSON is considered to be immutable, because changing it would change the computed [ImageID](#imageid).
-Changing it means creating a new derived image, instead of changing the existing image.
+* Each image has an associated JSON structure which describes some basic information about the image such as date created, author, as well as execution/runtime configuration like its entrypoint, default arguments, networking, and volumes.
+* The JSON structure also references a cryptographic hash of each layer used by the image, and provides history information for those layers.
+* This JSON is considered to be immutable, because changing it would change the computed [ImageID](#imageid).
+* Changing it means creating a new derived image, instead of changing the existing image.
 
 ### Layer DiffID
 

considerations.md

@@ -5,12 +5,12 @@ Instead they MUST ignore unknown properties.
 
 # Canonicalization
 
-OCI Images [are](descriptor.md) [content-addressable](image-layout.md).
-One benefit of content-addressable storage is easy deduplication.
-Many images might depend on a particular [layer](layer.md), but there will only be one blob in the [store](image-layout.md).
-With a different serialization, that same semantic layer would have a different hash, and if both versions of the layer are referenced there will be two blobs with the same semantic content.
-To allow efficient storage, implementations serializing content for blobs SHOULD use a canonical serialization.
-This increases the chance that different implementations can push the same semantic content to the store without creating redundant blobs.
+* OCI Images [are](descriptor.md) [content-addressable](image-layout.md).
+* One benefit of content-addressable storage is easy deduplication.
+* Many images might depend on a particular [layer](layer.md), but there will only be one blob in the [store](image-layout.md).
+* With a different serialization, that same semantic layer would have a different hash, and if both versions of the layer are referenced there will be two blobs with the same semantic content.
+* To allow efficient storage, implementations serializing content for blobs SHOULD use a canonical serialization.
+* This increases the chance that different implementations can push the same semantic content to the store without creating redundant blobs.
 
 ## JSON
 

descriptor.md

@@ -1,13 +1,11 @@
 # OCI Content Descriptors
 
-An OCI image consists of several different components, arranged in a [Merkle Directed Acyclic Graph (DAG)](https://en.wikipedia.org/wiki/Merkle_tree).
-References between components in the graph are expressed through _Content Descriptors_.
-A Content Descriptor (or simply _Descriptor_) describes the disposition of the targeted content.
-A Content Descriptor includes the type of the content, a content identifier (_digest_), and the byte-size of the raw content.
-
-Descriptors SHOULD be embedded in other formats to securely reference external content.
-
-Other formats SHOULD use descriptors to securely reference external content.
+* An OCI image consists of several different components, arranged in a [Merkle Directed Acyclic Graph (DAG)](https://en.wikipedia.org/wiki/Merkle_tree).
+* References between components in the graph are expressed through _Content Descriptors_.
+* A Content Descriptor (or simply _Descriptor_) describes the disposition of the targeted content.
+* A Content Descriptor includes the type of the content, a content identifier (_digest_), and the byte-size of the raw content.
+* Descriptors SHOULD be embedded in other formats to securely reference external content.
+* Other formats SHOULD use descriptors to securely reference external content.
 
 This section defines the `application/vnd.oci.descriptor.v1+json` [media type](media-types.md).
 
@@ -80,10 +78,10 @@ digest                                                                  | algori
 ------------------------------------------------------------------------|---------------------|
 sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b | [SHA-256](#sha-256) |
 
-Before consuming content targeted by a descriptor from untrusted sources, the byte content SHOULD be verified against the digest.
-Before calculating the digest, the size of the content SHOULD be verified to reduce hash collision space.
-Heavy processing before calculating a hash SHOULD be avoided.
-Implementations MAY employ some canonicalization of the underlying content to ensure stable content identifiers.
+* Before consuming content targeted by a descriptor from untrusted sources, the byte content SHOULD be verified against the digest.
+* Before calculating the digest, the size of the content SHOULD be verified to reduce hash collision space.
+* Heavy processing before calculating a hash SHOULD be avoided.
+* Implementations MAY employ some canonicalization of the underlying content to ensure stable content identifiers.
 
 ### Algorithms
 

image-layout.md

@@ -1,7 +1,7 @@
 ## OCI Image Layout Specification
 
-The OCI Image Layout is a slash separated layout of OCI content-addressable blobs and [location-addressable](https://en.wikipedia.org/wiki/Content-addressable_storage#Content-addressed_vs._location-addressed) references (refs).
-This layout MAY be used in a variety of different transport mechanisms: archive formats (e.g. tar, zip), shared filesystem environments (e.g. nfs), or networked file fetching (e.g. http, ftp, rsync).
+* The OCI Image Layout is a slash separated layout of OCI content-addressable blobs and [location-addressable](https://en.wikipedia.org/wiki/Content-addressable_storage#Content-addressed_vs._location-addressed) references (refs).
+* This layout MAY be used in a variety of different transport mechanisms: archive formats (e.g. tar, zip), shared filesystem environments (e.g. nfs), or networked file fetching (e.g. http, ftp, rsync).
 
 Given an image layout and a ref, a tool can create an [OCI Runtime Specification bundle](https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc3/bundle.md) by:
 
@@ -53,14 +53,12 @@ afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 ./blobs/sha256/
 
 ## Blobs
 
-Object names in the `blobs` subdirectories are composed of a directory for each hash algorithm, the children of which will contain the actual content.
-A blob, referenced with digest `<alg>:<hex>` (per [descriptor](descriptor.md#digests-and-verification)), MUST have its content stored in a file under `blobs/<alg>/<hex>`.
-The character set of the entry name for `<hex>` and `<alg>` MUST match the respective grammar elements described in [descriptor](descriptor.md#digests-and-verification).
-For example `sha256:5b` will map to the layout `blobs/sha256/5b`.
-
-The blobs directory MAY contain blobs which are not referenced by any of the [refs](#indexjson-file).
-
-The blobs directory MAY be missing referenced blobs, in which case the missing blobs SHOULD be fulfilled by an external blob store.
+* Object names in the `blobs` subdirectories are composed of a directory for each hash algorithm, the children of which will contain the actual content.
+* A blob, referenced with digest `<alg>:<hex>` (per [descriptor](descriptor.md#digests-and-verification)), MUST have its content stored in a file under `blobs/<alg>/<hex>`.
+* The character set of the entry name for `<hex>` and `<alg>` MUST match the respective grammar elements described in [descriptor](descriptor.md#digests-and-verification).
+* For example `sha256:5b` will map to the layout `blobs/sha256/5b`.
+* The blobs directory MAY contain blobs which are not referenced by any of the [refs](#indexjson-file).
+* The blobs directory MAY be missing referenced blobs, in which case the missing blobs SHOULD be fulfilled by an external blob store.
 
 ### Example Blobs
 
@@ -147,10 +145,10 @@ The [image index](image-index.md) is a multi-descriptor entry point.
 
 This index provides an established path (`/index.json`) to have an entry point for an image-layout and to discover auxiliary descriptors.
 
-No semantic restriction is given for the "org.opencontainers.image.ref.name" annotation of descriptors.
-In general the `mediaType` of each [descriptor][descriptors] object in the `manifests` field will be either `application/vnd.oci.image.index.v1+json` or `application/vnd.oci.image.manifest.v1+json`.
-Future versions of the spec MAY use a different mediatype (i.e. a new versioned format).
-An encountered `mediaType` that is unknown SHOULD be safely ignored.
+* No semantic restriction is given for the "org.opencontainers.image.ref.name" annotation of descriptors.
+* In general the `mediaType` of each [descriptor][descriptors] object in the `manifests` field will be either `application/vnd.oci.image.index.v1+json` or `application/vnd.oci.image.manifest.v1+json`.
+* Future versions of the spec MAY use a different mediatype (i.e. a new versioned format).
+* An encountered `mediaType` that is unknown SHOULD be safely ignored.
 
 
 **Implementor's Note:**

layer.md

@@ -8,13 +8,13 @@ This section defines the `application/vnd.oci.image.layer.v1.tar`, `application/
 
 ## `+gzip` Media Types
 
-The media type `application/vnd.oci.image.layer.v1.tar+gzip` represents an `application/vnd.oci.image.layer.v1.tar` payload which has been compressed with [gzip][rfc1952].
-The media type `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip` represents an `application/vnd.oci.image.layer.nondistributable.v1.tar` payload which has been compressed with [gzip][rfc1952_2].
+* The media type `application/vnd.oci.image.layer.v1.tar+gzip` represents an `application/vnd.oci.image.layer.v1.tar` payload which has been compressed with [gzip][rfc1952].
+* The media type `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip` represents an `application/vnd.oci.image.layer.nondistributable.v1.tar` payload which has been compressed with [gzip][rfc1952_2].
 
 ## Distributable Format
 
-Layer Changesets for the [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` MUST be packaged in [tar archive][tar-archive].
-Layer Changesets for the [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` MUST NOT include duplicate entries for file paths in the resulting [tar archive][tar-archive].
+* Layer Changesets for the [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` MUST be packaged in [tar archive][tar-archive].
+* Layer Changesets for the [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` MUST NOT include duplicate entries for file paths in the resulting [tar archive][tar-archive].
 
 ## Change Types
 
@@ -58,17 +58,14 @@ Where supported, MUST include file attributes for Additions and Modifications in
 
 #### Hardlinks
 
-Hardlinks are a [POSIX concept](http://pubs.opengroup.org/onlinepubs/9699919799/functions/link.html) for having one or more directory entries for the same file on the same device.
-Not all filesystems support hardlinks (e.g. [FAT](https://en.wikipedia.org/wiki/File_Allocation_Table)).
-
-Hardlinks are possible with all [file types](#file-types) except `directories`.
-Non-directory files are considered "hardlinked" when their link count is greater than 1.
-Hardlinked files are on a same device (i.e. comparing Major:Minor pair) and have the same inode.
-The corresponding files that share the link with the > 1 linkcount may be outside the directory that the changeset is being produced from, in which case the `linkname` is not recorded in the changeset.
-
-Hardlinks are stored in a tar archive with type of a `1` char, per the [GNU Basic Tar Format][gnu-tar-standard] and [libarchive tar(5)][libarchive-tar].
-
-While approaches to deriving new or changed hardlinks may vary, a possible approach is:
+* Hardlinks are a [POSIX concept](http://pubs.opengroup.org/onlinepubs/9699919799/functions/link.html) for having one or more directory entries for the same file on the same device.
+* Not all filesystems support hardlinks (e.g. [FAT](https://en.wikipedia.org/wiki/File_Allocation_Table)).
+* Hardlinks are possible with all [file types](#file-types) except `directories`.
+* Non-directory files are considered "hardlinked" when their link count is greater than 1.
+* Hardlinked files are on a same device (i.e. comparing Major:Minor pair) and have the same inode.
+* The corresponding files that share the link with the > 1 linkcount may be outside the directory that the changeset is being produced from, in which case the `linkname` is not recorded in the changeset.
+* Hardlinks are stored in a tar archive with type of a `1` char, per the [GNU Basic Tar Format][gnu-tar-standard] and [libarchive tar(5)][libarchive-tar].
+* While approaches to deriving new or changed hardlinks may vary, a possible approach is:
 
 ```
 SET LinkMap to map[< Major:Minor String >]map[< inode integer >]< path string >
@@ -213,11 +210,9 @@ To signify that the resource `./etc/my-app-config` MUST be removed when the chan
 
 ## Applying Changesets
 
-Layer Changesets of [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` are _applied_, rather than simply extracted as tar archives.
-
-Applying a layer changeset requires special consideration for the [whiteout](#whiteouts) files.
-
-In the absence of any [whiteout](#whiteouts) files in a layer changeset, the archive is extracted like a regular tar archive.
+* Layer Changesets of [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` are _applied_, rather than simply extracted as tar archives.
+* Applying a layer changeset requires special consideration for the [whiteout](#whiteouts) files.
+* In the absence of any [whiteout](#whiteouts) files in a layer changeset, the archive is extracted like a regular tar archive.
 
 ### Changeset over existing files
 
@@ -230,13 +225,13 @@ In all other cases, the implementation MUST do the semantic equivalent of the fo
 
 ## Whiteouts
 
-A whiteout file is an empty file with a special filename that signifies a path should be deleted.
-A whiteout filename consists of the prefix `.wh.` plus the basename of the path to be deleted.
-As files prefixed with `.wh.` are special whiteout markers, it is not possible to create a filesystem which has a file or directory with a name beginning with `.wh.`.
+* A whiteout file is an empty file with a special filename that signifies a path should be deleted.
+* A whiteout filename consists of the prefix `.wh.` plus the basename of the path to be deleted.
+* As files prefixed with `.wh.` are special whiteout markers, it is not possible to create a filesystem which has a file or directory with a name beginning with `.wh.`.
+* Once a whiteout is applied, the whiteout itself MUST also be hidden.
+* Whiteout files MUST only apply to resources in lower/parent layers.
+* Files that are present in the same layer as a whiteout file can only be hidden by whiteout files in subsequent layers.
 
-Once a whiteout is applied, the whiteout itself MUST also be hidden.
-Whiteout files MUST only apply to resources in lower/parent layers.
-Files that are present in the same layer as a whiteout file can only be hidden by whiteout files in subsequent layers.
 The following is a base layer with several resources:
 
 ```
@@ -271,8 +266,9 @@ Implementations SHOULD generate layers such that the whiteout files appear befor
 
 ### Opaque Whiteout
 
-In addition to expressing that a single entry should be removed from a lower layer, layers may remove all of the children using an opaque whiteout entry.
-An opaque whiteout entry is a file with the name `.wh..wh..opq` indicating that all siblings are hidden in the lower layer.
+* In addition to expressing that a single entry should be removed from a lower layer, layers may remove all of the children using an opaque whiteout entry.
+* An opaque whiteout entry is a file with the name `.wh..wh..opq` indicating that all siblings are hidden in the lower layer.
+
 Let's take the following base layer as an example:
 
 ```