UserPreferences

EchoExample

Version as of 2003-07-08 09:13:25

Clear message

Up: SyntaxConsiderations has background and discussion on why we chose this format.
Process: EchoExampleProcess See also : SyntaxExtensionMechanism

Maximal Echo Feed

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://purl.org/echo/" version="1.0"
  xml:lang="en-us" xml:base="http://example.com">
  <title>My First Weblog</title>
  <title rel="subtitle">Ain't the Interweb great?</title> 
  <link rel="weblog" href="/johndoe/weblog/" />
  <date rel="created">2003-02-05T12:29:29Z</date>
  <date rel="issued">2003-02-05T12:29:29Z</date>
  <date rel="modified">2003-02-05T12:29:29Z</date>

  <entry id="e45">
    <title>My First Entry</title>
    <title rel="subtitle">In which a newbie learns to blog...</title>
    <summary>A very boring entry; just learning how to blog here...</summary>
    <link rel="entry" href="/weblog/archive/45.html" />
    <date rel="created">2003-02-05T12:29:29Z</date>
    <date rel="issued">2003-02-05T12:29:29Z</date>
    <date rel="modified">2003-02-05T12:29:29Z</date>

    <!-- One can define any number of persons related to an entry, and define their role.  -->
    <contributor role="author">
      <name>John Doe</name>
      <!-- <link rel="" /> is used to respect prior art in html/xhtml -->
      <link rel="homepage" href="/johndoe/" />
      <link rel="email" href="john.doe@example.com" />
    </contributor> 

    <contributor role="graphical-artist">
      <name>Bob Smith</name>
      <link rel="homepage" href="/bobsmith/" />
      <link rel="email" href="bob.smith@example.com" />
    </contributor>

    <content type="application/xhtml+xml" mode="none" xml:lang="en-gb">
      <!-- Summary is typically plain text and don't need encoding -->
      <summary>Hello, _weblog_ world!</summary>
      <body xmlns="http://www.w3.org/1999/xhtml">
        <p>Hello, <em>weblog</em> world! 2 &lt; 4!</p>
      </body>
    </content>

    <content type="text/html" mode="escaped">
      <body>
        &lt;p&gt;Hello, &lt;em&gt;weblog&lt;/em&gt; world! 2 &amp;lt; 4!&lt;/p&gt;
      </body>
    </content> 

    <content type="text/html" mode="cdata">
      <body><![CDATA[ <p>Hello, <em>weblog</em> world! 2 &lt; 4!</p> ]]></body>
    </content> 
    
    <content type="text/plain" mode="cdata">
      <body><![CDATA[ Hello, _weblog_ world! 2 < 4! ]]></body>
    </content>
  
    <content type="image/png" xml:lang="no-nb" href="/heisann.png" />
  </entry>
</feed>

Issues

Notes

Other Examples

Comments

[DavidJanes, DeleteOk] Time to split this page?

[DannyAyers, DeleteOk] a lot of it looks more like SyntaxConsiderations to me. Well, ok, perhaps with fewer Considerations.

[TimothyAppnel] This example seems like a rather silly reinvention of the wheel though as it has not incorporated sound elements of prior art.

If you have an issue, suggestion, or proposal for the above example, add it here:

Weblog vs Homepage

[TimBray] For people, the distinction between "homepage" and "weblog" seems shaky and of little value. Why don't we just limit ourselves to email address and web URI, this is what every comments system in the universe does and it seems to work fine.

[AaronSw] There seems to be a pretty clear distinction. For example, you have [WWW]a homepage and [WWW]a weblog. For many people these are on different domains (i.e. Cory Doctorow: [WWW]homepage, [WWW]blog, NormWalsh too, I think). While most UIs might only display one of these; I don't think it's a good idea to conflate them. You'll want the homepage when you want to know who someone is, but their weblog when you want to see what they think about something.

[DiegoDoval, RefactorOk] I agree with Tim: limit to one link, and with Asbjorn, change the name to something generic that encompases both weblog and homepage and identifies the "tracking back" to the source, which is I think the idea. Aaron's point is a good one, since homepages and weblogs are different. However, in practice either one will link to the other, and if people know that they want the homepage as opposed to the weblog (that is, if they belong to the group of people to whom the distinction makes sense at all), then they will know how to find one given the other. So I can't see a use-case for having two links: If it's a feed, intended to be used by tools and the weblog/homepage tags are meant to provide information about the creator, one link "back to the creator" is enough.

[DavidJanes, RefactorOk] Consider using an HTML <link>-link attribute, with roles and content being defined by "rel" and "name". Also considering how this can link to Foaf.

AdamRice +1 to DavidJanes. I humbly suggest using the Title attribute to suggest what kind of link it is, rather than getting hung up on the many different varieties of links that would be canonically supported. A recommended vocabulary--weblog, homepage, official site, etc--would satisfy those with a need for explicit definitions. A title-less link would be taken as the author's preferred link.

Content by reference?

See also "Sub Entries" below and MimeContent.

[AsbjornUlsberg] What if you want a <description> of the "href", then? <content type="image/jpeg" href="http://www.example.com/fishing.jpeg"><description>Me, fishing</description></content>. I did agree with you until Arve told me about that situation, then I realised that it's best to have the link as an sub-element of <content> instead of as an attribute.

[TimBray] I think content-by-reference gets us into all sorts of problems that we don't have to solve for Echo 1.0. This is explicitly designed to contain things like XHTML that have all sorts of well-debugged machinery for pointing to external resources and describing them and so on, let's let the <content> take care of it.

[JamesSnell] I agree that content-by-reference can be pushed off and revisited post 1.0 if it is deemed necessary.

[ChrisWilper] I'm strongly favor of content by reference as an option, but recommending that if it's XML-based, to inline it. What sorts of problems are you wary of, Tim and James? Examples please? I work with a format called [METS http://www.loc.gov/standards/mets/] that takes care of this kind of thing just fine. It seems to buy a lot of flexibility for little cost to me. I think including a href in a chunk of XHTML instead is kludgy. It has different meaning than pointing to the content straight from the content element.

[LachlanCannon] The model that makes sense to me is having <content type="whatever" [href="whatever"]>Text</content>. That is, an optional href, if it's not present then the contents of the element are the content If it is present, then the resource it points to is the content, and the contents of the content element (ugh) are a fallback for UAs which are unable to fetch or display the specified href.

Attributes vs. Elements

See ElementsVsAttributes

[JamesSnell] I made "id" an attribute to reflect GeorgBauer's comments below about possibly using attributes for technical, non-content related pieces of information (such as content type, language, etc).

[AsbjornUlsberg] I think attributes has it's usage, specifically for data that shouldn't be visible to any end-user. I think there are many elements in the existing RSS standard that should be attributes, and not to mention more generic naming, so that the attribute's value don't always have to be an alias for "true/false". E.g; Instead of "base64Encoding='true'", it should of course be "encoding='base64'".

[GeorgBauer] An idea: maybe restrict attributes for "technical, non-content" stuff? For example this way the type is something that should be noted with an attribute, as it describes the content of an element, and is not the actual content itself. This way I think the "id" element should be an id attribute at the entry element - this would make clear the destinction Sam gave in his comment, as the id attribute denotes some technical identification, but the permalink element denotes the actual link for the entry. This could give a way to select date formats, too: just have a format attribute at every timestamp element that gives "iso" or "rfc822" or some other denotion of format.

[DannyAyers, RefactorOk] my personal preference would be to use elements for the stuff and attributes for modifiers - exactly as in the use of type here.

If that's the case, isn't the type redundant?

[BillHumphries] No. For example, I've got 5 years worth of blog entries, a couple thousand, and I know (but have been too lazy to fix) that many are not valid. So you need the type in order to tell whatever's marshalling the entries what to do. And the CMS has to do the right thing when generating an Echo element.

[JamesSnell] Are we coming to a design style decision now that we're ready to vote on?

[AaronSw] I'm not sure it's a good idea to vote on design principles at this stage. It might be better to take these things on a case-by-case basis.

[KenMacLeod] +1 on premature. Note that RelaxNg supports a design where data can be in either elements or attributes, allowing the benefits of either.

Is ID an ID?

This is still being discussed. See PermaLinks, EntryIdentifier, and PostIdSpec.

[JamesSnell] In the schema, the id attribute is defined as an xsd:ID so it is an ID in the technical XML sense. This has the double effect of allowing entries to be referenced directly using the URI#id scheme which makes XML digital signatures and other interesting types of things easier (without an id attribute, we'd have to use XPath mapping to directly identify a given entry within a document). Sure, it is a bit limiting, but it has its uses.

[AaronSw] Consensus seems to be that ID should be a URI, which is definitely not an xsd:ID. (Neither are integers, which seems to be the other possibility.)

[JamesSnell] Ok, consider this. The <entry> entry-id as far as the conceptual model of a WellFormedEntry is concerned is related as an Element. The <entry> id as far as having a technical reference point for things like digital signatures, URI addressing of specific <entry> element references would use an attribute. <entry-id> is a URI that identifies the WellFormedEntry. the id attribute is an XML ID that identifies a specific serialization of the WellFormedEntry. Would that clear up the issue? I've updated the example to reflect this approach

[AaronSw] I don't want to name the id element entry-id, because a) it's already (duh) in an <entry>, and b) it prevents the same element from being reused. I'm wary about adding a per=element ID because it would really have to be required to be useful, and it's difficult to do right and we already have an ID (although it's funky)... Hm, this is complicated.

[JamesSnell] But it is an ID with different semantics... one relating to the conceptual entry, the other relating to the specific individual serialization of it. They serve two distinct purposes. I'm not as concerned about what they are named as much as I am about having the ability to directly reference, on a technical level, an individual <entry> element independent of it's semantic ID.

[DonPark] It is a mistake to overload 'id' attribute with semantics deviating from xsd:ID. Adding a prefix to the name like 'entry' makes sense.

[BillDehora] Add me to Aaron's consensus - I don't like the idea of baking xsd types into id. And the locator-id thing is old permathread ground. A entry can have a locator distinct from its identifier. To my mind they're both URIs and if they happen to be same, that's cool.

[MartinAtkins] If we want to decrease verbosity, maybe we can allow the per-entry ids to optionally be relative URLs of a URL given just once in the document. This way there'd be less repeated http://www.mysite.com/blog/entries/ which would save quite a lot of bandwidth, I'd hazard.

It needs to be optional, though, because if it isn't it becomes impossible to re-syndicate multiple feeds in aggregate form. An example of this is the LiveJournal 'friends page' which has entries from several different 'blogs' each with its own base URL, but there are certainly other feeds right now which exist as an aggregate of others although admittedlyI cannot name one off the top of my head. (in RSS, this aggregation is often painful, but Echo or whatever would make it a lot cleaner)

xml:lang location

[ArveBersvendsen, RefactorOk, DeleteOk] Moved the xml:lang attribute to the root element to reflect that the entire feed can use a default language, and with specific overrides if neccessary (as shown with xml:lang="en-gb"). If this is offensive, please change it back.

[LachlanCannon, RefactorOk] Makes sense to me. Having to specify the same language for each entry seems ridiculously redundant. not everyone will be using programs to generate these feeds, after all.

[KenMacLeod] [WWW]XML defines xml:lang as "A special attribute named xml:lang may be inserted in documents to specify the language used in the contents and attribute values of any element in an XML document." and clarified "The intent declared with xml:lang is considered to apply to all attributes and content of the element where it is specified, unless overridden with an instance of xml:lang on another element within that content."

The distinction I see is that xml:lang tells you what language is used within elements of "this" XML instance and some other attribute (echo:language) tells you things like "this fead is in <echo:language>" or "this piece of content is in <echo:language>". The use of xml:lang on the <content> element may be a gray area. Particularly, it may not be obvious to a developer that the xml:lang attribute needs to be carried with the content if it's aggregated into a different content. echo:language is very obvious.

[MaciejCeglowski, RefactorOk] It should be possible to have multiple lang attributes on an entry, because there are bloggers out there who mix languages in their writing. This seems particularly frequent in non-English tech blogs, where people switch in and out.

Authors versus persons and roles

[AsbjornUlsberg] This goes in the same line as I've been going this whole time; that elements and attributes should be as generic as possible. Therefore I think the <author>, and of course also the <contributor> elements should begone, and rather introduce one new element that replaces both of them; <person>. Each person with relations to the <entry> has a specific role; <person role="author" />, <person role="painter" /> e.g. The sub-elements of <person> is of course still up to debate, but I don't think it's appropriate to lock ourselves into the "author"-perspective.

[KenMacLeod] I generally agree with the use of roles or qualifiers to specialize attributes. In this context, though, DublinCore provides definitions for 'creator', 'contributor', and 'publisher' and I believe that should be taken into consideration.

[DavidJanes, RefactorOk] As per my comments on [SyntaxConsiderations], consider renaming "Author" to "Poster" or "Creator". Make this element required and narrow as possible. Then all other contributor types can fit in under the generic <person role="..."> type.

GaryFIf we are to have role attributes instead of elements, then the acceptable role values should be specified (extensible through namespaces). This way aggregators know exactly what they're looking at. i.e. an author is always "author", and not "writer".

[DannyAyers] The biggest problem with person + role is that the interpretation of any enclosed elements/attributes or even what would be allowed would vary according to the value of the role. At best it makes it harder to interpret, at worst it means that the syntax can't be validated. I'd strongly suggest taking advantage of the work done by DublinCore on this. It's simple to do but sophisticated in what it can describe, and standard.

[BillDehora] What Danny and Ken said. Use the Dublin Core elements. If you happen to use different names for them, then just say what they are wrt DC.

[AsbjornUlsberg] I'm not sure about this, but what I understand from Dublin Core, is that an "element" isn't necessary an XML element, it's a concept of naming; it's a containter for data which has a predefenition. When looking at [WWW]Encoding Dublin Core Metadata in HTML, I think this comes out clear. All DC "elements" are prefixed with "DC." and are serialized into <meta> HTML elements to provide the information somehow, in HTML documents. This is because you can't just introduce <ctreator> tags in HTML without breaking the DTD, and even valid through custom DTD's, no UA will understand it.

I think this manifests the principal; DC elements doesn't necessarily have to be XML elements. The point is that we adopt the concept and names from DC, and take it from there. If we feel like plunging "creator" into an attribute, that's OK, but the values of the attribute "rel" (in this case) has to be an enumeration of the DC elements. If one wants to extend this, it can be done through namespaces. Give me a smack if I've misunderstood DC completely, but do it gentle, OK? ;)

Versioning

[AsbjornUlsberg, RefactorOk, DeleteOk] Added the Echo version number (1.0) to the Echo namespace. It's logical that both namespaces, schemas, DTD's and such change with each version of Echo, thus we don't need a "version" attribute. Comments on this are welcome and wanted. I also added an "e"-prefix to the ID's.

[TimBray] I think it would be a big mistake to embed the version number in the namespace name. HTML had a big fight about this, and it's also an issue over at the [WWW]W3C TAG. The conclusion seems to be that namespace names are for fine-grained identification: "this is HTML", "this is SVG". On the other hand, putting a version="1.0" on the root element would probably be a really good idea.

Sub-Entries

[AsbjornUlsberg] If you want to specify one or more images for an entry, the best way to do this imho, is to nest <entry>'s, with content type and "permalink" set. This goes for threaded <entry>'s as well, in discussions and such. Allowing the <entry> element to contain another <entry> element, gives a lot of room for rich entries without doing a lot of work in the specification. Once the <entry> type is defined, we have it.

[JamesSnell] I disagree. Take email as an example. If I want to include multiple images in a single note,

Avoiding duplication of author data

[SimonWillison] I am unhappy with the need to provide full author information for every entry: the duplication of author data adds unnecessary additional information, making feeds larger than they need to be and increasing the effort needed to parse a feed (it also makes hand-rolled feeds harder to maintain). I propose using reference attributes instead. I have posted an example of such a feed at EchoFeedWithAuthorRefs.

[AsbjornUlsberg] Looks like an ok solution to me. Also, I think everything <feed> has in common with <entry> should be inherited by <entry>, and overridden in the <entry> if needed. These common properties are e.g. dates, authors, language etc.

Relative links

[LachlanCannon, RefactorOk] This seems to have been lost at some stage: I believe that relative links in echo feeds should be allowed via xml:base.

[AsbjornUlsberg, RefactorOk] The "xml:base" was in my Echo example which got lost. You can view the example in [WWW]an older version of this page. I also believe we need relative links.

[GaryF] Any reason why it was removed? Seems like the perfect solution. I say add it back in.

[AsbjornUlsberg] The reason why my example was removed, was because of some error while somone saved this page, so just parts of the text got from the browser to the server (or something like that). Is it ok that I edit the current example at the top, or should I repost my example at it's own as I did last time?

[TimBray] +1 on xml:base

[ZhangYining] +1 on xml:base, but in trackback entries, xml:base override the feed's xml:base, agree?

[GaryF, RefactorOk] As no-one has complained so far, I'm adding it back in now. Should an example of a relative link be added to an entry to demonstrate?

[AsbjornUlsberg, RefactorOk] I've overwritten the example with "my" version of it, because I feel it reflects the outcome of different discussions more than the one that was. E.g. I hate the usage of the <weblog> element in <author>, and the worst part is that many of these elements are being taken into other examples on this wiki. I hope no one gets offended by my overwriting; if they are, make a comment about it, and we might just go back in history and overwrite "my" example again.

Tools

RSS to Echo converter http://www.kbcafe.com/iBLOGthere4iM/comments.aspx?guid=20030702080054

Echo to RSS converter http://www.kbcafe.com/iBLOGthere4iM/comments.aspx?guid=20030703091858

RSS2 to SAM (formerly (n)ECHO) converter (XSLT-msxml3) http://cybarber.ath.cx/TestingwithSources.htm

SAM(necho),RSS2/RSS1 to CDF (Channel Definition Format) converter(XSLT-msxml3) http://cybarber.ath.cx/TestingwithSources.htm

Patch to add Echo support to the Straw aggregator http://www.licquia.org/code/straw-0.18.1-necho-0.1-patch.diff

more Tools

CategorySyntax, AuthorElement, LinkElement, IdElement, IssuedElement, ModifiedElement, ContentElement