Merge pull request #51 from darrellodonnell/main

QUERY and other edits

diagrams/highlevel.plantuml

@@ -2,7 +2,7 @@
 
 
 
-title Trust Over IP Trust Registry Protocol v2 Data Model - Implementer Review Draft
+title Trust Over IP Trust Registry Query Protocol v2 Data Model - Implementer Review Draft
 
 package EGF {
 

diagrams/protocol-bridging.plantuml

@@ -4,26 +4,46 @@
 ' !include C4_Context.puml
 
 
-title Native and Bridged Support for TRP - Implementer Review Draft
+title Native and Bridged Support for TRQP - Implementer Review Draft
 
 Person(Integrator, "Integrator", "Ecosystem Developer")
 
-System(Bridge, "TR Protocol Bridge")
-System(TRAIN, "TRAIN")
+System(Bridge, "Generic Bridge")
+System(teBridge, "DIF \n Credential Trust Establishment \nBridge","[CTE]")
+
+System(oidcBridge, "OIDF Bridge")
+System(oidfData,"Federation","OIDF\nProfile 1")
+System(oidfDataN,"Federation","OIDF\nProfile N")
+Rel(Integrator, oidcBridge,"TRQP")
+Rel(oidcBridge,oidfData,"OIDF\nProfile 1")
+Rel(oidcBridge,oidfDataN,"OIDF\nProfile N")
+
+System(TRAIN, "TRAIN") 
+Rel(Bridge, TRAIN,"bridges")
+
+
+
 System(EUTrustedList, "EU Trusted List")
-System(NativeSupport, "SystemX"," w Native TRP Support")
+System(NativeSupport, "SystemX"," w Native TRQP Support")
 
-System(OpenDataBridge, "OpenData Bridge")
 
 
-Rel(Integrator, Bridge, "TRP")
-Rel(Bridge, TRAIN,"bridges")
+System(teFile, "CTE file")
+
+Rel(teBridge, teFile,"processes")
+
+Rel(Integrator, Bridge, "TRQP")
+Rel(Integrator, teBridge, "TRQP")
+
+
 Rel(Bridge, EUTrustedList, "bridges")
 
-Rel(Integrator, OpenDataBridge,"TRP")
-Rel(OpenDataBridge,NativeSupport,"ODPS")
 
-Rel(Integrator, NativeSupport,"TRP")
+' System(OpenDataBridge, "OpenData Bridge")
+' Rel(Integrator, OpenDataBridge,"TRQP")
+' Rel(OpenDataBridge,NativeSupport,"ODPS")
+
+Rel(Integrator, NativeSupport,"TRQP")
 
 
 

spec/annex.md

@@ -33,24 +33,24 @@ The OpenAPI Specification (v3.1.0) is the first "concrete" API specification.
 
 It is provided as an Open API Specification v3 YAML file. 
 
-[OAS (.yaml) for TRP v2](../api/toip-tswg-trustregistryprotocol-v2.yaml). 
+[OAS (.yaml) for TRQP v2](https://github.com/trustoverip/tswg-trust-registry-protocol/blob/main/api/toip-tswg-trustregistryprotocol-v2.yaml). 
 
 There are several renderings of the OAS specification:
 
 * Inline - this rendering is managed in this repository [Redoc Rendering (static HTML) of specification](./api/redoc-static.html)
-* SwaggerHub - this rendering is manually updated from time to time and may be out of date: [SwaggerHub](https://app.swaggerhub.com/apis/CULedger/CULedger.Identity/0.3.1-oas3.1) 
+* SwaggerHub - this rendering is manually updated from time to time and may be out of date: [SwaggerHub](https://app.swaggerhub.com/apis-docs/continuumloop/trust-over_ip_trust_registry_protocol_res_tful_api_v_2/2.0.0) 
 
 
 ## Annex C - Uses and Data Model Reference
 
-### Use of the Trust Registry Protocol.
+### Use of the Trust Registry Query Protocol.
 
-The TRP is intended to be used in at least two key ways:
+The TRQP is intended to be used in at least two key ways:
 
-* Native Support - systems may directly implement access using the TRP.
-* Bridged - systems may create access "bridges" that provide TRP access to their systems.
+* Native Support - systems may directly implement access using the TRQP.
+* Bridged - systems may create access "bridges" that provide TRQP access to their systems.
 
-![C4 Systems Model - showing native TRP support on one system, bridged support to two other systems (e.g. TRAIN and EU Trusted List ARF)](./images/puml/protocol-bridging.png).
+![C4 Systems Model - showing native TRQP support on one system, bridged support to two other systems (e.g. TRAIN and EU Trusted List ARF)](./images/puml/protocol-bridging.png).
 
 
 ### Object Model
@@ -63,5 +63,5 @@ We provide a high-level object model (NOTE: source of truth is the Swagger as th
 
 We will need to provide guides and other thought pieces that explain many aspects of trust registries. A notional (short bullet) list of items could include:
 * "why do I need a trust registry?" - blog article or position paper to explain why trust registries help.
-* "I have the data, but how do I use the TRP?" - paper about how adding TRP to a bridge or native integration.
+* "I have the data, but how do I use the TRQP?" - paper about how adding TRQP to a bridge or native integration.
 * "where do I learn about the governance changes that I have?"

spec/foreword.md

@@ -13,11 +13,11 @@ The usefulness of an ecosystem is largely dependant on its ability to assert tru
 The term [[ref:trust]] is loaded with varied meanings that may conflict. In the context of trust registries we want to be clear what we mean, when we apply the term “trust”. A trust registry does not create trust by itself. The decision for one entity to “trust” another is each party's own decision. The purpose of the trust registry is to provide access to a system of record that contains answers to questions that help drive those trust decisions.
 
 A trust registry may provide information that helps the [[ref:consuming party]] in deciding that an entity is [[ref:trustworthy]]. 
-The ToIP Trust Registry Protocol helps ecosystems create the foundation of trust within its governed domain, by providing a common protocol for querying information that helps the consuming party in deciding that an entity is [[ref: trustworthy]].
+The ToIP Trust Registry Query Protocol helps ecosystems create the foundation of trust within its governed domain, by providing a common protocol for querying information that helps the consuming party in deciding that an entity is [[ref: trustworthy]].
 
-In addition to providing information on its own ecosystem, the Trust Registry Protocol (TRP) enables creation of a registry of registries. This is done by allowing an ecosystem to assert trust to other trust registries, and thus ecosystems. This can be achieved by allowing a governance entity to assert that consuming parties that rely on the trust registry, may also utilize information from another trust registry for additional assertions. This effectively creates transitive trust across ecosystems to achieve wider reach.
+In addition to providing information on its own ecosystem, the Trust Registry Query Protocol (TRQP) enables creation of a registry of registries. This is done by allowing an ecosystem to assert trust to other trust registries, and thus ecosystems. This can be achieved by allowing a governance entity to assert that consuming parties that rely on the trust registry, may also utilize information from another trust registry for additional assertions. This effectively creates transitive trust across ecosystems to achieve wider reach.
 
-The Trust Registry Protocol serves to provide a simple interface to enable querying of systems of record that provide the information that drives a trust registry. There are a plethora of systems that contain answers that are required to make trust decisions. The protocol is intended to make the communication with any particular system-of-record consistent and simple.
+The Trust Registry Query Protocol serves to provide a simple interface to enable querying of systems of record that provide the information that drives a trust registry. There are a plethora of systems that contain answers that are required to make trust decisions. The protocol is intended to make the communication with any particular system-of-record consistent and simple.
 
 ## Foreword
 This specification is subject to the **OWF Contributor License Agreement 1.0 - Copyright** available at

spec/introduction.md

@@ -16,25 +16,25 @@ We need answers to a simple question:
 
 > Does `Entity X` have `Authorization Y`, in the context of `Ecosystem Governance Framework Z`?
 
-The Trust Registry Protocol (TRP) serves to provide a simple interface to enable querying of systems of record that provide the information that drives a trust registry. There are a plethora of systems that contain answers that are required to make trust decisions. The protocol is intended to make the communication with any particular system-of-record consistent and simple.
+The Trust Registry Quert Protocol (TRQP) serves to provide a simple interface to enable querying of systems of record that provide the information that drives a trust registry. There are a plethora of systems that contain answers that are required to make trust decisions. The protocol is intended to make the communication with any particular system-of-record consistent and simple.
 
 It is intentionally simple to allow rapid integration into external systems.
 
-The TRP does not:  
+The TRQP does not:  
   * create a trust registry - it allows (read-only) access to a system-of-record that has the data needed to generate answers that a trust registry provides.
   * create new information - the Create, Update, and Delete of CRUD are not supported. Systems-of-record perform the full CRUD operations. The protocol provides a simple and consistent way of retrieving information from a system.
-  * create nor implement governance - the system-of-record that supports the TRP may have technical ways of doing this, supported by manual operations. Regardless, the TRP has no opinion on how governance is implemented - just that the information retrieved complies with the stated EGF.
-  * make decisions - the TRP serves up data that are inputs to trust decisions.
-  * assign Roles or Rights, though a consuming system may take information that is received via the TRP and assign these.
+  * create nor implement governance - the system-of-record that supports the TRQP may have technical ways of doing this, supported by manual operations. Regardless, the TRQP has no opinion on how governance is implemented - just that the information retrieved complies with the stated EGF.
+  * make decisions - the TRWP serves up data that are inputs to trust decisions.
+  * assign Roles or Rights, though a consuming system may take information that is received via the TRQP and assign these.
 
 It is most crucial to understand that a Trust Registry does NOT create authority. The authority of a trust registry is an outcome of governance.
 
 The purpose of this [[xref: TOIP, ToIP specification]] is to define a standard interoperable protocol for querying a global web of [[xref: TOIP, peer]] [[xref: TOIP, trust registries]], each of which can answer queries about whether a particular [[xref: TOIP, entity]] holds an [[ref:authorization]], in a particular [[xref: TOIP, digital trust ecosystem]] (defined under an [[xref: TOIP, EGF]]), as well as which peer trust registries acknowledge each other.
 
-### Trust Registry Protocol features
+### Trust Registry Query Protocol features
 A core role within the ToIP stack is a [[xref: TOIP, trust registry]]. This is a network service that enables the [[xref:TOIP, governing authority]] for an [[xref: TOIP, EGF]] to share information about their ecosystem. In particular, which [[xref: TOIP, governed parties]] hold which [[ref: authorizations]] under the EGF.
 
-A trust registry protocol thus should provide the following features:
+A trust registry query protocol thus should provide the following features:
 
 1. interface to query if a particular [[xref: TOIP, entity]] holds specific [[ref:authorization]] under a defined [[xref: TOIP, EGF]]? 
   - e.g.  "Does entity X hold the authorization of `canada.driver.license.issue` under Canadian Driver's license scheme?" 
@@ -43,11 +43,11 @@ A trust registry protocol thus should provide the following features:
 ### Read-only query Protocol
 The primary question (Does `Entity X` have `Authorization Y`, in the context of `Ecosystem Governance Framework Z`) we need an answer to when working in an ecosystem is in itself a simple query. Furthermore, it is read-only query and it doesn't modify any information in a system of record. It just makes data available.
 
-In the web service world the TRP is purely a GET protocol. 
+In the web service world the TRQP is purely a GET protocol. 
 
-Just as important it is to understand what the Trust Registry Protocol does NOT do. The TRP does NOT:
-* affect the operations and governance of the systems that support querying using the TRP.
-* create, update, or delete data in a system. In web services this means the TRP does to PUT, POST, DELETE, and other non-GET operations.
+Just as important it is to understand what the TRQP does NOT do. The TRQP does NOT:
+* affect the operations and governance of the systems that support querying using the TRQP.
+* create, update, or delete data in a system. In web services this means the TRQP does to PUT, POST, DELETE, and other non-GET operations.
 
 As with all layers of the [[xref: TOIP, ToIP stack]], the purpose of a [[xref: TOIP, ToIP specification]] is to enable the technical interoperability necessary to support transitive trust within and between different [[xref: TOIP, trust communities]] implementing the [[xref: TOIP, ToIP stack]]. In this case, the desired interoperability outcome is a common query protocol that works between any number of decentralized peer trust registries operated by independent governing authorities** representing multiple legal and business jurisdictions.