UserPreferences

Syntax


Syntax

Abstract

Syntax is the normative document defining the WellFormedEntry format.

Status of this document

This document is in fluid motion, trying to capture the result of discussion, highlight ambiguous or under-defined areas, and raise visibility of significant issues in a concise, linear format for those unable to follow the wiki on a hourly or daily basis.

When complete, this document will be finalized by moving to a non-wiki format and prepared for publication.

At the bottom of each section are links to discussion covering the topics within the section. Please do not initiate discussions in this document, instead use an existing discussion page or create a new one.

In addition to the linked pages at the bottom of each section, this document specifically is also discussed on the [WWW]atom-syntax mailing list.

Professional writers are welcome, encouraged even, to make edits and suggestions on what the techies are writing.

Introduction

WellFormedEntry format conforms to Extensible Markup Language (XML) 1.0 (Second Edition) and XML Namespaces.

There are two primary XML document types, <feed> and <entry>. The <feed> type is for distributing metadata and, optionally, the content of a series of entries. The <entry> type can be used standalone in some contexts or used as element within feeds.

The namespace for the core elements is 'http://need/a/namespace'.

Schema Patterns

The syntax follows certain repeating patterns:


Primer, DontUseXml, InfoSetDiscussion, MultipleSyntaxDiscussion, NamespaceDiscussion, ToolSpecificConvenienceSyntax, ViewSourceClan, ElementsVsAttributes, PropertiesVsRoles, SchemaPatterns

Schema Patterns Comments & Discussion

(moved to SchemaPatterns)

Entry

An entry is defined as

EditEntryDefinition

entry


CategoryMetadata

Required entry elements include

EditAuthorElement

<author>


CategoryElementSpec

EditLinkElement

<link> (deprecated)


<link> (new version)

Expresses a relationship between an Atom entity and another resource.

Structure

<!ELEMENT link EMPTY>
<!ATTLIST link
    rel (#PCDATA) #REQUIRED
    href (#PCDATA) #REQUIRED
    type (#PCDATA)
    title CDATA>

(eg <link rel="alternate" href="http://www.example.org/blog/entry1" [type="text/html"] [title="This entry's webpage"']>)

Summary

Description

The LinkElement is used to express a relationship between a resource identified in an Atom feed and another "external" resource. The Atom resource is normally that associated with the parent of the link element (the link element may also be used to associate a schema name with a namespace, see below). The other resource is identified in the href attribute of the link element. The rel attribute defines the relationship between the two resources.

Relationship Values

The meaning of the rel attribute is determined in one of two ways. For terms defined in the Atom specification, the term may be used directly in the attribute, e.g.

   <link rel="inResponseTo"       type="application/x.atom+xml"       href="http://example.org/post123" />

The core terms are described at LinkTagMeaning For terms defined outside Atom, additional namespace-based qualification must be used.

Explicit Namespace

This method of defining the relationship uses a technique derived from that described in RFC 2731 (Encoding Dublin Core Metadata in HTML) . First an external schema is identified and its namespace identified with a schema name. This only needs to be done once per feed:

<feed>

...

Subsequently the schema may be referred to in individual link entries:

<entry>

...

(The # suffixed to the image.jpg url prevents this wiki from automagically displaying the image inline)

Implicit Namespace (Atom Core)

Much of the time the relationship schema used will be that defined in the Atom specification. To simplify the use of this a shorthand can be used. If there is no schema explicitly associated with the content of a rel attribute (using the method described above) then the value of the rel attribute is taken to refer to a term in the Atom namespace.

So this:

<feed> ...

<entry>

...

is equivalent to, and will be used in preference to:

<feed>

...

<entry>

The core terms are described at LinkTagMeaning


LinkElementDiscussion

CategoryElementSpec

EditIdElement

<id>


PostIdSpec


CategoryElementSpec

EditIssuedElement

<issued>


TimestampVsCreationDateTime

CategoryElementSpec

EditModifiedElement

<modified>


CategoryElementSpec

EditContentElement

<content>

<content type="application/xhtml+xml" xml:lang="en-us" rel="fragment"> 
  <p xmlns="...">Hello, <em>weblog</em> world! 2 &lt; 4!</p> 
</content>
<content type="audio/mpeg" src="http://example.org/blog/commentary.mp3" />
<content type="multipart/alternative">
  <content type="image/jpeg" encoding="base64">
    xo+Hello0AFWeblogh5FWorldh1mImagedsTbrVbF3
  </content>
  <content type="text/html" xml:lang="en-us" mode="escaped" rel="fragment">
    <![CDATA[<p>Hello, <em>weblog</em> world! 2 &lt; 4!</p>]]>
  </content>
  <content type="application/xhtml+xml" xml:lang="en-us" rel="fragment">
    <p xmlns="http://www.w3.org/1999/xhtml">
      Hello, <em>weblog</em> world! 2 &lt; 4!</p>
  </content>
</content>

content, ContentDiscussion, ContentAndPermalink, MultipleContentDiscussion, MimeContent, EscapedHtmlDiscussion, ContentProblems, ComponentBlog, AdaptiveBlogosphere


CategoryMetadata, CategoryElementSpec


ConceptualModel, EchoExample

Feed

A feed is most simply defined as

EditFeedDefinition

feed, channel:


ListOfFeeds

Typically, a feed is used by online journals or weblogs, defined as

EditWeblogDefinition

online journal, weblog

Required feed elements include

EditLinkElement

<link> (deprecated)


<link> (new version)

Expresses a relationship between an Atom entity and another resource.

Structure

<!ELEMENT link EMPTY>
<!ATTLIST link
    rel (#PCDATA) #REQUIRED
    href (#PCDATA) #REQUIRED
    type (#PCDATA)
    title CDATA>

(eg <link rel="alternate" href="http://www.example.org/blog/entry1" [type="text/html"] [title="This entry's webpage"']>)

Summary

Description

The LinkElement is used to express a relationship between a resource identified in an Atom feed and another "external" resource. The Atom resource is normally that associated with the parent of the link element (the link element may also be used to associate a schema name with a namespace, see below). The other resource is identified in the href attribute of the link element. The rel attribute defines the relationship between the two resources.

Relationship Values

The meaning of the rel attribute is determined in one of two ways. For terms defined in the Atom specification, the term may be used directly in the attribute, e.g.

   <link rel="inResponseTo"       type="application/x.atom+xml"       href="http://example.org/post123" />

The core terms are described at LinkTagMeaning For terms defined outside Atom, additional namespace-based qualification must be used.

Explicit Namespace

This method of defining the relationship uses a technique derived from that described in RFC 2731 (Encoding Dublin Core Metadata in HTML) . First an external schema is identified and its namespace identified with a schema name. This only needs to be done once per feed:

<feed>

...

Subsequently the schema may be referred to in individual link entries:

<entry>

...

(The # suffixed to the image.jpg url prevents this wiki from automagically displaying the image inline)

Implicit Namespace (Atom Core)

Much of the time the relationship schema used will be that defined in the Atom specification. To simplify the use of this a shorthand can be used. If there is no schema explicitly associated with the content of a rel attribute (using the method described above) then the value of the rel attribute is taken to refer to a term in the Atom namespace.

So this:

<feed> ...

<entry>

...

is equivalent to, and will be used in preference to:

<feed>

...

<entry>

The core terms are described at LinkTagMeaning


LinkElementDiscussion

CategoryElementSpec

EditModifiedElement

<modified>


CategoryElementSpec


EchoExample

Extensions

User-defined and modular extensions are allowed in <feed>, <entry>, and <author> elements. Those extensions must have names defined in namespaces.


SyntaxExtensionMechanism

Schemas

Non-Normative.


EchoSchema