Merge pull request #39 from a-fox/issue-34

Restructuring & new intro

spec/foreword.md

@@ -7,62 +7,31 @@
 
 [//]: # (\newpage)
 
+## Scope
+The usefulness of an ecosystem is largely dependant on its ability to assert trust for and between its members. This is true for traditional ecosystems, but even more so with digital ecosystems. With the growing trend on decentralisation of digital services, we are also seeing increased need to transitively assert trust across ecosystems. 
 
-## Foreword
-
-ToIP (Trust Over IP Foundation) create a _____ 
-
-::: todo 
-Preamble along the lines of an ISO Foreword.
-:::
-
-List significant changes (non-normative):
-
-* Shift away from a pure Issuer/Holder/Verifier approach to support non-credential use cases.
-* Addition of namespacing concep to begin normalization of trust registries naming conventions.
-* Enrichment of registry-of-registry concept to allow for registries that focus primarily on providing a list of registries.
+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.
 
-### On Trust, Trustworthy, and Trustworthiness
+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 term [[ref:trust]] is loaded with varied meanings that often conflict. In the context of [[ref:trust registries]] we need to establish the scope of what we are talking about when we apply the term "trust" to trust registires. There are baseline definitions that follow this limiting scope. 
+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.
 
-A trust registry does not create trust. The decision for one entity to "trust" another is their decision. A trust registry may provide information that helps the *consuming party*  in deciding that an entity is [[ref: trustworthy]]. 
-
-::: todo 
-  define term "*consuming party*" - OR find better term and capture definition.
-
-
-### Copyright Notice
+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.
 
+## Foreword
 This specification is subject to the **OWF Contributor License Agreement 1.0 - Copyright** available at
 [https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright).
 
 If source code is included in the specification, that code is subject to the Apache 2.0 license unless otherwise marked. In the case of any conflict or confusion within this specification between the OWF Contributor License and the designated source code license, the terms of the OWF Contributor License shall apply.
 
 These terms are inherited from the Technical Stack Working Group at the Trust over IP Foundation. [Working Group Charter](https://trustoverip.org/wp-content/uploads/TSWG-2-Charter-Revision.pdf)
 
-
-### Terms of Use
-
-These materials are made available under and are subject to the [OWF CLA 1.0 - Copyright & Patent license](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright-and-patent). Any source code is made available under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.txt).
-
 THESE MATERIALS ARE PROVIDED “AS IS.” The Trust Over IP Foundation, established as the Joint Development Foundation Projects, LLC, Trust Over IP Foundation Series ("ToIP"), and its members and contributors (each of ToIP, its members and contributors, a "ToIP Party") expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. 
 
 IN NO EVENT WILL ANY ToIP PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THESE MATERIALS, ANY DELIVERABLE OR THE ToIP GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-### Introduction
-
-*This section is non-normative*
-
-A [[ref: trust registry]] is a resource that helps to bind governance (business, legal, and social mandates) for an ecosystem. A trust registry helps get the main answers that parties inside and outside of the ecosystem need to tie the governance into their own systems - both technically (it is a protocol) and on a governance (the information provided is created via a governed process).
-
-It is crucially important to understand that a trust registry does not create trust, nor the conditions for trust, by itself. Trust and belief in the data provided by a trust registry is an outcome of governance. 
-
-We need answers to a simple question:
-
-> Does `Entity X` have `Authorization Y`, in the context of `Ecosystem Governance Framework Z`?
+
+### Conventions
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
 
 
-[[def: trustworthiness]]
-~ An attribute of a person or organization that provides confidence to others of the qualifications, capabilities, and reliability of that entity to perform specific tasks and fulfill assigned responsibilities. Trustworthiness is also a characteristic of information technology products and systems (see Section 2.6.2 on trustworthiness of information systems). The attribute of trustworthiness, whether applied to people, processes, or technologies, can be measured, at least in relative terms if not quantitatively.48 The determination of trustworthiness plays a key role in establishing trust relationships among persons and organizations. The trust relationships are key factors in risk decisions made by senior leaders/executives. NOTE: Current state-of-the-practice for measuring trustworthiness can reliably differentiate between widely different levels of trustworthiness and is capable of producing a trustworthiness scale that is hierarchical between similar instances of measuring activities (e.g., the results from ISO/IEC 15408 [Common Criteria] evaluations). 
-- source: [NIST Special Publication 800-39](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-39.pdf) p.24

spec/introduction.md

@@ -1,14 +1,67 @@
 
 [//]: # (Pandoc Formatting Macros)
 
-[//]: # (::: introtitle)
+[//]: # (\mainmatter)
 
-[//]: # (Introduction)
-
-[//]: # (:::)
+[//]: # (\doctitle)
 
 ## Introduction
+*This section is non-normative*
+
+A [[ref: trust registry]] is a resource that helps to bind governance (business, legal, and social mandates) for an ecosystem. A trust registry helps get the main answers that parties inside and outside of the ecosystem need to tie the governance into their own systems - both technically and on a governance (the information provided is created via a governed process).
+
+It is crucially important to understand that a trust registry does not create trust, nor the conditions for trust, by itself. Trust and belief in the data provided by a trust registry is an outcome of governance. 
+
+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.
+
+It is intentionally simple to allow rapid integration into external systems.
+
+The TRP 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.
+
+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
+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:
+
+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?" 
+2. interface to query what other trust registries are recognized by this trust registry?
+
+### 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. 
+
+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.
+
+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.
+
+### Registry of Registries
+A Registry of Registries (RoR), is a form of [[xref: TOIP, trust registry]] that primarily serves information about other [[xref: TOIP, trust registries]]. 
+
+1. What other [[xref: TOIP, governing authorities]] are known to the RoR. 
+2. Which [[xref: TOIP, trust registry]] are known to be authoritative for particular actions. Examples:
+	- Which trust registry is known to issue university diplomas for a particular jurisdiction?
+  - Which trust registry is known to manage a list of professionals (e.g. CPAs, lawyers, engineers) that have particular signing rights (authorizations)?
+3. Which [[xref: TOIP, trust registry]] are known to operate under a given [[xref: TOIP, EGF]].
+
+The results on a [[xref: TOIP, trust decision]] based on input from a trust registry may range from:
+* immediate decision that the entity meets or cannot meet the full requirement of the [[ref:trust relationship]]; or
+* further input is required before trust decision can be made. 
 
-::: todo 
-create introduction
-:::
+These decisions relate to a determination that a relationship is (or is not) sufficiently [[ref: trustworthy]] to establish a [[ref: trust relationship]]. To reach that determination, each party may have its own way of determining the [[ref: trustworthiness]] of their counterparty for the [[ref: trust relationship]] that they require.