WĒD: Work Elucidation Document
DŌP is a framework where modules are expected to perform work according to formally defined rules. I will dive into some first impressions about what those rules look like here. Before that, though, it might be good to think about just what is being defined. The model of a Diplomat on the right provides the answer to that question: the Passive Axis. Work is initiated when an Input is provided to a Diplomat or a Request is made of a Diplomat. The Diplomat performs the actual work internally with Fetch and Output actions appropriate to its implementation but that implementation is beyond our concern. The expectations of what will happen when Input and Request Demands are made are our only concern. How those expectations are fulfilled is left up to the Diplomat. Another way to say it is that we are defining the Interactions between us and the Diplomat. The Automations that the Diplomat performs lie outside of the purview of the work definition.
Introducing the Work Elucidation Document, or WĒD
elucidate [ih-loo-si-deyt]
- to make lucid or clear; throw light upon; explain
- to provide clarification
Source dictionary.com
WĒD will elucidate work to be done, that is, it will explain the expectations of what will happen when Input and Request Demands are made of a Diplomatic Agent. The “expectation” is described in natural language and can be as specific or general as desired. The success of this description will partly be determined by how well Diplomats can meet the expectation. If there is a consistent failure to meet expectations, it is likely the description is failing to fully elucidate them.
Below is a schema that defines valid WĒD. If you are not familiar with JSON Schema, check it out. After the schema, I will provide details about each element.
{
"$id" : "http://dop.forsaken-threads.com/schema/0.0.1.alpha/work-elucidation-document.json#",
"$schema" : "http://json-schema.org/draft-07/schema#",
"title" : "WĒD: Work Elucidation Document",
"description" : "In Diplomacy Oriented Programming, Diplomatic Agents perform work to meet the expectations defined in the Work Elucidation Document.",
"type" : "object",
"required" : ["id", "title", "interactions"],
"additionalProperties" : false,
"properties" : {
"id" : {
"$comment" : "Work IDs that do not contain a '/' are reserved for work globally defined in the DŌP dispensary.",
"type" : "string",
"minLength" : 3,
"maxLength" : 256,
"pattern" : "^[a-z0-9- ]{3,}(|\/[a-z0-9- ]{3,})$"
},
"title" : {
"type" : "string",
"minLength" : 3,
"maxLength" : 256
},
"description" : {
"type" : "string",
"minLength" : 3,
"maxLength" : 4096
},
"interactions" : {
"$comment" : "According to the Diplomatic Agent model, an Interaction can be either an Input Demand or a Request Demand. The type of Demand is dependent on the kind of response expected. 'acknowledgment' for an Input, or 'informative' for a Request.",
"type" : "array",
"minItems" : 1,
"maxItems" : 256,
"uniqueItems" : true,
"items" : {
"type" : "object",
"required" : ["responseType", "demand", "expectation"],
"additionalProperties" : false,
"properties" : {
"responseType" : {
"enum" : ["acknowledgment", "informative"]
},
"demand" : {
"$comment" : "Within the context of a single WĒD, Input and Request Demands should be unique, however this is not currently enforceable with JSON Schema draft-07. DŌP implementations should ignore all but the last occurrence of a demand.",
"type" : "string",
"minLength" : 1,
"maxLength" : 256
},
"expectation" : {
"$comment" : "A natural language description of what work this demand is expected to do.",
"type" : "string",
"minLength" : 3,
"maxLength" : 1024
},
"conditions" : {
"$comment" : "The conditions for the demand can be whatever is necessary to support the expectation. If defined, it must consist of a valid JSON Schema.",
"$ref" : "http://json-schema.org/draft-07/schema#"
},
"response" : {
"$comment" : "The effective validation for this property can be found in the if-then-else statement below.",
"type" : ["string", "number", "boolean", "null", "object", "array"]
},
"required" : {
"type" : "boolean",
"default" : "true"
}
},
"if" : {
"properties" : {
"responseType" : {
"const" : "acknowledgment"
}
}
},
"then" : {
"not" : {
"properties" : {
"$comment" : "The response to an Input Demand cannot be defined in a WĒD. Instead, 'acknowledgment' responses have a standardized format. The JSON Schema for it can be found at http://dop.forsaken-threads.com/schema/0.0.1.alpha/acknowledgment-response.json#"
"response" : {
"type" : ["string", "number", "boolean", "null", "object", "array"]
}
}
}
},
"else" : {
"properties" : {
"response" : {
"$comment" : "The response for a Request Demand can be whatever is necessary to support the expectation. If defined, it must consist of a valid JSON Schema.",
"$ref" : "http://json-schema.org/draft-07/schema#",
}
}
}
}
}
}
}A Work Elucidation Document should be a JSON object with three or four properties. While description is optional, id, title, and interactions are all required. The Work ID is a short, name-spaced identifier that will be used by a Diplomat to advertise what work it can perform. There will be a DŌP dispensary that contains all kinds of WĒDs for basic units of work. These will help jump-start the creation of DŌP implementations by providing expectations for common universal work. IDs that do not contain a / are reserved for WĒDs found in the dispensary.
The title and description properties are self-evident. interactions defines the Input and Request Demands. As you can see, they are simple JSON objects with at least three properties: responseType, demand, and expectation. The response type is a constant value depending on the interaction. For an Input, it’s acknowledgment, and for a Request, it’s informative. The demand property is an identifier that will be used by the requesting and receiving Diplomats to indicate what should be done for the interaction. The expectation property is self-evident.
There are three other possible properties for an interaction: conditions, response, and required. The conditions property, if it exists, must be a valid JSON Schema that can be used to validate a payload for the demand, i.e. the contents of the diplomatic pouch used as part of the exchange. DŌP implementations will discreetly use the schema before passing the demand along to the Diplomatic agent. This way Diplomats do not have to perform this validation step when receiving a Demand. Of course, there may be other validations required that cannot be encoded within a standard JSON Schema.
The response property should only be defined for Request Interactions, i.e. an interaction where the responseType is informative. Like conditions, if defined, it should be a valid JSON Schema and will be used to validate the response before forwarding to the receiving Diplomat. Lastly, the required property is used during protocol negotiation. The default value is true and means that the Demand must be handled by any Diplomat wishing to perform the work elucidated in the WĒD. When false, the Demand is optional.
One last thing to note is the response for Input Demands, i.e. an interaction where the responseType is acknowledgment. This is a standard object defined elsewhere. Here is the schema for it:
{
"$id" : "http://dop.forsaken-threads.com/schema/0.0.1.alpha/acknowledgment-response.json#",
"$schema" : "http://json-schema.org/draft-07/schema#",
"title" : "Acknowledgment Response",
"description" : "In Diplomacy Oriented Programming, Diplomatic Agents make demands of other Diplomats. The response to an Input Demand uses this standardized format.",
"type" : "object",
"required" : ["message", "received", "met"],
"additionalProperties" : false,
"properties" : {
"message" : {
"type" : "string",
"minLength" : 3,
"maxLength" : 256
}
"received" : {
"type" : "boolean"
},
"met" : {
"type" : "boolean"
},
"receivedFailure" : {
"type" : "string",
"minLength" : 3,
"maxLength" : 256
},
"metFailure" : {
"type" : "string",
"minLength" : 3,
"maxLength" : 256
}
},
"allOf" : [
{
"if" : {
"properties" : {
"received" : false
}
},
"then" : {
"required" : ["receivedFailure"]
}
},
{
"if" : {
"properties" : {
"received" : true,
"met" : false
}
},
"then" : {
"required" : ["metFailure"]
}
}
]
}An Acknowledgment Response will contain, at a minimum, three properties: message, received, and met. The message is used to convey a string response. received and met are booleans that indicate whether or not the demand was received and the expectation was met. In the event a demand was not received, receiveFailure must provide a reason. If the demand was received, but the expectation could not be met, metFailure must provide a reason.
This required a lot of thought as well as research, most of it to learn the JSON Schema standard. I have not actually tested these schema to see if they work as intended, or if they even validate as good JSON Schema. Obviously, this will be done at some point in the future, and in preparation for future fixes, I inserted a version string in the $id for all schema. I should also make a note about the URIs indicated in the schema. To quote from the JSON Schema specification:
The URI is not a network locator, only an identifier. A schema need not be downloadable from the address if it is a network-addressable URL, and implementations SHOULD NOT assume they should perform a network operation when they encounter a network-addressable URI…The use of URIs to identify remote schemas does not necessarily mean anything is downloaded, but instead JSON Schema implementations SHOULD understand ahead of time which schemas they will be using, and the URIs that identify them.
For now, I do not have downloadable versions of these schema. One step at a time. :-)