From aaa2ce8c287d4db76527909b539bd4bba1e56178 Mon Sep 17 00:00:00 2001 From: Andres Olave Date: Tue, 4 Jun 2024 12:21:25 +1000 Subject: [PATCH 1/2] Cleanup TRP formatting --- spec/requirements.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/spec/requirements.md b/spec/requirements.md index 46c667c..c68ec1d 100644 --- a/spec/requirements.md +++ b/spec/requirements.md @@ -133,7 +133,7 @@ The authoritative technical specifications for the API calls in the ToIP Trust R - `Terminated` + http code 200 - authorization was terminated (e.g. voluntary termination by the **registered entity**) - `Revoked` + http code 200 - authorization was revoked (e.g. involuntary termination by the **governing authority**) - [TRP-3-2] **Entity Authorizations**: Given only the `entityDID` the system SHOULD return the array of Authorization objects for the entity identified by `entityDID`. - - ii. [TRP-3-2] **Recognized Registry:** Given the entityDID the system SHOULD return the list of [[def:trust registries]] that the entity has indicated it is registered in. + - [TRP-3-2] **Recognized Registry:** Given the entityDID the system SHOULD return the list of [[def:trust registries]] that the entity has indicated it is registered in. - [TRP-3-2-1] The system MUST NOT return more than one trust registry in the array designated as a [[def: primary registry]]. @@ -141,23 +141,23 @@ The authoritative technical specifications for the API calls in the ToIP Trust R Align VID and/or DID terminology. ::: -[TRP-4] MUST return responses using the data model specified in the OpenAPI Specification . +* [TRP-4] MUST return responses using the data model specified in the OpenAPI Specification . -[TRP-5] For queries returning a **status value** other than `Not Found`, the response MUST return the following values: +* [TRP-5] For queries returning a **status value** other than `Not Found`, the response MUST return the following values: - [TRP-5-1] The system must return the parameter values exactly as supplied in the query (so responses can be stateless). - [TRP-5-2] The system must return the **status value** for the entity (per TRP-3-1). - [TRP-5-3] The system must return exactly two **datetime values** conforming to the following requirements: - - [TRP-5-3-1]The value labels MUST be: - - i. `AuthorizationStartDate` - - ii. `AuthorizationEndDate` - - [TRP-5-3-2] The datetime values MUST be formatted to comply with [[spec-norm:RFC3339]] in the UTC/Z time zone with no offset. - - [TRP-5-3-3] The `AuthorizationStartDate` MUST be the date that the **registered entity** authorization began. - - [TRP-5-3-4] The `AuthorizationEndDate` MUST be either: - - [TRP-5-3-4-1] `Null` for an entry whose **status value** is `Current` at the time of the query. - - [TRP-5-3-4-2] A specific datetime value if the **registered entity** **status value** is `Expired`, `Terminated` or `Revoked.` - - [TRP-5-3-5] If a **registered entity** has multiple entries in the system (representing an authorization history), the value that is active at the time indicated must be returned: - - [TRP-5-3-5-1] when no `queryTime` value is provided the value that is active at time of the query MUST be returned. - - [TRP-5-3-5-2] when a `queryTime` parameter is provided the entry that is active at that time (i.e. indicted by `queryTime`) MUST be returned. + - [TRP-5-3-1]The value labels MUST be: + - i. `AuthorizationStartDate` + - ii. `AuthorizationEndDate` + - [TRP-5-3-2] The datetime values MUST be formatted to comply with [[spec-norm:RFC3339]] in the UTC/Z time zone with no offset. + - [TRP-5-3-3] The `AuthorizationStartDate` MUST be the date that the **registered entity** authorization began. + - [TRP-5-3-4] The `AuthorizationEndDate` MUST be either: + - [TRP-5-3-4-1] `Null` for an entry whose **status value** is `Current` at the time of the query. + - [TRP-5-3-4-2] A specific datetime value if the **registered entity** **status value** is `Expired`, `Terminated` or `Revoked.` + - [TRP-5-3-5] If a **registered entity** has multiple entries in the system (representing an authorization history), the value that is active at the time indicated must be returned: + - [TRP-5-3-5-1] when no `queryTime` value is provided the value that is active at time of the query MUST be returned. + - [TRP-5-3-5-2] when a `queryTime` parameter is provided the entry that is active at that time (i.e. indicted by `queryTime`) MUST be returned. ### Anti-Requirements From 6fa34d2bf825e418dd1f9a5c8385faca716dcaca Mon Sep 17 00:00:00 2001 From: Andres Olave Date: Tue, 4 Jun 2024 12:38:10 +1000 Subject: [PATCH 2/2] Update requirements.md --- spec/requirements.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/spec/requirements.md b/spec/requirements.md index c68ec1d..6473a15 100644 --- a/spec/requirements.md +++ b/spec/requirements.md @@ -122,10 +122,8 @@ The authoritative technical specifications for the API calls in the ToIP Trust R * [TRP-2] The system SHOULD support queries that are at a point in time in the past. * [TRP-2-1] The parameter for the point in time must be named `queryTime`. * [TRP-2-2] The datetime value provided MUST be formatted per [[spec-norm:RFC3339]] using the UTC (i.e. Z for Zulu) zero offset (e.g. "2018-03-20T09:12:28Z". - * [TRP-2-3] If the system does not support non-current data, and the the `queryTime` parameter is present, the system MUST NOT return entity data and must se http error code 405 (Method not allowed). - + * [TRP-2-3] If the system does not support non-current data, and the the `queryTime` parameter is present, the system MUST NOT return entity data and must use http error code 405 (Method not allowed). * [TRP-3] MUST return responses to queries for the **status value** of a **registry entry** that satisfies one or more of the following sets of query parameters: - - [TRP-3-1] **Entity Authorization**: Given the `entityDID`, and `authorization` return the status of that registered entity, MUST return exactly one of the following **status values** for a **registry entry** satisfying the query parameters: - `Not Found` + http code 404 - entry not found. - `Current` + http code 200 - authorization for the registered entity is current as of the time of query, or as of the time requested. @@ -133,16 +131,15 @@ The authoritative technical specifications for the API calls in the ToIP Trust R - `Terminated` + http code 200 - authorization was terminated (e.g. voluntary termination by the **registered entity**) - `Revoked` + http code 200 - authorization was revoked (e.g. involuntary termination by the **governing authority**) - [TRP-3-2] **Entity Authorizations**: Given only the `entityDID` the system SHOULD return the array of Authorization objects for the entity identified by `entityDID`. - - [TRP-3-2] **Recognized Registry:** Given the entityDID the system SHOULD return the list of [[def:trust registries]] that the entity has indicated it is registered in. - - [TRP-3-2-1] The system MUST NOT return more than one trust registry in the array designated as a [[def: primary registry]]. + - [TRP-3-3] **Recognized Registry:** Given the `entityDID` the system SHOULD return the list of [[def:trust registries]] that the entity has indicated it is registered in. + - [TRP-3-3-1] The system MUST NOT return more than one trust registry in the array designated as a [[def: primary registry]]. ::: TODO: Align VID and/or DID terminology. ::: -* [TRP-4] MUST return responses using the data model specified in the OpenAPI Specification . - +* [TRP-4] MUST return responses using the data model specified in the OpenAPI Specification. * [TRP-5] For queries returning a **status value** other than `Not Found`, the response MUST return the following values: - [TRP-5-1] The system must return the parameter values exactly as supplied in the query (so responses can be stateless). - [TRP-5-2] The system must return the **status value** for the entity (per TRP-3-1). @@ -154,7 +151,7 @@ The authoritative technical specifications for the API calls in the ToIP Trust R - [TRP-5-3-3] The `AuthorizationStartDate` MUST be the date that the **registered entity** authorization began. - [TRP-5-3-4] The `AuthorizationEndDate` MUST be either: - [TRP-5-3-4-1] `Null` for an entry whose **status value** is `Current` at the time of the query. - - [TRP-5-3-4-2] A specific datetime value if the **registered entity** **status value** is `Expired`, `Terminated` or `Revoked.` + - [TRP-5-3-4-2] A specific datetime value if the **registered entity** **status value** is `Expired`, `Terminated` or `Revoked`. - [TRP-5-3-5] If a **registered entity** has multiple entries in the system (representing an authorization history), the value that is active at the time indicated must be returned: - [TRP-5-3-5-1] when no `queryTime` value is provided the value that is active at time of the query MUST be returned. - [TRP-5-3-5-2] when a `queryTime` parameter is provided the entry that is active at that time (i.e. indicted by `queryTime`) MUST be returned.