Info Bite List Specification
Version 1.0 - 2/12/2004
© 2004 Antone Roundy
- Mission Statement
- General
- Design Philosophy
- Namespace
- Filename Extension
- MIME type
- Common Attributes
- type
- mode
- xml:lang
- Sample Documents
- Format of Element Explanations
- Global Elements
- generator
- interval
- role
- rolespec
- skipday
- skiptime
- Defaults
- defif
- defifno
- defsetval
- defgetval
- defsetattr
- defgetattr
- Channel Elements
- channel
- category
- copyright
- date
- description
- link
- media
- copyright
- description
- height
- link
- size
- width
- rating
- tagline
- textinput
- content
- label
- submit
- title
- Item Elements
- item
- category
- content
- copyright
- date
- guid
- link
- media
- role
- summary
- textinput
- title
- Revision History
I. Mission Statement:
Info Bite List enables the publication and flexible use of collections and lists of data of many kinds while minimizing bandwidth requirements and promoting interoperability and flexibility through an extendable, XML-based format.
II. General:
Info Bite List is an XML-based content syndication format similar to RSS and Atom,
and in fact, many concepts were adapted or borrowed directly from them.
As the name suggests, it is geared toward the publishing of lists of bites of information.
However, it could as easily be used to publish full content.
A. Design Philosophy
The guiding principles behind the development of the format are:
- Size matters: smaller is better.
Every effort has been made to ensure small file sizes by making most elements optional,
specifying default values for omitted elements and attributes,
and providing a mechanism for setting one's own default values.
In addition, a companion API will be be developed to extend Info Bite List which will also focus on minimizing the bandwidth needed to keep up-to-date on the contents of an Info Bite List.
- Usage agnosticism: Info Bite List is not a news format, blogging format, or anything-else format.
It is intended to be useful for publishing a wide variety of data types without (intentional) bias toward any particular type.
Of course they say the road to hell is paved with good intentions, so if publishing a particular type of data via Info Bite List is hell, pick a different road!
- "I am all things to all people...": Okay, Info Bite List is not all things to all people, but it can be extended using modules and become more things to more people.
Also, it has a namespace (though not a DTD yet), so it can be embedded in other formats.
- All other things being equal, the simplest solution is usually the right one.
Info Bite List was designed with an eye toward avoiding some of the complexity that has been introduced into some other syndication formats.
On the other hand, adding certain new capabilities (most notably the ability to set defaults) required the introduction of additional complexity.
I guess all other things weren't always equal.
B. Namespace
The namespace name for Info Bite List 1.0 is "http://dtd.geckotribe.com/ibl/1.0/".
Note that at present, there is no DTD at the address, and in fact, the subdomain doesn't even exist as of the writing of this document!
By convention, the namespace prefix for an Info Bite List is "ibl", and the Info Bite List namespace is the default namespace.
Thus, the opening tag for an Info Bite List file will usually be:
<ibl version="1.0" xmlns="http://dtd.geckotribe.com/ibl/1.0/">
C. Filename Extension
The standard filename extension for an Info Bite List is .ibl.
D. MIME type
The MIME type for an Info Bite List is application/xml+ibl.
E. Common Attributes
Any element with a value MAY specify type and mode attributes as follows.
These apply only to the value of that element, and not to its other attributes or descendents.
xml:lang applies more broadly, as noted:
- type: The MIME type of the value.
The default is "text/plain" unless otherwise specified.
To specify the same content in different formats, use the type "multipart/alternative", and then specify multiple copies of the same element with different types inside the main element.
Any attributes (other than type) specified in the main element are inherited by all child elements that do not override them.
The type of the child elements MUST NOT be "multipart/alternative".
Multiple alternatives with the same type and xml:lang are not allowed.
- mode: The method used to encode the content.
The default is xml (inline xml, such as XHTML).
Other valid values are: escaped, and base64.
- xml:lang: The primary language for the element in which it appears, all of its attributes, and its decendants, unless overridden by another xml:lang attribute.
The value MUST be a valid RFC 3066 language tag.
F. Sample Documents
G. Format of Element Explanations
The explanations of the various elements that appear in an Info Bite List are formatted as follows:
| element name |
Where and how many times the element may appear* |
Notes about the element.
* Note: "File" means as a child of the outermost ibl element.
Everything else is the name of an element which this element can be a child of.
value: An explanation of the value of the element (the data the appears between the opening and closing tags).
We recommend specifying elements marked "value: none" as empty elements, ie., like <elementName attributes="" ... />
attributes:
- attribute name [REQUIRED] Explanation of a required attribute.
- another attribute name [OPTIONAL] Explanation of an optional attribute with no default value.
- another attribute name [OPTIONAL: default value] Explanation of an optional attribute with a default value.
| required element |
Where and how many times the element may appear |
Notes that required elements that are children of optional elements are only required if the parent element exists.
III. Global Elements:
A number of elements can exist as children of the ibl element.
These are referred to as global elements.
All of these elements may also appear as children of channel elements, and some as children of items, as specified.
When an element appears at multiple levels, the latter may override the former.
All global elements MUST appear before the first channel element.
The global elements are as follows:
value: A string representing the agent that created the channel.
attributes: none
value: A number of minutes.
Only one with each "rel" value is allowed.
attributes:
- rel [OPTIONAL: minrefresh] The relationship of the interval to the file or channel. Valid values and their meanings are:
- ttl: "Time to live". The number of minutes that the file or channel can be cached before it needs to be refreshed.
- minrefresh: Minimum refresh time. This is a request to clients not to reload the file or channel more often than the specified number of minutes. A server MAY enforce this limit by denying access to clients who reload more often. A server SHOULD NOT deny access to a client who contacts it more often than this with distinct requests for different files or channels, or for different parts of them (using the Info Bite API). An obvious exception is in the case where it appears that the client is attempting a denial of service attack by submitting numerous varied requests.
| role |
File, channel, item: >=0 |
Role elements specify persons or other entities which played the specified role in the production of the file, channel or item.
Outside of an item, rel MAY be omitted.
In this case, the role does not apply at the file or channel level, but is specified simply to make it available for reference by an enclosed channel or item.
When a role defined elsewhere is referenced by id, if rel is specified, it overrides the rel specified where the role is defined.
value: none
attributes:
- id [OPTIONAL] An identifier, unique within the scope where the role is defined. If roles with the same id are defined in different scopes, the one defined closest in scope to any references to it overrides the other. A role with an id may be referenced by id elsewhere in the same file, channel, or item where it was originally specified by creating another role element which specifies the same id, but has no child elements.
- rel [OPTIONAL: author] The relationship of the role to the file, channel or item. If the element is referencing another role by id, the rel defined there is the default value.
Valid values are:
- author: The author of the file, channel or item.
- contributor: A contributor to the production of the file, channel or item.
- webmaster: The webmaster in charge of technical issues related to the file or channel.
- editor: The managing editor of the file or channel.
This element may appear only as a child of a role element.
value: The data indicated by the rel attribute.
attributes:
- rel [OPTIONAL: name] The relationship of the rolespec to the role.
Valid values are:
- email: an email address.
- fax: a facimilie number.
- ibl: the address of an Info Bite List associated with the individual or organization.
- name: the real name of the individual or organization.
- nick: a nickname for the individual or organization.
- tel: a telephone number.
- website: a website address, including http:// or https://.
Days on which clients should not load the file or channel.
value: none
attributes:
- day [REQUIRED] A day of the week on which the file or channel should not be loaded. Valid values are Sun, Mon, Tue, Wed, Thu, Fri, and Sat.
- timezone [OPTIONAL: UTC] The number of hours before or after UTC that the day begins.
Use negative numbers for timezones after (west of) UTC.
Skipday MAY have skiptime child elements specifying the time periods on the specified day during which the file or channel should not be loaded.
If a timezone is specified, skiptimes are expressed in that timezone.
If a skiptime period spans midnight, it may not all be part of the same day of the week.
If no skiptimes are specified, the entire day should be skipped.
Time periods during which clients should not load the file or channel.
value: none
attributes:
- start [REQUIRED] The number of minutes after midnight UTC from which to begin a period during which the file or channel should not be loaded.
- duration [OPTIONAL: 60] The number of minutes after the start time that the no-load period lasts.
The remainder of the global elements are parts of a system for specifying default values for elements and their attributes.
The use of defaults is optional, but can be useful in reducing the size of your data.
Defaults are undoubtably the most complex part of the Info Bite List specification.
You may wish to refer to the sample document to help you understand their usage.
Addressing Elements and Attributes:
A subset of XPath is used to address elements and their attributes in the "name" and "source" attibutes of some of the following.
Only the following parts of XPath may be used:
- Relative location paths: Absolute location paths (paths beginning with "/") are not allowed.
- / : Location step separator.
- .. : The parent of the "context node" (the element currently under consideration).
- elementName: The element named.
- node(): All of the "node children" of an element, concatenated together. In other words, the value of the element.
- @attributeName : The value of the attribute whose name appears after the "@".
- elementName[@attributeName='value to check for'] : This syntax is used to select an element which has an attribute with a specific value.
When defaults elements appear outside of any channel, the initial "context node" is the enclosing ibl element, so "ibl" will not need to be part of any "name" or "source" attributes.
When they appear inside a channel, the initial context node is the enclosing channel element, and thus "channel" will not need to be part of any "name" or "source" attributes.
One quick example:
role[@rel='author']/rolespec[@rel='name']/node()
The above refers to the real name of the author (the value of a rolespec element whose rel attribute equals "name", which is the child of a role element whose rel attribute equals "author").
| defif |
File, channel, defif: >=0 |
Indicates an element to test for the existance of.
If it exists, its child elements are processed.
value: none
attributes:
- name [REQUIRED] The name of the element we are testing for the existance of.
Name may specify the element herarchically using XPath syntax as described above (eg. "channel/item/date").
If a defif appears nested within another defif, the names from all enclosing defifs are automatically prepended to the name of the current defif.
| defifno |
File, channel, defif, defifno: >=0 |
Defifno is the opposite of defif: it tests for the non-existance of a particular element.
value: none
attributes:
- name [REQUIRED] See defif.
Defsetval creates the element named by the name attribute of the parent defifno element.
Defsetval cannot appear immediately inside defif, because the element will already exist--it does not override the value of an existing element.
value: The value to use for the element being created.
attributes: None.
Defgetval creates the element named by the name attribute of the parent defifno element, if the source is found.
If the source is not found, the element is not created (in which case, another defgetval or defsetval could follow).
It indicates an element or attribute whose value will be used as the value for element being created.
Defgetval cannot be used immdiately inside defif, because the element will already exist.
value: none
attributes:
- source [REQUIRED] The place to get the value from, in the XPath format described above.
The path to the value must be specified relative to the parent of the element being created (ie. the parent is the context node).
This value is used as the default value for the element specified by the name attribute of the enclosing defifno.
Defsetattr sets an attribute to the specified value in the element named by the name attribute of the parent defif or defifno element if it is not already set.
If the attribute is already set, it is not modified.
If the element does not exist (in the case of a defifno), the element is created.
value: none
attributes:
- attr [REQUIRED] The name of the attribute to set the default value for.
- value [REQUIRED] The value to use as the default.
Defsetattr sets an attribute to a value which it gets from the location indicated, if it is not already set.
If the source is not found, the attribute is not created (so another defgetattr or defsetattr for the same attribute could follow).
If the attribute is already set, it is not modified.
If the element does not exist (in the case of a defifno), the element is created.
value: none
attributes:
- attr [REQUIRED] The name of the attribute to set the default value for.
- source [REQUIRED] The place to get the value from, in the XPath format described above.
The path to the value must be specified relative to the parent of the element being created if inside a defifno, or in a defif, relative to the element specified in the enclosing defif.
Any global element may appear as a child of a channel element.
All item elements MUST appear after all other elements which are children of the channel.
A channel defines an "Info Bite List".
value: none
attributes:
- id [OPTIONAL] any value which will uniquely identify this channel when clients send you requests.
The id attribute is REQUIRED if you wish to support client requests referring to multiple channels at once
(the Info Bite API will define ways to do this).
value: An arbitrary category name or a value meaningful in the specified domain, if any.
attributes:
- domain [OPTIONAL] A domain in which the category is meaningful, for example, Syndic8.
value: Text describing copyrights to the channel or item.
attributes: none
value: The value may either be a UNIX timestamp (in UTC time) or a
W3C Date-Time string.
attributes:
- rel [REQUIRED] the relationship between the date and the channel.
Valid values are:
- created: when the channel was created
- modified: when the channel was last modified
- published: when the channel was published in it's current form
- release: when the channel is scheduled for release
If a creation date is specified, all other dates default to the same value if not specified, unless another default is specified using the Info Bite List defaults mechanism.
Only one of each date type is allowed.
value: A description of the channel.
Unlike RSS, brief taglines should go in the "tagline" element rather than here.
This element is for longer descriptions.
attributes: none
A link to another resource.
value: [OPTIONAL] The value of this tag is the text of the link when rendering it as HTML.
If omitted, the client may choose what to render as the text of the link.
For example, it could use the title attribute, the channel or item title, or whatever seems most appropriate under the circumstances.
attributes:
- rel [REQUIRED] The relationship of the linked item to the channel. Valid values, and what they are used to link to, are (with the number of each that a channel may contain specified in parenthesis):
- refersto: something that this channel or item refers to (>=0)
- referredfrom: something that refers to this channel or item (>=0)
- self: a link that can be used to load this channel or item (<=1)
- full: the full content of what this channel or item summarizes (<=1)
- alternative: the same content as this channel or item, in a different format (>=0, but each must have a different type)
- home: the place that could best be called the web homepage for this channel (Channel: <=1, Item: 0)
- respond: a place to go to respond to this channel or item (<=1)
- docs: documentation for the file format of the channel (Channel: <=1, Item: 0)
- href [REQUIRED] The URL being linked to.
- title [OPTIONAL] The text to use in the title attribute when rendering the link as HTML.
- type [OPTIONAL: text/html] The MIME type of what is being linked to.
The MIME type returned by the server hosting the resource overrides this setting.
Media points to an object intended to be rendered with the channel or item, for example, and image, video or sound file.
It's child elements are listed below.
value: none
attributes:
- href [REQUIRED] The URL of the media object.
- type [OPTIONAL: image/jpeg] The MIME type of what is being linked to.
The MIME type returned by the server hosting the resource overrides this setting.
See
channel copyright for details.
value: A description of or caption for the media object.
attributes: none
value: The height in pixels of the media object.
attributes: none
attributes:
- rel [OPTIONAL] A link that is the child of a media link may have only the following rel values: full, alternate.
Full indicates a page that clicking (or otherwise manipulating, as appropriate) the media (or it's caption, if the link specifies a value) should take one to another resource.
Alternate indicates an alternate media type (for example, a GIF version of a PNG image, or an image that could be displayed in the place of a video).
See link above for details of the value and other attributes.
value: The size in bites of the media object.
attributes: none
value: The width in pixels of the media object.
attributes: none
value: A value meaningful in the specified domain.
attributes:
- domain [OPTIONAL: PICS] Specifies a domain in which the rating is meaningful.
value: A tagline introducing the channel.
attributes: none
A form which clients may use to sumbit text for whatever purpose you desire.
The child elements of textinput are described below.
value: none
attributes:
- name [REQUIRED] The name of the textinput field.
- href [REQUIRED] The URL to which to submit the textinput.
- maxlength: [OPTIONAL] The maximum number of bytes that should be submitted in this textinput.
- multiline: [OPTIONAL: false] Indicates whether newline characters are allowed in the text submitted. This value also provides a hint to the client about how to render the textinput (for example, as an HTML input or textarea). Valid values are true and false.
value: Any explanitory or other related text to display with the textinput.
This is NOT default contents for the textinput.
attributes: none
value: A textual label to show with the textinput.
attributes: none
A submit button.
If omitted, the client should render a button saying something to the effect of "submit".
value: none
attributes:
- name [OPTIONAL] The name of the submit button.
If more than one submit button is specified, all but at most one must specify a name.
The names MAY be identical.
- label [OPTIONAL] The text to show on the submit button.
If more than one submit button is specified, all must specify a label.
The labels MUST be unique.
value: Text naming the channel.
attributes: none
V. Item Elements:
It may seem strange that item is optional, but there are cases where there will be no items.
For example, queries using the Info Bite API may result in channels with no items,
and if an Info Bite List only contains items posted within a particular timeframe, it may be empty.
value: none
attributes:
- id [OPTIONAL] Any identifier that uniquely identifies the item within the scope of its channel.
Ids MUST NOT be reused for different items, even after an item is removed from the channel.
See
channel category for details.
value: The full content of the item.
attributes: none
See
channel copyright for details.
See
channel date for details.
value: An identifier that uniquely identifies this item globally
(as opposed to within the scope of the channel, as is done by the item's id attribute).
attributes:
- isPermaLink [OPTIONAL: false] "true" if the guid is a link to the "permanent" location of the item.
"false" otherwise.
If the value is false, the guid cannot be assumed to be a link.
NOTE:
This element may be removed from future specifications.
The preferred method is to use a
link element with rel="self".
See
channel link for details.
See
channel media for details.
| role |
File, channel, item: >=0 |
See
global role for details.
value: A brief version of the full content the item refers to.
If the item does not link to full content, the content element should be used instead, even if it is brief.
attributes: none
See
channel textinput for details.
See
channel title for details.
Note that an item title is optional, while a channel title is required.
| Date |
Revision |
Notes |
| 2/12/2004 |
1.0 |
Modified defaults to use XPath syntax.
Replaced language element with xml:lang attribute.
Fixed error in allowed quantities of various elements.
Added clarifications.
|
| 2/11/2004 |
0.9 |
Original specification |