Socknet Message Format

From The Socknet

Jump to: navigation, search

Socknet Message Format is an XML format that enables providers to customize a message based on user preferences at the time of reading.

Contents

Example 

<socknet:name openid="http://openid.com/username">David</socknet:name>
has tagged
<socknet:nameGroup>
    <socknet:name openid="http://openid.com/user1">Jim</socknet:name>,
    <socknet:name openid="http://openid.com/user2">Jack</socknet:name>, 
    and 
    <socknet:name openid="http://openid.com/user3">Jenny</socknet:name>
</socknet:nameGroup>
in a photo.

A provider may choose to show the message with all the names exactly as is. But it may choose to alter the message however it prefers. For example, because the message identifies the OpenID's of the users, the provider may choose to only include the users who are friends of the reader, as in: 

<socknet:name openid="http://openid.com/username">David</socknet:name>
has tagged
<socknet:nameGroup>
    <socknet:name openid="http://openid.com/user2">Jack</socknet:name>
</socknet:nameGroup>
in a photo.

Above, the provider has replaced the contents of the nameGroup node.

Other possibilities:

Reader calls user2 something else: 

<socknet:name openid="http://openid.com/username">David</socknet:name> 
has tagged
<socknet:nameGroup>
    <socknet:name openid="http://openid.com/user2">Jack Sparrow</socknet:name>
</socknet:nameGroup>
in a photo.

Reader doesn't care who, but the number only: 

<socknet:name openid="http://openid.com/username">David</socknet:name> 
has tagged
<socknet:nameGroup>3 people</socknet:name> 
in a photo.

Combination: 

<socknet:name openid="http://openid.com/username">David</socknet:name> 
has tagged
<socknet:nameGroup>
    <socknet:name openid="http://openid.com/user2">Jack Sparrow</socknet:name> 
    and 2 others
</socknet:nameGroup> 
in a photo.

Note: The examples are not final, but transitional. The "socknet:*" nodes should be removed before including these messages in an HTML page.

The Format

Messages may be fragments, without a single root element. This means that there may be multiple top-level nodes in the message. To simplify processing, the receiver of the message is encouraged to encapsulate it: 

$message = '<span>' . $message . '</span>';

The Socknet Message Format is comprised of XHTML and special elements in the http://socknet.net/message namespace. Such as: 

<socknet:message xmlns:socknet="http://socknet.net/message">
A message for you.
</socknet:message>

In the examples, we assume the local name "socknet" is used, but the local name could be anything.

socknet:message

Does nothing.

socknet:nameGroup

Must contain one or more socknet:name nodes. The provider will use any set of rules to determine which of the OpenID's it would like to report on, as few as 1 and as many as all of them. If it is zero, the provider shouldn't bother showing the message, or should reconsider showing at least one item.

This node contains the area of the message that may be completely replaced by a customized list of names.

Additionally, a socknet:nameGroup may contain one or more other socknet:nameGroup nodes. These sub nameGroup's constitute groups of names which must be together in relation to other parts of the message. See the example at the end of the page. Generally it is best to process sub nameGroup's before nameGroup's that contain them. Then any changes to the sub nameGroup can be reflected in the work of the nameGroup above it.

socknet:name

attributes

openid: required, an openid

Contains a human-readable name. Providers will usually replace this with one that best represents the user in the openid attribute. Several examples of this are shown above.

socknet:singular

socknet:plural

These nodes must be within a nameGroup node. Each is visible only if the openid list has one or more than one (respectively) OpenID after processing.

socknet:masculine

socknet:feminine

socknet:unknownGender

These nodes must be within a nameGroup node.

These are subject to the rules of the human language that the user uses, but in general, the masculine node will be visible only when the OpenID(s) refers to a male and the feminine will be visible when the openid(s) refers to a female.

In English, this only applies to the singular form. In Spanish, plural forms can have masculine and feminine alternatives. Many other examples exist of differences between languages.

Most languages have obvious rules which dictate how this and the plurality nodes can interact. A few languages will need specifications. Clearly the creating provider and reading provider of a message must both understand the interactions.

unknownGender is used when the user has not specified his gender. In English, this often morphs into the plural form, the defacto standard and bane of English teachers everywhere. Various camps believe that all non-specific genders should use the male form, others use the female and others still alternate with the modulo of 13. He/she is a ridiculous choice. Whatever => YMMV.

socknet:*

attributes

canIgnore: optional, 1 or 0

A "dumb-processor" may use the attribute canIgnore as an indication of what parts of a message to excise if it doesn't intend to actually process the message. So if a socknet:singular and a socknet:plural node are both present, then one can have canIgnore set to 1, so that the message can be easily made to make sense.

A More Thorough Example 

<socknet:nameGroup>
	<socknet:nameGroup>
		<socknet:name openid="http://user1.com/">Mike</socknet:name>
		and
		<socknet:name openid="http://user2.com/">Jim</socknet:name> 
	</socknet:nameGroup>
	<socknet:plural>both enjoy</socknet:plural> 
	<socknet:singular>enjoys</socknet:singular>
</socknet:nameGroup>
this video: http://videosite.com/path/

The results could be:

Retrieved from "http://socknet.net/w/Socknet_Message_Format"
Personal tools