fix: entity_statements claims to subordinate_statements and normative lang about it

peppelinux · web-flow · commit 5a9651747e3d · 2024-12-10T15:29:41.000+01:00
diff --git a/openid-federation-extended-listing-1_0.md b/openid-federation-extended-listing-1_0.md
@@ -47,7 +47,7 @@ organization="Self-Issued Consulting"
 
 .# Abstract
 
-This specification acts as an extension to the [@!OpenID.Federation]. It defines methods to interact with a given Federation with a potentially large number of registered Entities, as well as mechanisms to retrieve multiple Entity Statements along with associated details in a single request.
+This specification acts as an extension to the [@!OpenID.Federation]. It defines methods to interact with a given Federation with a potentially large number of registered Entities, as well as mechanisms to retrieve multiple Subordinate Statements along with associated details in a single request.
 
 {mainmatter}
 
@@ -57,11 +57,11 @@ The Federation Extended Subordinate Listing endpoint has been created to address
 
 ## Response Size
 
-The standard `federation_list_endpoint` has limitations when Entities are able to issue Entity Statements for an exceptionally large number of Entities. Limitations can be encountered both when attempting to process receiving such a large response as well as more technical limitations such as response sizes of infrastructure. Pagination has been proposed as a solution for this.
+The standard `federation_list_endpoint` has limitations when Entities are able to issue Subordinate Statements for an exceptionally large number of Entities. Limitations can be encountered both when attempting to process receiving such a large response as well as more technical limitations such as response sizes of infrastructure. Pagination has been proposed as a solution for this.
 
 ## Bulk Retrieval
 
-For certain usecases, such as mass registration, consumers may encounter challenges when attempting to retrieve information on multiple Entities. A flow with the standard `federation_list_endpoint` may involve a request to the list endpoint followed by a series of subsequent requests to retrieve an Entity Statement for each listed Entity resulting in an N+1 operation. The Federation Extended Subordinate Listing endpoint seeks to solve this by providing a mechanism to include additional metadata for Entities in the provided list.
+For certain usecases, such as mass registration, consumers may encounter challenges when attempting to retrieve information on multiple Entities. A flow with the standard `federation_list_endpoint` may involve a request to the list endpoint followed by a series of subsequent requests to retrieve a Subordinate Statement for each listed Entity resulting in an N+1 operation. The Federation Extended Subordinate Listing endpoint seeks to solve this by providing a mechanism to include additional metadata for Entities in the provided list.
 
 ## Requirements Notation and Conventions
 
@@ -97,7 +97,7 @@ The endpoint accepts all parameters defined in the `federation_list_endpoint` in
 | limit            | OPTIONAL         | Positive Integer  | Requested number of results included in the response.<br><br> If this parameter is present, the number of results in the returned list SHOULD NOT be greater than the minimum of the server's upper limit and the value of this parameter.<br><br>If this parameter is not present the server MUST fall back on the upper limit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | updated_after    | OPTIONAL         | NumericDate       | Epoch time constraining the response to include only Entity identifiers with updates at or after this time. <br><br>When absent, there is no cutoff for how long ago updates occurred to Entities being listed.<br><br>When present the `registered`, `updated`, `revoked` MUST be included in the response unless the `audit_timestamps` parameter is set to `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 ||
 | updated_before   | OPTIONAL         | NumericDate       | Epoch time constraining the response to include only Entity identifiers with updates at or before this time.<br><br>When absent, there is no cutoff before which updates occurred to listed Entities.<br><br>When present the `registered`, `updated`, `revoked` MUST be included in the response unless the `audit_timestamps` parameter is set to `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           ||
-| claims           | OPTIONAL         | Array             | List of claims to be included in the response for each returned Immediate Subordinate Entity.<br><br> If this parameter is NOT present or it is an empty array, the Entity Statement MUST be the only claim for each Immediate Subordinate Entity<br><br>If this parameter is present and it is NOT an empty array each JSON object that represents the Immediate Subordinate Entity MUST include the requested claims for a Subordinate Entity Statement if available.<br><br>Entities that expose the Federation Extended Subordinate Listing endpoint MUST support all top level statement claims defined in [@!OpenID.Federation]. TBD: Support of requests for discrete Entity metadata attributes. ||
+| claims           | OPTIONAL         | Array             | List of claims to be included in the response for each returned Immediate Subordinate Entity.<br><br> If this parameter is NOT present or it is an empty array, the response SHOULD NOT contain any claims for a Subordinate Statement.<br><br>If this parameter is present and it is NOT an empty array each JSON object that represents the Immediate Subordinate Entity MUST include the requested claims for a Subordinate Statement if available.<br><br>Entities that expose the Federation Extended Subordinate Listing endpoint MUST support all top level statement claims defined in [@!OpenID.Federation]. TBD: Support of requests for discrete Entity metadata attributes. ||
 | audit_timestamps | OPTIONAL         | Boolean           | Request parameter to control presence of  the `registered`, `updated`, `revoked` audit timestamps attributes for all returned Immediate Subordiates.<br><br>If this parameter absent the audit timestamp attributes mentioned above MUST NOT be present unless `updated_after` and/or `updated_before` parameters are present.<br><br>If this parameter is present and set to `true` the response MUST include the above mentioned audit timestamp attributes for each Immediate Subordinate Entity included in the response.<br><br>If this parameter is present and set to `false` the response MUST NOT include the above mentioned audit timestamp attributes for each Immediate Subordinate Entity included in the response, even irrespective whether the `updated_after` and/or `updated_before` request parameters are present.<br><br>                                                     
 
 *Table 1: Additional request parameters accepted by the Federation Extended Subordinate Listing endpoint in addition to the those specified by the `federation_list_endpoint`*
@@ -148,7 +148,7 @@ Each JSON object in the returned `immediate_subordinate_entities` array MAY cont
 | **Attribute**                                                 | **Availability** | **Type**          | **Value**                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 |---------------------------------------------------------------|------------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | id                                                            | REQUIRED         | Entity Identifier | Entity Identifier for the subject entity of the current record.                                                                                                                                                                                                                                                                                                                                                                                |
-| entity_statement                                                     | OPTIONAL         | String            | Signed entity statement for the Subordinate Entity as issued by the Entity that exposes the Federation Extended Subordinate Listing endpoint.<br><br>This `entity_statement` attribute SHOULD be returned if the `claims` parameter is NOT present in the request or it is present but the array is empty.<br><br>This `entity_statement` attribute MUST NOT be returned if the `claims` parameter is NOT present in the request or it is present but the array is empty. |
+| subordinate_statement                                                     | OPTIONAL         | String            | Subordinate Statement for the Immediate Subordinate Entity as issued by the Entity that exposes the Federation Extended Subordinate Listing endpoint.<br><br>This `subordinate_statement` attribute MUST be returned if the `claims` parameter is present and contains `subordinate_statement`. It MUST NOT be returned if the `claims` parameter is present but the array does not contain `subordinate_statement`. |
 | trust_marks, metadata, and/or other selected statement claims | OPTIONAL         | N/A               | Selected Immediate Subordinate claims as requested with the `claims` request attribute. <br><br>These attributes MUST NOT be returned if the `claims` parameter is NOT present in the request or it is present but the array is empty.                                                                                                                                                                                                        |
 | registered                                                    | OPTIONAL         | Number            | Time when the Entity was registered with the issuing party using NumericDate format.                                                                                                                                                                                                                                                                                                                                                           |
 | updated                                                       | OPTIONAL         | Number            | Time when the Entity was updated using the time format defined for the `iat` claim in [@!RFC7519]. This parameter MAY indicate that the Federation Entity Keys or metadata policies or constraints about this Entity was updated.                                                                                                                                                   |
@@ -168,17 +168,17 @@ Content-Type: application/json
   "immediate_subordinate_entities": [
     {
       "id": "https://rp0.example.net/oidc/rp",
-      "entity_statement": "eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiQlh2ZnJ..."
+      "subordinate_statement": "eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiQlh2ZnJ..."
     },
     {
       "id": "https://rp0.example.net/oidc/rp",
-      "entity_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
+      "subordinate_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
     }
   ]
 }
 ```
 
-*Figure 5: Example Federation Extended Subordinate Listing endpoint response that includes Entity Statements.*
+*Figure 5: Example Federation Extended Subordinate Listing endpoint response that includes Subordinate Statements.*
 
 ```
 GET /list_extended?audit_timestamps=true&claims=entity_statement HTTP/1.1
@@ -190,7 +190,7 @@ Content-Type: application/json
   "immediate_subordinate_entities": [
     {
       "id": "https://rp0.example.net/oidc/rp",
-      "entity_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
+      "subordinate_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
       "registered":1704217689,
       "updated":1704217789,
       "revoked":1704217800
@@ -199,10 +199,10 @@ Content-Type: application/json
 }
 ```
 
-*Figure 6: Example Federation Extended Subordinate Listing endpoint response that includes an Entity Statement and audit timestamps*
+*Figure 6: Example Federation Extended Subordinate Listing endpoint response that includes an Subordinate Statement and audit timestamps*
 
 ```
-GET /list_extended?claims=entity_statement,trust_marks HTTP/1.1
+GET /list_extended?claims=subordinate_statement,trust_marks HTTP/1.1
 
 200 OK
 Content-Type: application/json
@@ -217,13 +217,13 @@ Content-Type: application/json
           "trust_mark": "eyJraWQiOiJmdWtDdUtTS3hwWWJjN09lZUk3Ynlya3N5a0E1bDhP..."
         }
       ],
-      "entity_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
+      "subordinate_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
     }
   ]
 }
 ```
 
-*Figure 7: Example Federation Extended Subordinate Listing endpoint response that includes Entity Statements and Trust Marks*
+*Figure 7: Example Federation Extended Subordinate Listing endpoint response that includes Subordinate Statements and Trust Marks*
 
 # Federation Entity Property
 
@@ -246,23 +246,23 @@ Content-Type: application/json
   "immediate_subordinate_entities": [
     {
       "id": "https://0.example.net",
-      "entity_statement": "eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiQlh2ZnJ..."
+      "subordinate_statement": "eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiQlh2ZnJ..."
     },
     {
       "id": "https://1.example.net",
-      "entity_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
+      "subordinate_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
     },
     ...
     {
       "id": "https://999.example.net",
-      "entity_statement": "eyK2aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
+      "subordinate_statement": "eyK2aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
     }
   ],
   "next_entity_id": "https://1000.example.net"
 }
 ```
 
-*Figure 8: A Trust Anchor returns the results list consisting of thousand Immediate Subordinate Entities, along with the next Entity id that the next page starts with, in response to the request to list all immediate Subordinate Entities.*
+*Figure 8: A Trust Anchor returns the results list consisting of thousand Immediate Subordinate Entities, along with the next Entity id that the next page starts with, in response to the request to list all Immediate Subordinate Entities.*
 
 ```
 GET /list_extended?from_entity_id=https://1000.example.net HTTP/1.1
@@ -274,15 +274,15 @@ Content-Type: application/json
   "immediate_subordinate_entities": [
     {
       "id": "https://1000.example.net",
-      "entity_statement": "eyK2aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
+      "subordinate_statement": "eyK2aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
     },
     {
       "id": "https://1001.example.net",
-      "entity_statement": "eyH4aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
+      "subordinate_statement": "eyH4aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
     },
     {
       "id": "https://1003.example.net",
-      "entity_statement": "eyW9aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
+      "subordinate_statement": "eyW9aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
     }
   ]
 }
@@ -300,22 +300,22 @@ Content-Type: application/json
   "immediate_subordinate_entities": [
     {
       "id": "https://123.example.net",
-      "entity_statement": "eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiQlh2ZnJ...",
+      "subordinate_statement": "eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiQlh2ZnJ...",
       "registered": 1704217689,
       "updated": 1704217789,
       "revoked": 1704217800
     },
     {
       "id": "https://323.example.net",
-      "entity_statement": "eyW9aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
+      "subordinate_statement": "eyW9aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
       "registered": 1704217689,
       "updated": 1704217789,
       "revoked": 1704217800
     },
     ...
     {
       "id": "https://342.example.net",
-      "entity_statement": "eyK2aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
+      "subordinate_statement": "eyK2aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
       "registered": 1704217689,
       "updated": 1704217789,
       "revoked": 1704217800
