propose HIPE: decorators #71
Conversation
Signed-off-by: Daniel Hardman <[email protected]>
|
|
||
| ### Basic Conventions | ||
|
|
||
| Decorators are defined in HIPEs that document a general pattern such as [message threading]( |
There was a problem hiding this comment.
It would be nice if threads had the same specification semantics as message families - e.g. versioning, an ID and mechanism to find the specification. A HIPE seems insufficient - although I suppose we could tag the commit of the HIPE for versioning :-). My guess is that, for example, threading will be complex enough that it will take a couple of iterations to get it right.
There was a problem hiding this comment.
Did you mean "would be nice if decorators had the same..."?
There was a problem hiding this comment.
I think we should have the versioning as part of the message family documentation. This allows the developer to provide version arguments or other config to their message handling code.
There was a problem hiding this comment.
@dhh1128 - yes - not threads, decorators.
Has the following idea been considered? It came up in conversation here. Make a decorator a YAMF (Yet Another Message Family - hey, I've used that twice now - it's a thing!). That is, any decorator would be defined as a sub-section of the message JSON:
<message family fields>
"@thread" : {
"@type": "did:sov:123456324324234;spec/threading/1.0/thread",
<other decorator fields>
}
At the cost of the @type name/value pair we get the following benefits:
- versioning
- specification discovery
- handling consistency with Message Families ("sub-protocols", I should say)
- the potential for dispatched handling - any JSON sub part with an
@<name>and an@typecould passed to the agent's dispatcher for processing (or, of course, handled locally by the message type). The message family may not even have to know about the decorator or it's purpose to be able to handle it.
Seems like that might be a worthwhile trade-off. Just listening to the Agent Call and Daniel talking about it. @id would not be a decorator by this definition - too much overhead :-).
Your thoughts?
text/decorators/README.md
Outdated
| or [message localization](https://github.com/hyperledger/indy-hipe/pull/64). | ||
| The documentation for a decorator explains its semantics and offers examples. | ||
|
|
||
| Decorators are recognized by name. The name must begin with the `@` character (which |
There was a problem hiding this comment.
Should probably require that decorators should be specified as being explicit - e.g. must be included in the message type spec to be used - vs. implicit - e.g. should be supported by all message types. Thread is an example of the latter. I think the _l10n fields are an example of the former.
There was a problem hiding this comment.
I like this thought. As part of the A2A spec, we can list the specific decorators and versions that are expected to be universally used. This list can be small, and be updated over time.
There was a problem hiding this comment.
This would require that all documents describing decorators would include a version history, which is a pretty easy ask.
| it requires them to be stateful. Therefore this usage, though theoretically possible, | ||
| may be undesirable. If community members want to explore this, they are encouraged | ||
| to discuss broadly, first.) | ||
| * **Connection**. It is conceivable that Alice could bundle up a set of decorators |
There was a problem hiding this comment.
This seems very complex to me. Pretty much all of these other than a scope of "message type" seems complex to me. What is the coding implications of saying, for example, that a specific decorator is viable for this thread or for a single connection? Would we need a "use_these_decorators" agent to agent message sent from Alice to Bob?
There was a problem hiding this comment.
I am not suggesting that we ever say that a decorator type is viable for a thread or connection; I am suggesting that we might want to allow someone to say that a decorator instance is being applied to a thread or connection.
Signed-off-by: Daniel Hardman <[email protected]>
| ``` | ||
| In this example, taken from the localization pattern, `note.@l10n` decorates `note`. | ||
|
|
||
| Besides a single message or a single field, consider the following scopes as decorator |
There was a problem hiding this comment.
I don't understand this section at all. Maybe examples would help?
Signed-off-by: Daniel Hardman <[email protected]>
Signed-off-by: Daniel Hardman [email protected]
Describes the theory and conventions associated with A2A decorators.