Update documentation to match 1.5.8. (#176)

Given the final decisions for L1 and L2 APIs defined in 1.5.8 of the
specification, this PR cleans up the class diagram and some
requirements specifications.

README.adoc

@@ -21,95 +21,27 @@ SPDX-FileType: DOCUMENTATION
 SPDX-License-Identifier: Apache-2.0
 ----
 
-== Purpose
+== Overview
 
-A software defined vehicle requires the design and development of software entities that are distributed by nature, deployed in different os/hw environments (mechatronics, high-compute, mobile phones, and the cloud).
+uProtocol is a communication protocol that enables software (uEs) to easily communicate with each other running in distributed systems. The protocol is designed to be lightweight, efficient, easy to use, and run on top of any other communication middleware (transport) such as SOME/IP, MQTT, zenoh, HTTP, etc...
 
-Every environment have their own software development, deployment, and communications protocols, thus resulting in no common interface,language or means for said distributed software to seamlessly discover, connect, and communicate with each other in a transparent, simplified, and secure manner.
+To achieve the above mentioned objectives, we have split the specifications into sections (folders) that are:
 
-uProtocol addresses the above-mentioned problem by defining an ubiquitous language that includes:
+ * link:basics/README.adoc[*The Basics:*] Foundational principles and concepts of uProtocol (ex. such as addressing, IDs, message header definitions, etc...). 
 
-1. Transport layer interface: Common way to  `send()` and `receive()` messages regardless of the underlining networking transport protocol
+ * link:up-l1/README.adoc[*Transport layer (uP-L1):*] Common interface for sending and receiving of messages intended to be implemented employing a particular communication middleware technology (ex. MQTT, SOME/IP, HTTP, Zenoh, etc...).
 
-2. Common Message Definitions
+ * link:up-l2/[*Communication Layer (uP-L2):*] The common transport agnostic, programming language specific, API for the publisher/subscriber, notification, and RPC messaging patterns used by application/service developers to communicate with each other.
 
-3. Common application layer interfaces for core business logic (ex. subscription management, discovery, etc...)
+* link:up-l3/[*Application Layer (uP-L3):*] Service contracts for subscription management, service/device discovery, and event caching that is common across all deployments (implementations) of uProtocol.
 
-<<img-overview>> image below provides a high-level view of what we aim to define in this specification. The arrows between the uEs are the physical/virtual transport (anything from OSI layer 2 protocol up to automotive/Internet application layer protocols, and everything in-between. The icon image:https://cloudevents.io/img/logos/cloudevents-icon-color.png[CloudEvents,25,35] represents the messages sent between uEs that, for the remainder of this document, referred to as CloudEvents or CEs.
 
+== How to get started?
 
-.uProtocol Overview
-[#img-overview]
-image::overview.drawio.svg[Overview]
+It is always best to start with link:basics/README.adoc[_the basics_] to familiarize yourself with common terminology used with uProtocol. 
 
+If you're a developer who would like to use uProtocol in your application or service, please refer to the appropriate language library (ex. up-cpp, up-java, up-rust, etc..) `README.adoc`. 
 
+If you would like to contribute to uProtocol to develop a new language library or transport implementation, please checkout the link:CONTRIBUTING.adoc[CONTRIBUTING.adoc].
 
-== link:basics/README.adoc[The Basics]
-In this section of the specifications we cover the foundations of uProtocol such as CloudEvents, UUIDs, naming conventions and more.
 
-
-== Layers
-
-.uProtocol Layers
-[#img-layers]
-image::layers.drawio.svg[uProtocol Layers]
-
-uProtocol consists of three layers as depicted in <<img-layers>> above, they are:
-
-1. link:up-l1/[*Transport & Session Layer (uP-L1):*] Bidirectional point-2-point communication between uEs (how messages are sent and received between uEs).
-
-2. link:up-l2/[*Communication (Messaging) Layer (uP-L2):*] Defines the message types, headers, format, and delivery semantics
-
-3. link:up-l3/[*Application Layer (uP-L3):*] Also known as the business logic layer, responsible for declaration and definition of interfaces between clients and servers (ex. subscription management, discovery, etc...)
-
-
-== Software Entities (uEs)
-A uE is software that communicates with other software using uProtocol.
-
-<<img-ues>> below illustrates the set of uProtocol defined uEs required to implement the protocol.
-
-.uE Classifications
-[#img-ues]
-image::ues.drawio.svg[uEs]
-
-=== Communication Backbone
-
-uEs in this category are essential for dispatching/routing of messages between uEs, uDevices, and uDomains.
-
-.Communication uEs
-[width=100%",cols="30%,70%"]
-|===
-|uE Name |Description
-
-|link:up-l2/dispatchers/README.adoc[*Dispatchers*]
-|Message dispatches sending CEs between uEs, between devices, etc...
-
-|link:up-l3/usubscription/v3/README.adoc[*uSubscription*]
-|Implement the publisher/subscriber architecture pattern within and between devices. Used by dispatchers to multicast messages to subscribers
-
-|===
-
-=== Core uEs
-Core uEs are business layer logic to perform a specific function of the protocol highlighted in the table below.
-
-.Core uEs
-[width=100%",cols="30%,70%"]
-|===
-|uE Name |Description
-
-|link:up-l3/udiscovery/v3/README.adoc[*uDiscovery*]
-|Discovery (services, devices, topics, methods, properties, etc...)
-
-|link:up-l3/utwin/v2/README.adoc[*uTwin*]
-|Local (to the device) caches of published information for subscribed topics
-
-|===
-
-=== Topology
-<<img-topology>> below illustrates what a uProtcol topology consists of when all the uEs connected together.
-
-.Topology
-[#img-topology]
-image::platform_ues.drawio.svg[uProtocol Topology]
-
-NOTE: Please see link:principles.adoc[Guiding Principles] for more information about motivations and high-level requirements/principles driving the specification

languages.adoc

@@ -18,88 +18,82 @@ SPDX-FileType: DOCUMENTATION
 SPDX-License-Identifier: Apache-2.0
 ----
 
-== Overview
+== Overview 
 
-Language specific uProtocol libraries (_the library_) implement the data model defined in link:../basics/README.adoc[uProtocol Basic Types] in a particular programming language like Java, Rust or C/C++. A library also provides helpers for validating data model instances, serializing UUris to a textual representation as well as builders for correctly instantiating more complex data types. Each library includes the language specific declaration of the abstract interfaces defined in uProtocol link:../up-l1/README.adoc[Layer 1] and link:../up-l2/README.adoc[Layer 2].
+uProtocol Language specific libraries (_libraries_) are written for a given programming language (ex. Java, C++, etc...) to implement the protocol and are the primary library that is used by applications and services (uEs) to communicate with other uEs. The _libraries_ declare the API for the uProtocol Transport Layer (uP-L1) and implement the uProtocol Communication Layer API (uP-L2).
 
-NOTE: All libraries *MUST* be made available under a permissive (OSS) license like Apache 2.0 or MIT and *MUST* be hosted under the https://github.com/eclipse-uprotocol[Eclipse uProtocol GitHub Organization].
 
-== Source Code Structure
+== Requirements
 
-The following sections define the content and structure of these libraries.
+=== Content
 
-* The root namespace (package name) *MUST* be `org.eclipse.uprotocol`
-* Modules defined in table <<content>> below *MUST* be implemented in their own folder (namespace)
-* Each module *SHOULD* separate the implementation of the specification as defined in table <<folders>> below.
+[.specitem,oft-sid="req~up-language-api~1",oft-needs="impl,utest"]
+--
+* *MUST* implement serializers, validators, and builders for the link:../basics/README.adoc[uProtocol data types] using the link:../up-core-api/README.adoc[up-core-api data model].
+--
 
+[.specitem,oft-sid="req~up-language-transport-api~1",oft-needs="impl,utest"]
+--
+* *MUST* declare the language specific link:up-l1/README.adoc[uProtocol Transport Layer interface], such that the interface can be implemented by the transport libraries.
+--
 
-.Module Folders/Namespace
-[#folders,width="80%",cols="20%,80%",options="header"]
-|===
-| Folder | Description
+[.specitem,oft-sid="req~up-language-comm-api~1",oft-needs="impl,utest"]
+--
+* *MUST* declare the language specific link:up-l2/README.adoc[uProtocol Communication Layer (uP-L2) API] and provide a default implementation based on the (abstract) Transport Layer API.
+--
 
-| `validators`
-| static methods to validate the data model
+[.specitem,oft-sid="req~up-language-naming~1",oft-needs="impl,utest"]
+--
+* *MUST* be named according to pattern `up-[LANGUAGE]`
+--
 
-| `serializer`
-| Any code that is responsible to Serialize and deserialize the data model
+[.specitem,oft-sid="req~up-language-structure~1",oft-needs="impl,utest"]
+--
+* The top level namespace (package name) *MUST* contain `uprotocol` and *SHOULD* contain `org.eclipse.uprotocol` 
+--
 
-| `factory` (or `builder`)
-| Factory methods to build the data model per business logic (i.e. to build CloudEvents, UUIDs, etc..)
+[.specitem,oft-sid="req~up-language-documentation~1",oft-needs="impl,utest"]
+--
+ * *MUST* contain a `README.adoc` that explains how to build and use the library. 
+--
 
-|===
+=== Test & CI
 
+[.specitem,oft-sid="req~up-language-test~1",oft-needs="impl,utest"]
+--
+ * *MUST* be able to run the test suite such that merge requests (commits) cannot be merged till tests are passed
+--
 
-=== Modules
-
-Modules are packages (folders) that reside under the `src` directory. <<content>> table below lists the required modules.
-
-.SDK Modules
-[#content,width="100%",cols="20%,20%,60%",options="header"]
-|===
-| Folder | Specification |Description
-
-| `uri`
-| link:basics/uri.adoc[UUri]
-| How things are addressed in uProtocol
-
-| `uuid`
-| link:basics/uuid.adoc[UUID]
-| Unique ID & timestamp specification 
-
-| `cloudevents`
-| link:up-l1/cloudevents.adoc[CloudEvents]
-| Specification of how uProtocol data models can be expressed using CloudEvents data model
-
-| `transport`
-| link:up-l1/README.adoc[uTransport]
-a| uP-L1 Transport Interface & data model.
-
-* *MUST* declare the interface & data model where as link:../upclient.adoc[uProtocol Client Library] implement the said interface.
-
-| `rpc`
-| link:up-l2/rpcclient.adoc[uP-L2 RPC Client]
-a|APIs used by clients to invoke methods to simplify implementation of the RPC design pattern. 
-
-|===
-
+[.specitem,oft-sid="req~up-language-ci-build~1",oft-needs="impl,utest"]
+--
+ * *MUST* have CI workflow that verifies pull requests compiles before they can be merged
+--
 
-== Test
+[.specitem,oft-sid="req~up-language-ci-test~1",oft-needs="impl,utest"]
+--
+ * *SHOULD* cover 100% of all code and specifications defined in <<Content>>
+--
 
- * *SHOULD* include a test suite under the folder `test`
- * *MUST* be able to run the test suite such that merge requests (commits) cannot be merged till tests are passed
-  * *SHOULD* cover 100% of all code and specifications defined in <<Source>>
+[.specitem,oft-sid="req~up-language-ci~1"]
+--
+ * *SHOULD* have linter for static code analysis as well as a tool that verifies APIs are properly documented
+--
 
 
-== Build
+=== Build
 
- * *MUST* be easily built in both a Windows and Linux development environment. Any build requirements (i.e. package dependencies) need to be properly documented in the README
-* *MUST* be able to be imported to any wellknown IDE (Eclipse, IntelliJ, VSCode, etc..) and include self contained build system to build the code and dependencies(ex. maven, gradle, clang, soong, etc...).
-* *MUST* fetch external dependency libraries as handle build dependencies, *MUST NOT* copy external dependencies
-* *MUST NOT* depend on external copyright or copyleft libraries/modules, only permissive licenses such as Apache 2.0, MIT, shall be accepted etc..
+[.specitem,oft-sid="req~up-language-build-sys~1",oft-needs="impl,utest"]
+--
+ * *SHOULD* employ an existing build system that is commonly used for the given programming language
+--
 
+[.specitem,oft-sid="req~up-language-build-deps~1",oft-needs="impl,utest"]
+--
+ * *MUST* resolve and include external dependencies as part of the build process only
+--
 
-== Documentation
+== Class Diagram
 
- * *MUST* include a main README.adoc file that explains how to build and use the library. 
- * Each module *MUST* also have a README.adoc that explains how to use said module
+.Class Diagram
+[#up-libraries]
+image:up_libraries.drawio.svg[width=640]