docs: fixed numerous typos, kudos @bhadley!

spec/v3/index.md

@@ -682,7 +682,7 @@ The scope of the HTTP API is minimal by design. Additional features will be adde
 A host system serves the needs of a single or multiple [=data owners=]. Additionally, a host system can also serve the needs of [=data recipients=] if it retrieves data from other host systems by calling their API.
 
 In other words, any host system which implements the API endpoints as described in this specification can play 
-the role of [=data owner=] as well as of [=data recipient=], thus mirroring real-world supply chains, also see [[#business-cases]]
+the role of [=data owner=] as well as of [=data recipient=], thus mirroring real-world supply chains. See [[#business-cases]] for more details.
 
 A [=host system=] MUST implement the following actions:
 
@@ -691,7 +691,7 @@ A [=host system=] MUST implement the following actions:
  - [Action GetFootprint](#action-getfootprint)
  - [Action Events](#action-events)
 
-The host system MUST make its footprints available to the data recipient through BOTH [=Action ListFootprints=] AND [=Action Event=]. 
+The host system MUST make its footprints available to the data recipient through BOTH [=Action ListFootprints=] AND [=Action Events=]. 
 
 A [=host system=] MUST offer its actions over HTTPS only. 
 
@@ -726,11 +726,11 @@ The following section briefly describes some of the additional functionality whi
 
 ## Error Handling ## {#api-error-handling}
 
-[he actions [GetFootprint](#action-getfootprint), [ListFootprints](#action-listfootprints) and [Events](#action-events) MUST return an appropriate HTTP status code and MUST include a JSON <{Error}> object with information on the error.
+The actions [GetFootprint](#action-getfootprint), [ListFootprints](#action-listfootprints) and [Events](#action-events) MUST return an appropriate HTTP status code and MUST include a JSON <{Error}> object with information on the error.
 
-Error responses are specified in detail such that data recipients can understand the cause of the error, and so that potentially host systems can react on and resolve errors automatically.
+Error responses are specified in detail such that data recipients can understand the cause of the error, and so that potentially host systems can act on and resolve errors automatically.
 
-Error responses from [Action Auth](#api-auth) follow the OAuth specification [[!rfc6750]]. See [[#api-auth]]
+Error responses from [Action Authenticate](#api-auth) follow the OAuth specification [[!rfc6750]]. See [[#api-auth]]
 
 
 ## Authentication Flow ## {#api-auth}
@@ -752,10 +752,10 @@ If provided by the host system, this document contains the `token_endpoint` to b
 
 If no OpenID configuration is provided by the host system, clients MUST assume `$auth-base-url$/auth/token` to be the token endpoint.
 
-After determining the token endpoint, clients MUST obtain by making a request to:
+After determining the token endpoint, clients MUST obtain an access token by making a request to:
 
-```
-POST $token-endpoint$
+```http
+POST $token-endpoint$ 
 ```
 
 with the following request parameters:
@@ -806,47 +806,17 @@ GET <base-url>/protected-resource
 Authorization: Bearer <access_token>
 ```
 
-The host system MUST check the Access Token and return an 401 when it has expired or is invaliud. 
+The host system MUST check the Access Token and return a 401 when it has expired or is invalid. 
 
-[=Access tokens=] SHOULD expire. In this case, data recipients MUST retrieve a new [=access token=]
+Access tokens SHOULD expire. In this case, data recipients MUST retrieve a new [access token](#obtaining-an-access-token)
 as described in this section.
 
-<!--
-A [=host system=] requires a [=data recipient=] to first authenticate before successfully calling an Action (such as [=Action ListFootprints=] or [=Action Events=]). The [=data recipient=] MUST perform the <dfn>authentication flow</dfn>:
-
-1. data recipient attempting to perform the OpenId Connect-based flow, by
-    1. retrieving and validating the [=OpenId Provider Configuration Document=] of the host system (see [[!OPENID-CONNECT]]), and then
-    2. using as [=AuthEndpoint=] the value of the `token_endpoint` property of the [=OpenId Provider Configuration Document=]
-2. otherwise, data recipient using [=AuthHostname=]`/`[=AuthSubpath=]`/auth/token` as the [=AuthEndpoint=] in the next step.
-3. data recipient retrieving the [=access token=] from [=AuthEndpoint=] (see [[#api-action-auth-request]]).
-
-Note: The [=authentication flow=] is defined such that a Version [VERSION] data recipient can authenticate against host versions irrespective of their support for OpenID-Connect.
-
-<figure>
-  <img src="diagrams/authentication-flow.svg" height="100%" width="100%" >
-  <figcaption>Authentication flow.</figcaption>
-</figure>
-
-
-Once the [=authentication flow=] is complete, the [=data recipient=] can call the other actions of the [=host system=]
-  - using the value of `access_token` of the response of the [=Action Authenticate=] call as the
-    value for a [[!rfc6750]] <dfn>Bearer token</dfn>
-  - presenting the Bearer token for subsequent call(s) to the host system in accordance with
-    [[!rfc6750]] Section 2.1
--->
-
 
 <pre class=include>
 path: rest-api.generated.md
 </pre>
 
 
-<!--
-<pre class=include>
-path: rest-api.md
-</pre>
--->
-
 # Examples # {#api-examples}
 
 <div class=note>Non-normative</div>

spec/v3/openapi.yaml

@@ -49,7 +49,7 @@ paths:
             ProductFootprints ready to be retrieved, such that
               - The `Link` header conforms to [[!RFC8288]]
               - The value of the `rel` parameter is equal to `next`
-              - the target URI (RFC8288, section 3.1) of the `Link` header is absolute
+              - the target URI of the `Link` header is absolute
               - The value of `host` of the target URI is equal to the value of the `host` 
                 request header from the original `ListFootprints` HTTP request
          3. The target URI from the `Link` header is called a <dfn>pagination link</dfn>.
@@ -67,7 +67,7 @@ paths:
          7. If a response contains a second pagination link and the data recipient has called 
             that second pagination link, the previous pagination link MAY no longer work: data 
             recipients MUST NOT assume that previous pagination links continue to return results 
-            after advancing in the pagination process
+            after advancing in the pagination process.
 
         ### Filtering
 
@@ -185,10 +185,10 @@ paths:
         same `id`, it MUST include only the latest version in the list of footprints.
 
         If the requested ProductFootprint is deprecated, the host system SHOULD
-        return the deprecated ProductFootprint.
+        return the deprecated ProductFootprint, if it is still available.
 
         If the requested ProductFootprint is not found, the host system MUST return
-        an 404 Not Found response.
+        a 404 Not Found response.
         
         Host systems SHOULD implement an access management system and only 
         return the product footprints for which the data owner granted access 
@@ -260,7 +260,7 @@ paths:
     post:
       summary: Action Events
       description: |
-        The Action Events endpoint supports for the following use cases:
+        The Action Events endpoint supports the following use cases:
 
          1. enabling a [=data recipient=] to request Product Footprints
             from a [=data owner=] by sending a `RequestCreatedEvent`, to
@@ -270,7 +270,7 @@ paths:
             updates to 1 or more Product Footprints: `PublishedEvent`
 
         The Action Events endpoint accepts CloudEvent events (see [[!CE]]) encoded 
-        in "Structured Content Mode" (see [[!CE-Structured-Content-Mode]]. 
+        in "Structured Content Mode" (see [[!CE-Structured-Content-Mode]]). 
 
         The CloudEvents are encoded in the "application/cloudevents+json" media type and
         MUST be sent as an HTTP POST request body to the Action Events endpoint.
@@ -376,7 +376,7 @@ components:
         precedingPfIds:
           description: |
             A given PCF may change over time, due to updates to the calculation. 
-            This is a list of ID's that reflect "past versions" of the current PCF,
+            This is a list of IDs that reflect "past versions" of the current PCF,
             maintained by the solution. 
 
             See [[#lifecycle]] for details.
@@ -1463,17 +1463,15 @@ components:
       $ref: '#/components/schemas/BaseEvent'
       title: Request Created Event
       description: |
-        A data recipient request a ProductFootprint from the data owner. The data recipient
+        A data recipient requests a ProductFootprint from the data owner. The data recipient
         MUST provide the criteria in the data object to enable the data owner to either
         find an existing relevant PCF or create a new one.
 
         Criteria to provide can be product id, geography, company identifier, validity 
         period, etc.
 
-        The data owner MUST validate the input parameters, including these criteria. 
-        
         If the data owner can *immediately* determine that it will not be able to 
-        handle this request it MUST respond with an appropriate `4xxx` error response, 
+        handle this request it MUST respond with an appropriate `4xx` error response, 
         otherwise it MUST respond directly with a `200` (Success) or `202` (Accepted). 
 
         In the latter case, the data owner MUST send a follow up event to the data 
@@ -1773,7 +1771,7 @@ components:
 
   securitySchemes:
     BearerAuth:
-      description: OAuth2 Client Credentials Grant (RFC6749 4.4)
+      description: OAuth2 Client Credentials Grant ([[!RFC6749]] 4.4)
       type: oauth2
       flows:
         clientCredentials:
@@ -1785,7 +1783,7 @@ components:
   parameters:
     productId:
       name: productId
-      description: One or more product ID's. Will return all footprints which have a corresponding ID in their `productIds` attribute. Note that a footprint itself can also have multiple product IDs.
+      description: One or more product IDs. Will return all footprints which have a corresponding ID in their `productIds` attribute. Note that a footprint itself can also have multiple product IDs.
       in: query
       explode: true
       schema: 
@@ -1794,7 +1792,7 @@ components:
           $ref: '#/components/schemas/Urn'
     companyId:
       name: companyId
-      description: One or more company ID's. Will return all footprints which have a corresponding ID in their `companyId` attribute.
+      description: One or more company IDs. Will return all footprints which have a corresponding ID in their `companyId` attribute.
       in: query
       explode: true
       schema: 
@@ -1822,31 +1820,31 @@ components:
     validOn:
       name: validOn
       description: |
-        If present, MUST match all PCFs which where valid on the date specified: footprint.validityPeriodBegin <= validOn AND validFrom <= footprint.validityPeriodEnd
+        If present, MUST match all PCFs which were valid on the date specified: footprint.validityPeriodBegin <= validOn AND validFrom <= footprint.validityPeriodEnd
       in: query
       schema:
         type: string
         format: date-time
     validAfter:
       name: validAfter
       description: |
-        if present, MUST match PCFs whith validAfter < footprint.validityPeriodBegin
+        If present, MUST match PCFs with validAfter < footprint.validityPeriodBegin
       in: query
       schema:
         type: string
         format: date-time
     validBefore:
       name: validBefore
       description: |
-        if present, MUST match PCFs whith validBefore > footprint.validityPeriodEnd
+        If present, MUST match PCFs with validBefore > footprint.validityPeriodEnd
       in: query
       schema:
         type: string
         format: date-time
     status:
       name: status
       description: |
-        if present, MUST be either be "Active" or "Deprecated"
+        If present, MUST be "Active" or "Deprecated". If not specified, will return footprints regardless of status. 
       in: query
       schema:
         type: string