major updates - still WIP

Signed-off-by: Darrell O'Donnell <[email protected]>

PATENT_LICENSING.md

@@ -6,7 +6,9 @@
 
 
 1.  The Purpose of this Agreement.  This Agreement sets forth the terms under which I make certain patent rights available to you for your Permitted Uses of the Specification.  Capitalized terms are defined in the Agreement’s last section.
+
 2. Patents.
+
 2.1.   Patent Non-Assert.
 
 2.1.1. The Promise.  I, on behalf of myself and my successors in interest and assigns, irrevocably promise not to assert my Granted Claims against you for your Permitted Uses, subject to the terms and conditions of Section 2.1.  This is a personal promise directly from me to you, and you acknowledge as a condition of benefiting from it that no rights from me are received from suppliers, distributors, or otherwise in connection with this promise. This promise also applies to your Permitted Uses of any other specifications incorporating all required portions of the Specification.
@@ -21,8 +23,8 @@
 
 2.1.4. Bankruptcy.  Solely for purposes of Section 365(n) of Title 11, United States Bankruptcy Code and any equivalent law in any foreign jurisdiction, this promise will be treated as if it were a license and you may elect to retain your rights under this promise if I (or any owner of any patents or patent applications referenced herein), as a debtor in possession, or a bankruptcy trustee, reject this non-assert.
 
-2.2.  Patent License Commitment.  In addition to rights granted in 2.1, on behalf of me and my successors in interest and assigns, I agree to grant to you a no charge, royalty free license to my Granted Claims on reasonable and non-discriminatory terms, where such license applies only to those Granted Claims infringed by the implementation of the Specification, solely for your Permitted Uses.
- 
+2.2.  Patent License Commitment.  In addition to rights granted in 2.1. on behalf of me and my successors in interest and assigns, I agree to grant to you a no charge, royalty free license to my Granted Claims on reasonable and non-discriminatory terms, where such license applies only to those Granted Claims infringed by the implementation of the Specification, solely for your Permitted Uses.
+
 3.  No Other Rights. Except as specifically set forth in this Agreement, no other express or implied patent, trademark, copyright, or other property rights are granted under this Agreement, including by implication, waiver, or estoppel.
 
 4.  Antitrust Compliance.  I acknowledge that I may compete with other participants, that I am under no obligation to implement the Specification, that each participant is free to develop competing technologies and standards, and that each party is free to license its patent rights to third parties, including for the purpose of enabling competing technologies and standards.

api/toip-tswg-trustregistryprotocol-v2.yaml

@@ -432,8 +432,6 @@ components:
 
       default:
         description: Generic Error
-  schemas:
-
     Uri:
       type: string
       format: uri

spec/annex.md

@@ -9,7 +9,7 @@
 
 [//]: # (With some more text)
 
-##  Appendix A: Consolidated Requirements
+##  Annex A: Consolidated Requirements
 
 For ease of reference, the following table consolidates all normative requirements in this specification. Each requirement is linked to the section in which it appears.
 
@@ -27,7 +27,7 @@ TODO: Finalize table once requirements (earlier).
 |A.3.2| The [ToIP Governance Architecture Specification](https://wiki.trustoverip.org/pages/viewpage.action?pageId=71241). Note that this includes the requirement that the **EGF** and all **governed parties** (which includes **authorized issuers** and **authorized verifiers**) |[LINK]|
 
 
-## Appendix B: OpenAPI Specification
+## Annex B: OpenAPI Specification
 
 The OpenAPI Specification (v3.0.1) is the first "concrete" API specification. 
 
@@ -38,3 +38,20 @@ It is provided as an Open API Specification v3 YAML file.
 [Redoc Rendering (static HTML) of specification](../api/redoc-static.html)
 
 
+## Annex C - Uses and Data Model Reference
+
+### Use of the Trust Registry Protocol.
+
+The TRP 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.
+
+![C4 Systems Model - showing native TRP support on one system, bridged support to two other systems (e.g. TRAIN and EU Trusted List ARF)](../out/diagrams/protocol-bridging/protocol-bridging.png).
+
+
+### Object Model
+
+We provide a high-level object model (NOTE: source of truth is the Swagger as this diagram may be out of date during development)
+
+![High Level Object Model](../out/diagrams/highlevel/highlevel.png)

spec/foreword.md

@@ -6,3 +6,17 @@
 [//]: # (:::)
 
 [//]: # (\newpage)
+
+
+## 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.
+

spec/header.md

@@ -1,11 +1,52 @@
-## Status of This Memo
 
+[//]: # (Pandoc Formatting Macros)
+
+[//]: # (::: headertitle)
+
+[//]: # (Header)
+
+[//]: # (:::)
+
+## Draft Specification
+
+### Source
+
+The following links will be helpful for editors and reviewers during the DRAFT stage.
+
+* Source Code - [https://github.com/trustoverip/tswg-trust-registry-protocol](https://github.com/trustoverip/tswg-trust-registry-protocol)
+* Rendered Specification (github.io Pages) - [https://trustoverip.github.io/tswg-trust-registry-protocol/](https://trustoverip.github.io/tswg-trust-registry-protocol/) 
+
+### Editors
+
+- [Darrell O'Donnell](https://github.com/darrellodonnell), [Continuum Loop Inc.](https://continuumloop.com/)
+
+### Contributors
+
+To comply with the intellectual property rights protections in[ the charter of the ToIP Foundation](https://docs.google.com/document/d/1hJ4YWH_efrYTRvzRI1N9YHwhUOyI_ScrPmI1D9T4_oc/edit?usp=sharing) (as required by all Joint Development Foundation projects hosted by the Linux Foundation), all contributors in any capacity to this Draft Deliverable MUST be current members of the ToIP Foundation. The following contributors each certify that they meet this requirement:
+
+* Antti 
+* Andor
+* Jacques Latour, CIRA
+* Christine Martin, Continuum Loop Inc.
+
+- 
+
+### Participate 
+**[[SECTION will be removed before going to Review]]**
+
+Participation is welcome. 
+
+* [GitHub repo](https://github.com/trustoverip/tswg-trust-registry-protocol)
+* [Trust Registry Task Force](https://wiki.trustoverip.org/display/HOME/Trust+Registry+Task+Force)
+* [Commit history](https://github.com/trustoverip/tswg-trust-registry-protocol/commits/main)
+
+------------------------------------
 This document contains a specification for the ToIP Trust Registry Protocol.
 
 Information about the current status of this document, any errata, and how to provide feedback on it, may be obtained at
 [https://github.com/trustoverip/tswg-trust-registry-protocol](https://github.com/trustoverip/tswg-trust-registry-protocol).
 
-## Copyright Notice
+### Copyright Notice
 
 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).
@@ -15,33 +56,10 @@ If source code is included in the specification, that code is subject to the Apa
 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
+### 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.
-
-## RFC 2119
-The Internet Engineering Task Force (IETF) is a large open international community of network designers, operators, vendors, and researchers concerned with the evolution of the Internet architecture and to ensure maximal efficiency in operation. IETF has been operating since the advent of the Internet using a Request for Comments (RFC) to convey “current best practice” to those organizations seeking its guidance for conformance purposes.
-
-The IETF uses RFC 2119 to define keywords for use in RFC documents; these keywords are used to signify applicability requirements.  ToIP has adapted the IETF RFC 2119 for use in the <name of this document>, and therefore its applicable use in ToIP-compliant governance frameworks.
 
-The RFC 2119 keyword definitions and interpretation have been adopted. Those users who follow these guidelines SHOULD incorporate the following phrase near the beginning of their document:
-        The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
-
-RFC 2119 defines these keywords as follows:
-
- * MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
- * MUST NOT: This phrase, or the phrase "SHALL NOT", means that the definition is an absolute prohibition of the specification.
- * SHOULD: This word, or the adjective "RECOMMENDED", means that there MAY exist valid reasons in particular circumstances to ignore a particular item, but the full implications MUST be understood and carefully weighed before choosing a different course.
- * SHOULD NOT: This phrase, or the phrase "NOT RECOMMENDED" means that there MAY exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications SHOULD be understood, and the case carefully weighed before implementing any behavior described with this label.
- * MAY: This word, or the adjective "OPTIONAL", means that an item is truly optional.  One vendor MAY choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor MAY omit the same item.
-
-Requirements include any combination of Machine-Testable Requirements and Human-Auditable Requirements. Unless otherwise stated, all Requirements MUST be expressed as defined in RFC 2119.
-
- * Mandatories are Requirements that use a MUST, MUST NOT, SHALL, SHALL NOT or REQUIRED keyword.
- * Recommendations are Requirements that use a SHOULD, SHOULD NOT, or RECOMMENDED keyword.
- * Options are Requirements that use a MAY or OPTIONAL keyword.
-
-An implementation which does not include a particular option MUST be prepared to interoperate with other implementations which include the option, recognizing the potential for reduced functionality. As well, implementations which include a particular option MUST be prepared to interoperate with implementations which do not include the option and the subsequent lack of function the feature provides.
+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.

spec/introduction.md

@@ -9,4 +9,4 @@
 
 ## Introduction
 
-Fancy introduction!
+TODO: create Introduction

spec/normative_references.md

@@ -10,44 +10,14 @@
 
 [//]: # (:::)
 
-* [W3C Decentralized Identifiers (DIDs) v1.0 (DID Core)](https://www.w3.org/TR/did-core/)
 * [ToIP Governance Architecture Specification](https://wiki.trustoverip.org/pages/viewpage.action?pageId=71241)
+* 
+*  
 
-## Terms & Definitions
+TODO: Finish up alignging with `spec-up` spec linkging
 
-[[def: assurance levels]]
-~ TODO: 
+[[spec-norm]]
 
-[[def: authorization]]
-~ an acknowlegement by the responding system that an entity has (or does not have) is authorized to conduct for a particular [[ref: action]] at the time of query.
-
-[[def:authorized trust registries]]
-~ The primary trust registry plus all secondary trust registries are collectively referred to as the authorized trust registries.
-
-[[def: action]]
-~ a discrete property (string) that an entity can be authorized for, in the form of an [[ref: authorization]] response.
-
-[[def: action namespace]]
-~ A well-known string that is used in an EGF to indicate a discrete authorization. Examples (non-exhaustive): "canada:driver-license", "eu:trusted-list.authorized-timestamp", "global:tsm"
-
-[[def: ecosystem governance framework, ecosystem governance frameworks, EGF]]
-~ TODO: replace this ChatGPT definiton: refers to a structured set of principles, rules, and mechanisms that guide and regulate the management and decision-making processes within an ecosystem. Ecosystem governance is typically associated with natural or environmental systems, where various stakeholders, such as governments, communities, businesses, and non-governmental organizations, work together to sustainably manage and protect ecosystems.
-
-[[def: registered entity]]
-~ An entity that is listed in the system (i.e. the [[ref: trust registry]]) that is being queried. 
-
-[[def: primary trust registry]]
-~ TODO:
-
-[[def:secondary trust registry, secondary trust registries]]
-~ TODO: 
-
-[[def: trust list]]
-~ A one-dimensional trust graph in which an authoritative source publishes a list of entities that are trusted in a specific trust context. A trust list can be considered a simplified form of a trust registry.
-
-[[def: trust registry]] 
-~ A registry that serves as an **authoritative source** for **trust graphs** or other **governed information** describing one or more **trust communities**. A trust registry is typically **authorized** by a **governance framework**.  See also: trust list
-
-[[def: VID Type]]
-~ TODO: 
+### Non-Normative/Informative References
 
+[[spec-inform]]

spec/requirements.md

@@ -78,7 +78,7 @@ TODO: Add normative ref to [ToIP Governance Architecture Specification](https://
 
 ### Trust Registry Service Property [TRSP-*] 
 
-The **DID document** for the **DID** that identifies an **EGF** compliant with this specification MUST include a service property that meets the **requirements** [in section 5.4 of the W3C Decentralized Identifiers (DIDs) 1.0 specification](https://www.w3.org/TR/did-core/#services) plus the following additional **requirements**:
+The **DID document** for the **DID** that identifies an **EGF** compliant with this specification MUST include a service property that meets the **requirements** in section 5.4 of [[spec-norm:DID-CORE]] plus the following additional **requirements**:
 
 * The value of the `type` property MUST be `TrustRegistry`.
 * The value of the `serviceEndpoint` property MUST be exactly one HTTPS URI.
@@ -118,7 +118,7 @@ The authoritative technical specifications for the API calls in the ToIP Trust R
         - a. The value labels MUST be:
             - i. `AuthorizationStartDate`
             - ii. `AuthorizationEndDate`
-        - b. The values MUST be formatted to comply with [RFC 3339](https://tools.ietf.org/html/rfc3339) in the UTC/Z time zone with no offset.
+        - b. The values MUST be formatted to comply with [[spec-norm:RFC3339]] in the UTC/Z time zone with no offset.
         - c. The `AuthorizationStartDate` MUST be the date that the **registered party’s** authorization began.
         - d. The `AuthorizationEndDate` MUST be either:
             - i. `Null` for an entry whose **status value** is `Current` at the time of the query.

spec/revision_history.md

@@ -1,10 +1,8 @@
-## Revision History
+### Revision History
+
+[[This section applies after the specification has been released for a public review]].
 
 The following key revisions have been made to this specification:
 
-- JAN2023 
-  - Created a clean repository to accomplish several goals:
-    - **Clearly delineate v1.0 and v2.0** - move from the [Trust Registry Task Force repository](https://github.com/trustoverip/tswg-trust-registry-tf) to [Trust Registry Protocol v2](https://github.com/trustoverip/tswg-trust-registry-protocol) repository.
-  clean repository.
-    - **Use Trust Over IP Specification Template** - applied the `spec-up` template from the [Trust Over IP Specification Template](https://github.com/trustoverip/specification-template) repository.
-  - 
+- DATE (e.g. month)
+  - Key changes only (reviewer can see github commits for full evolution)

spec/scope.md

@@ -39,18 +39,4 @@ A Registry of Registries (RoR), is a form of **trust registry** that primarily s
   - Which trust registry is known to manage a list of professionals (e.g. CPAs, lawyers, engineers) that have particular signing rights (authorizations)?
 3. Which **trust registry** are known to operate under a given **EGF**.
 
-### Use of the Trust Registry Protocol.
 
-The TRP 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.
-
-![C4 Systems Model - showing native TRP support on one system, bridged support to two other systems (e.g. TRAIN and EU Trusted List ARF)](../out/diagrams/protocol-bridging/protocol-bridging.png).
-
-
-### Object Model
-
-We provide a high-level object model (NOTE: source of truth is the Swagger as this diagram may be out of date during development)
-
-![High Level Object Model](../out/diagrams/highlevel/highlevel.png)