TŌC: Tentative Offer of Collaboration
Now that we’ve defined a specification for declaring work (the Work Elucidation Document, or WĒD), we need a way to declare what work a particular Diplomatic Agent will do. However, it might be a good idea to talk about Diplomats and negotiations a little bit before getting to the that.
In a DŌP world, work is formally declared so that modules can be safely plugged in to a Host Application and, so long as a protocol can be successfully negotiated, the expectations for that work should be properly met. If we think about work in this context, it is possible to envision a case where similar declarations of work might exist. It is also conceivable that a particular module could perform many different kinds of work. All of this is simple with Diplomacy Oriented Programming.
Diplomats can be written to perform any number of different tasks, or any number of variations of the same task. During protocol negotiation, a Tentative Offer of Collaboration (TŌC) is used to determine if the Diplomat and the Negotiating Partner can come to terms for mutual expectations. There are two sides to this. On one side the Negotiating Partner has expectations for what work the Diplomat will be doing. On the other side, the Diplomat has its own expectations for what it will require in order to complete that work. For example, a Diplomat may require access to a database to persist data, or it may require the ability to make web-based API calls.
If terms for a particular expectation - on either side of the negotiations - cannot be agreed upon, the Diplomat has the opportunity to suggest one or more alternative TŌCs. Depending on the preferences of the Negotiating Partner, these alternatives can be requested and evaluated automatically. Consider a Diplomat that requires access to a database. If the Negotiating Partner cannot provide that access, the Diplomat may make another offer where the expectation for a database is replaced by an expectation for a small monthly fee. It is likely such a counter-offer would need manual intervention, but you can imagine cases where alternatives could be accepted based on an algorithmic calculation of predefined preferences.
With a better idea of what’s going on with Diplomats and negotiations, let’s take a look at the schema for a Tentative Offer of Collaboration:
{
"$comment" : "TO DO: Include retrieval methodology for alternative offers."
"$id" : "http://dop.forsaken-threads.com/schema/0.0.1.alpha/tentative-offer-of-collaboration.json#",
"$schema" : "http://json-schema.org/draft-07/schema#",
"title" : "TŌC: Tentative Offer of Collaboration",
"description" : "In Diplomacy Oriented Programming, Diplomatic Agents make offers to fulfill the expectations of a Work Elucidation Document.",
"type" : "object",
"required" : ["id", "title", "workIDs", "plans"],
"properties" : {
"id" : {
"$comment" : "TŌC IDs that do not contain a '/' are reserved for Diplomats globally defined in the DŌP embassy.",
"$ref" : "#/definitions/idString"
},
"title" : {
"type" : "string",
"minLength" : 3,
"maxLength" : 256
},
"description" : {
"type" : "string",
"minLength" : 3,
"maxLength" : 4096
},
"workIds" : {
"$comment" : "This array advertises all of the Work IDs that are covered by all of the plans in this TŌC.",
"type" : "array",
"minItems" : 1,
"maxItems" : 256,
"uniqueItems" : true,
"items" : {
"$comment" : "Work IDs that do not contain a '/' are reserved for work globally defined in the DŌP dispensary.",
"$ref" : "#/definitions/idString"
}
},
"plans" : {
"type" : "array",
"minItems" : 1,
"maxItems" : 256,
"uniqueItems" : true,
"items" : {
"type" : "object",
"required" : ["id", "title", "workIds", "interactions"],
"additionalProperties" : false,
"properties" : {
"id" : {
"$comment" : "Within the context of a single TŌC, Plan IDs 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 Plan ID.",
"type" : "string",
"minLength" : 1,
"maxLength" : 256
},
"title" : {
"type" : "string",
"minLength" : 3,
"maxLength" : 256
},
"description" : {
"type" : "string",
"minLength" : 3,
"maxLength" : 4096
},
"workIds" : {
"$comment" : "This array advertises all Work IDs covered by this plan.",
"type" : "array",
"minItems" : 1,
"maxItems" : 256,
"uniqueItems" : true,
"items" : {
"$comment" : "Work IDs that do not contain a '/' are reserved for work globally defined in the DŌP dispensary.",
"$ref" : "#/definitions/idString"
}
},
"interactions" : {
"$comment" : "Each item should map to a Demand defined in one of the covered Work IDs.",
"type" : "array",
"minItems" : 1,
"maxItems" : 256,
"uniqueItems" : true,
"items" : {
"type" : "string",
"minLength" : "1",
"maxLength" : "256"
}
},
"automations" : {
"$comment" : "This array advertises the Work IDs that the Diplomat requires to fulfill the expectations defined by the interactions.",
"type" : "array",
"maxItems" 256,
"uniqueItems" : true,
"items" : {
"$comment" : "Work IDs that do not contain a '/' are reserved for work globally defined in the DŌP dispensary.",
"$ref" : "#/definitions/idString"
}
},
"alternatives" : {
"$comment" : "Each property must map to a Work ID defined in either an interaction or an automation, however this is not currently enforceable with JSON Schema draft-07. DŌP implementations should handle this validation with an extension of the Schema or by some other method."
"type" : "object",
"additionalProperties" : false,
"patternProperties" : {
"$comment" : "Work IDs that do not contain a '/' are reserved for work globally defined in the DŌP dispensary.",
"^[a-z0-9- ]{3,}(|\/[a-z0-9- ]{3,})$" : {
"type" : "object",
"minProperties" : 1,
"additionalProperties" : false,
"properties" : {
"plans" : {
"$comment" : "Each item must map to a Plan ID defined in this TŌC, however this is not currently enforceable with JSON Schema draft-07. DŌP implementations should handle this validation with an extension of the Schema or by some other method."
"type" : "array",
"minItems" : 1,
"maxItems" : 256,
"uniqueItems" : true,
"items" : {
"type" : "string",
"minLength" : 1,
"maxLength" : 256
}
},
"offers" : {
"$comment" : "Each item must map to a TŌC ID that can be retrieved. The precise method of retrieval is not yet incorporated into this schema.",
"type" : "array",
"minItems" : 1,
"maxItems" : 256,
"uniqueItems" : true,
"items" : {
"$comment" : "TŌC IDs that do not contain a '/' are reserved for Diplomats globally defined in the DŌP embassy.",
"$ref" : "#/definitions/idString"
}
}
}
}
}
}
}
}
}
},
"definitions" : {
"idString" : {
"type" : "string",
"minLength" : 3,
"maxLength" : 256,
"pattern" : "^[a-z0-9- ]{3,}(|\/[a-z0-9- ]{3,})$"
}
}
}Hopefully JSON Schema documents are a little more familiar now, so this breakdown will be a bit less thorough. The TŌC is a JSON object with a minimum of four properties: id, title, workIDs, and plans. The first two are pretty basic. workIDs is an array of any Work IDs that might be satisfied by the Offer. plans is an array of different configurations that can apply to one or more of those Work IDs. This is how a Diplomatic Agent can offer to fulfill a variety of Work IDs in a variety of ways. A final property, description, is optional.
So what constitutes a plan? It must be a JSON object also with a minimum of four properties: id, title, workIDs, and interactions. The first three are pretty self-explanatory. interactions is an array of Demands that are defined by the Work IDs that this plan will work. It cannot be an empty array, but it also does not have to cover every Demand defined by every Work ID. Missing Demands, however, may cause negotiations to fail. In addition to these four required properties, there are three optional ones. Of course, there’s the basic and uninteresting description property. automations is an array of Work IDs that the Diplomat requires to do its work. The Negotiating Partner has to agree to fulfill these expectations in order for a protocol to be established.
Lastly, alternatives is where Diplomats can offer other options when negotiations break down. It should be a JSON object where each property is a Work ID. If a particular Work ID becomes a sticking point during negotiations - and it’s important to note this could be work related to either an Interaction or an Automation - the corresponding property on the alternatives object provides other plans within the current Offer or even entirely different offers altogether. These other options can each be tried, in turn, to get negotiations back on track. On a side note, DŌP implementations should be careful that processing of alternatives does not result in an infinite loop. Implementations may also offer a setting for limiting the radius of alternatives considered, i.e. how many connections from one alternative to another alternative are allowed (A suggests B suggests C etc.).
With the Work Elucidation Document and the Tentative Offer of Collaboration both defined, we now have a foundation to begin laying out a specification for Protocol Negotiation, the final major piece in Diplomacy Oriented Programming.