Universal Social Data Protocol

The Universal Social Data Protocol (USDP) is a collection of API calls using the comon Universal Social Data Structure of the OSA standards set. This protocol is used to provide a common decentralized communication standard for use amongst all participating communication platforms.

Overview

The USDP supports bringing normalcy to online communications. There is no such thing as entirely risk free communications, not online, not in the physical world. Normalcy in communication brings the risk of online communicates to, or at least near, risk levels of physical world conversations. Standing eye-to-eye with someone, there is no guarantee that what is told to them will remain confidential. Conversations of all types require an element of trust. Re-establishing that normal trust in conversation by providing unprecedented control over personal data use, and removing today's guarantee of data molestation, is the goal of the OSA ond the OSA/USDP.
The USDP is not an attempt to overcome human nature with guarantees that passed information will remain 100% private. There is no way to prevent information recipients from forwarding last Halloween's picture of your holding a Cuban cigar while in a baby blue tutu, whether it was sent online or physically mailed. Properly implemented however, the USDP does provide a solid assurance your information communicated online will be limited to those you know and trust. There is no way to guarantee that trust placed in those close to you won't be broken, you can however keep your privacy secure from being exploited by third parties you have no reason to trust and very likely distrust in the first place. OSA and the USDP also provide for the guaranteed excommunication of recipients that violate a sender's trust, be they personal or otherwise.

Structure

The USDP operates as a typed, two-tier structure made up of data and API calls. What API's are available depend on the type of message passed. Tier one of the USDP is considered cargo. Tier two is an instruction set layer. Tier two is not available to the OSA Communication Engine (OCE) with all message types.

Message Types

The "msgType" field of the USDS defines the type of message being passed. There are four types of USDP categorically speaking. The "qMsg" type is the most common, and most restrictive, of the message types. The "appOp" and "oceOp" types, are more robust in their capabilities, though less common, providing the ability to interact directly with the OCE. The "Admin" type is the most powerful of the types, supporting configuration changes to the OCE.

qMsg

The "qMsg" type is the most common, and most restrictive of the message types. The "qMsg" is used to pass data to the OSA Communication Engine (OCE) for routing. All data passed with the type of "qMsg" is considered cargo only. Tier two of the USDP is not available to the OCE with "qMsg" type messages.

appOp

The "appOp" and "oceOp" types are more robust in their capabilities. Though less common, they provide the ability to interact directly with the OCE. The appOp message type represents messages initiated by registered applications to invoke actions specific to the OCE. This message type opens the "Adjunct" section of the USDS to the OCE as a JSON container holding an API call and associated data structure. In this regard, the "Adjunct" section acts as tier two of the USDP. In contrast, with a "qMsg" type the "Adjunct" section is simply another data item.

oceOp

The "oceOp" and "appOp" types are more robust in their capabilities than the qMsg. Though less common, they provide the ability to interact directly with the OCE. The oceOp message type represents messages initiated by one OCE to invoke actions specific to a remote OCE with which it has previously registered. This message type opens the "Adjunct" section of the USDS to the OCE as a JSON container holding an API call and associated data structure. In this regard, the "Adjunct" section acts as tier two of the USDP. In contrast, with a "qMsg" type the "Adjunct" section is simply another data item.

oceAdm

Supporting configuration changes to the OCE, the "oceAdm" type is the most powerful of the types. Like the oceOp type, the "Admin" type opens the "Adjunct" section of the USDS to the OCE as tier 2 of the USDP. The API calls made available via the "Admin" type are used to make configuration changes to the OCE itself. Such changes would be along the lines of adding community members, defining OCE rules and changing the runtime state of the OCE.

APIs

The API function calls of the USDP provide the means by which information is passed, applications interact with the OCE and the OCE itself is managed. The APIs are broken down categorically, one category to each message type.

Note: The API calls listed here will be listed as a link if the spec for that call is considered defined to the point of usability. Any call being implemented for which the spec is considered incomplete should be submitted to TekAdvocates, and eventually the OSA Governance Board, for consideration in the formal definition of that call. This is a developing standard and all consideration in keeping this effort unified will go a long way to assuring its success.
API Conventions
Convention Definition
Name Prefix API calls that support functions mandatory in the OSA specification will have lower-cased "osa" prefix. Additional functions defined specific to the OCE will have the lower-cased "oce" applied as a prefix.
Name Body The body of the API function name, after the prefix, will have the first letter of each word capitalized with each additional letter of the word lower-cased (CamelCase). There are no spaces in function names. The underscore (_) can be used for clarity when two initial capital letters are adjacent.
Operation No API function may, as a result of it's operation, violate the functional tenants of the OCE as defined by the OSA, whether an OSA standard or OCE custom function.

Communication

The communcation category of API's has no specific functions defined for calling directly. While the "qMsg" type could be considered a function call in itself because it triggers the OCE functionality of storing and routing a message, there is not necessarily an API function of the OCE named "qMsg." Implementation of this message type will be OCE specific.
Any messages coming to the OCE must come from a locally registered application, or remotely registered OCE. Messages not meeting this criteria are not to be accepted. How the message is handled otherwise is OCE dependent.

Message Type: qMsg

Objective
The objective of the "Communication" category is simply to securely pass data to and from the OCE for caching and redistribution.
Function Description
N/A The qMsg message type has no function calls. The act of sending this message type is in itself a trigger for the singular operation of storing the data for redistribution to intended recipients.

Operational

The operational category of API's are used to affect, or report on, the operational relationship of the client"Client" is any software registered to interact with the OCE. with the OCE. Both the "appOp" and "oceOp" message types are considered members of the "Operational" message type category.

Message Type: appOp

Objective
The objective of the "appOp" Operational category is to manage the flow of data within, and between, the client applications and the OCE.
Function Description
osaAppReg The means by which applications register for data interaction with an OCE managing the local POD.
osaAppUpdate Used to update stored information about a registered application, such as parameter settings.
osaAppDrop Used to remove a registered application from the OCE. Messages from a dropped application will no longer be accepted, nor will messages be sent to a dropped application.
osaNewKey The means by which applications with reason to believe their key has been comprimised can request a new key from an OCE.
osaNotify Under consideration as a function for an already registered application to notify the OCE of changes in IP address to facilitate remote communication.
osaAppPullCfg Pull the OCE member specific configuration data for the calling application. A default dataset is returned if no OCE member data is defined.


Message Type: oceOp

Objective
The objective of the "oceOp" Operational category is to manage the flow of data within, and between, two OCEs.
Function Description
osaInvite Send an invitation to connect a local OCE with an external POD/OCE. No OCE will accept a message (other than osaInvite) from another OCE unless the sending OCE is fully registered and approved by the receiving OCE.
osaMemberReg Function to process a member registration request from a member of a previously registered OCE.


Administrative

The API calls of the administrative section are used to manage membership data and to alter the configuration and runtime state of the OCE itself.

Message Type: oceAdm

Objective
The objective the "Administrative" category is to provide API functions that give the one or more OCE administrators the ability to immediately satisfy the need to alter OCE operation or data from a remote location. This category is intended to support future development of mobile applications.
Function Description
osaStop Shutdown the OCE entirely. No further remote communication with the OCE will be possible. There won't be a running OCE left to communicate with after running this command.
osaMaint Take the OCE to a state where qMsg and oceOp type messages are queued and not processed. This state allows for adjustments to be made to the OCE in a quiesced state.
osaSuspend Take the OCE to a state where qMsg and oceOp type messages are rejected and oceAdm message types continue to be processed. Rejected messages are not to be queued for future processing. This state allows for adjustments to be made to the OCE in a quiesced state. Messages are rejected to inform the send OCE that the suspended OCE is not receiving messages at this time.
osaCloak Take the OCE to a state where qMsg and oceOp type messges are quietly discarded and oceAdm message types continue to be processed. Discarded messages are not to be queued for future processing. This state allows for adjustments to be made to the OCE in a quiesced state. Messges are discarded instead of queued as an additional measure in the case the "osaSuspend" is being sent to compensate for malicious or DoS attacks.
osaNormal Return the OCE to a normal runtime state.
osaAddMbr Add a new member to the OCE.
osaSusMbr suspend the ability of a member to interact with the OCE, but leave their enrollment information and associated rules in place.
osaDelMbr Remove a member from the OCE and delete any associated information, pending messages and rules.
osaAddGrp Add a new member group to the OCE.
osaAddGrpMbr Enroll an existing OCE member to an existing OCE group.
osaRemGrpMbr Remove an existing OCE member from an existing OCE group.
osaDelGrp Remove all Members from an existing OCE group and delete the group. The actual member records are left unchanged.
osaAddRule Insert an operational rule to the OCE to control message routing.
osaChgRule Alter an existing OCE rule to alter the way messages are routed.
osaSusRule Suspend a rule from having an effect on queued messages without actually changing the rule itself.
osaDelRule Remove a message routing rule from the OCE entirely.

API Responses

All USDP API functions respond with the same base JSON message structure regardless of message type. Additional data elements can be added to the returned JSON, however the list base structure must be present. 

{
   "MsgNum" : "1",
   "MsgID" : "MSGRCVD",
   "Mesg" : "Message received"
}

Where:

MsgNum
The numeric return code for the message. Positive numbers indicate a successful action. Negative numbers indicate there was a problem.
MsgID
A character representation of the return status for the API call.
Mesg
A short descriptor for the response.