two comments for testing collaboration

README.md

@@ -1,3 +1,20 @@
+<!-- 
+DF: Throughout the repo there are at least two types of data: 
+    protocol specification (see janus/message-packaging) and 
+    philological ideas and principals (see self_sovereign_privacy_by_design_distilled.md).
+    Lastly we have something in between (see dkms).
+    How do we want to distinguish them (or do we). Should we have a directory that is background
+    reading and/or design principles? 
+JL: Yes, I think we should organized them, and cross reference. What do you recommend?
+DF: I'm thinking that maybe we should have a folder/codename like Janus for the background theory, where we layout
+    our case for our goals, principles, etc. We decribe the folder as not containing specs, per se, but as a foundation to
+    understand our protocol.
+JL: OK, that sounds good. What should the main README have in it then? Super high level summary with a 
+    reference to documents for principles and for specs?
+DF: Yeah, a map to where to go depending on what you are wanting to read.
+
+-->
+
 # The Sovrin Protocol
 
 The Sovrin Protocol is a set of standards, patterns, and tools that facilitate

janus/message-transport.md

@@ -6,22 +6,38 @@ Messaging is transport agnostic. Messaging does not rely on transport for guaran
 Despite the agnostic nature of the messaging protocol, the use of a transport protocol requires agreement on conventions for the use of the said protocol. These conventions will be protocol specific and their scope is only decisions needed to transport the message on the said protocol. Anything related to the meaning, security or routing of the message is expressly out of scope.
 
 # HTTP/HTTPS
-## URL
-The endpoint URL for messages should be a simple endpoint. It should not have route info (ex. DIDs) and should be consistent for all users of the endpoint service.
+## Request
+### URL
+Endpoint URLs for Janus messages should be simple. The URL should not expose any extra information about the message (e.g., the type of message being sent). It should have no route info (e.g., DIDs) and should be consistent for all users of the endpoint service. Message types and destination DIDs are encapsulated in the encrypted messages themselves, so as not to reveal information to proxy agents and routers along the path to the ultimate destination.
 
-Example:
+Example: https://agency.example.com/msg/
+
+### Method
+The method used for Janus messages should be `POST`, and agents with HTTP interfaces that receive a different message are encouraged to return a 405 Method Not Allowed.
+
+Janus does not depend on the transport protocol for confidential communications, therefore an HTTP method can leak details about the message being sent. HTTP is resource-oriented, and Janus is message-oriented. The intent of a Janus message is embedded in the message type.
+
+### Headers
+Accept: message/janus
+Content-Type: message/janus
 
-https://agency.example.com/msg/
-## Headers
-<span style="color:yellow">TODO: Any thoughts on http headers</span>
 ## Response
-### Codes
-#### OK
-How the message is processed and what response is given is the prerogative of the receiver of the message. There is two conventions for non-error response.
 
-**202 Accepted** -- The message is processed asynchronously. No content is return.
+### Headers
+If a response contains a message then include a Content-Type header.
+
+Content-Type: message/janus
+
+### Status Codes
+How the message is processed and what response is given is the prerogative of the receiver of the message. There are two conventions for non-error response.
+
+#### Success
+**200 OK** -- The message was processed successfully, and the body contains the response message.
+
+**202 Accepted** -- The message will be processed asynchronously. No response message.
+
+**204 No Content** -- The message was processed succesfully with no response message.
 
-**200 OK** -- If the message is processed synchronously and the return is the corresponding message.
+#### Errors
 
-#### Error
-Standard 400s codes for client errors and standard 500s codes for server errors.
+Standard 4xx codes for client errors and 5xx codes for server errors.