Armonía | En definitiva...

Revisando documentación para una pequeña idea que tengo en mente, me topé con este fantástico documento introductorio sobre la tecnología Atom. Y aprovechando la ocasión, voy a hacer una "traducción libre" para que podais disponer de ella como gusteis, pero recordad que el texto original es de la AtomEnabled Alliance y que esto es sólo una traducción libre.

¿Que es Atom?

Atom es el nombre de un formato de sindicacion para contenidos y metadatos basado en XML, además de un protocolo para la publicación y edición de recursos Web en sitios que se actualizan con frecuencia.

Todos los feeds Atom deben ser documentos XML bien formados, y se han de identificar con el media type application/atom+xml

Consideraciones generales:

• Todos los elementos descritos en este documento deben estar en el namespace http://www.w3.org/2005/Atom
• Todas las fechas en Atom deben corresponderse al RFC 3339
• A no ser que se especifique lo contrario, todos los valores deben estar en texto plano, (p. ej., nada de texto HTML codificado con entidades)
• xml:lang puede usarse para identificar el lenguaje de cualquiero texto legible para las personas
• xml:base puede usarse para controlar cómo se resuelven las URI relativas

Feed Atom de ejemplo

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">

  <title>Example Feed</title>
  <link href="http://example.org/"/>

  <updated>2003-12-13T18:30:02Z</updated>
  <author>
    <name>John Doe</name>
  </author>
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>

  <entry>
    <title>Atom-Powered Robots Run Amok</title>
    <link href="http://example.org/2003/12/13/atom03"/>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>

    <updated>2003-12-13T18:30:02Z</updated>
    <summary>Some text.</summary>
  </entry>

</feed>

Elementos de <feed>

Un feed está formado por algunos metadatos seguidos por una serie de entradas.

Elementos requeridos en <feed>

Aquí tenemos una lista de los elementos obligatorios en un feed, cada uno con una pequeña explicación y un ejemplo.

id

Identifica al feed usando una única y permantente URI.

<id>http://example.com/</id>

title

Contiene el título del feed, (en un formato legible para las personas). Normalmente es el mismo que el del sitio Web al que está asociado el feed. Esta valor no puede estar en blanco.

<title>Example, Inc.</title>

updated

Indica la última vez que el feed fué modificado de alguna forma significativa.

<updated>2003-12-13T18:30:02Z</updated>

Elementos recomendados dentro de <feed>

Atom tiene una serie de elementos recomendados que deberías tener en cuenta. Estos elementos son:

author

El nombre del autor del feed. Un feed puede tener diversos autores, y por tanto diversos elementos author, pero como mínimo ha de tener uno, a no ser que todos los elementos entry tengan al menos un elemento author.

<author>
  <name>John Doe</name>
  <email>JohnDoe@example.com</email>
  <uri>http://example.com/~johndoe</uri>
</author>

link

Identifica una página Web relativa al feed. El tipo de relación viene definido por el atributo rel. Un feed está limitado a un elemento link con un rel con valor alternate por type y hreflang. Un feed debería tener un enlace referenciandose a si mismo. Ejemplo:

<link rel="self" href="/feed" />

Elementos opcionales dentro de <feed>

Aquí hay una lista de elementos opcionales que pueden estar en <feed>:

category

Especifica una categoría a la que el feed pertenece. Un feed puede pertenecer a diversas categorías, por lo que puede tener diversos elementos category.

<category term="sports"/>

contributor

Especifica un colaborador en la creción del feed. Un feed puede tener más de un elemento contributor.

<contributor>
  <name>Jane Doe</name>
</contributor>

generator

Identifica el software usado para generar el feed. Esta información se usa para operaciones de debugging por ejemplo. Tanto el atributo uri como el atributo version son opcionales.

<generator uri="/myblog.php" version="1.0">
  Example Toolkit
</generator>

icon

Identifica una imagen pequeña que da una información visual icónica del feed. Los iconos han de ser cuadrados.

<icon>/icon.jpg</icon>

logo

Identifica una imagen mayor que ofrece una identificación visual para el feed. Las imágenes deberían ser el doble de anchas que de largas.

<logo>/logo.jpg</logo>

rights

Especifica información sobre los derechos del feed, como por ejemplo el copyright.

<rights> © 2005 John Doe </rights>

subtitle

Contiene una descripción o un subtítulo para el feed. Debe estar escrita en un formato entendible por personas.

<subtitle>all your examples are belong to us</subtitle>

Elementos en <entry>

Un ejemplo de "entrada" sería un post en un weblog.

Elementos requeridos en <entry>

Aquí hay una lista de los elementos requeridos dentro del elemento entry, junto con una breve descripción y un ejemplo.

id

Identifica la entrada usando una URI permanente y universal. Dos entradas pueden tener el mismo id si ambas representan a la misma entrada en diferentes momentos.

<id>http://example.com/blog/1234</id>

title

Contiene un título para la entrada en formato legible por personas. Este valor no puede quedar en blanco.

<title>Atom-Powered Robots Run Amok</title>

updated

Indica la última vez que la entrada fué modificada de manera significativa. Este valor no necesita ser cambiado después de una modificación pequeña, como por ejemplo una corrección ortográfica. Como norma general, cada entrada tendrá un valor distinto en este elemento.

<updated>2003-12-13T18:30:02-05:00</updated>

Elementos recomendados en <entry>

Atom tiene una serie de recomendaciones para el elemento entry que deberías tener en cuenta:

author

Nombra un autor de la entrada. Una entrada puede tener diversos autores, y debe contener al menos un elemento author a no ser que exista, como mínimo, un elemento author para el elemento feed.

<author>
  <name>John Doe</name>
</author>

content

Contiene o enlaza al contenido de la entrada. El elemento content es obligatorio si no hay un elemento link alternativo, y debería ofrecerse si no hay un elemento summary.

<content>complete story here</content>

link

Especifica una página Web relacionada con la entrada. El tipo de la relación viene definida por el atributo rel. Una entrada sólo puede tener un enlace con el atributo rel con valor alternate por type y hreflang. Además, una entrada debe contener un link con un rel con valor alternate si no contiene un elemento content.

<link rel="alternate" href="/blog/1234"/>

summary

Contiene un pequeño resumen o parte del comienzo de una entrada. El elemento summary debería ofrecerse si no hay un elemento content para la entrada, o si el contenido de content está especificado en linea, (p. ej., a través del atributo src), o si el contenido está codificado como base64.

<summary>Some text.</summary>

Elementos opcionales en <entry>

Aquí hay una lista de elementos opcionales dentro del elemento <entry>

category

Especifica una categoría a la que pertenece la entrada. Una entrada puede tener más de una categoría, por lo que el elemento entry puede contener más de un elemento category

<category term="technology"/>

contributor

Nombra un colaborador que haya participado en la creación de la entrada. Una entrada puede tener más de un colaborador.

<contributor>
  <name>Jane Doe</name>
</contributor>

published

Contiene la fecha de publicación de la entrada

<published>2003-12-13T09:17:51-08:00</published>

source

Si una entrada se ha copiado de un feed a otro, entonces los metadatos del feed original, (todos los elementos hijos del elemento feed que no sean elementos entry), deberían conservarse si el feed de origen contiene alguno de los elementos author, contributors, rights o category y esos elementos no están presentes en el elemento entry de orígen.

<source>
  <id>http://example.org/</id>
  <title>Fourty-Two</title>
  <updated>2003-12-13T18:30:02Z</updated>
  <rights>© 2005 Example, Inc.</rights>
</source>

rights

Contiene información sobre los derechos sobre la entrada, (p. ej., el copyright).

<rights type="html"> © 2005 John Doe </rights>

Construcciones comunes

Categoría

El elemento category tiene un atributo obligatorio, term, y dos atributos opcionales, scheme y label.

• term identifica la categoría
• scheme identifica el esquema de categorización mediante una URI
• label da a la categoría un nombre legible por personas

Contenido

El elemento content contiene o bien un enlace al contenido de la entrada, o bien el contenido en si mismo.

En la mayoría de los casos, el atributo type tiene como valor text, html o xhtml, e indica el formato del texto que contiene.

Por otro lado, si el atributo src está presente, éste identifica una URI donde se puede encontrar el contenido. En este casi, si el atributo type está presente, indica el media type del contenido.

Si el atributo type termina con +xml o /xml, entonces un documento xml del tipo definido está contenido en linea.

Si el atributo type empieza con text, entonces significa que un documento en linea sin marcar está contenido en el elemento.

Enlace

El elemento link tiene un atributo requerido, href, y cinco atributos opcionales: rel, type, hreflang, title y length.

href contiene una URI para el recurso especificado, (normalmente una página Web).

rel contiene el tipo de relación del enlace. Puede ser una URI completa o uno de los siguientes valores predefinidos, (el valor por defecto es alternate):

• alternate: especifica que el enlace es una representación alternativa de la entrada o del feed, por ejemplo un permalink o una versión HTML de la entrada, o bien la página principal de un blog.
• enclosure: un recurso asociado que es demasiado grande en tamaño y que puede requerir un tratamiento especial, como por ejemplo una grabación de audio o de video.
• related: un documento relacionado con la entrada o el feed
• self: el feed en si mismo
• via: la fuente de información que ha propiciado la entrada

type indica el media type del recurso.

hreflang indica el lenguaje del recurso referenciado.

title indica un texto informativo en formato legible por personas sobre el enlace, normalmente se usa como nombre para el enlace.

length indica el tamaño del recurso, en bytes.

Persona

author y contributor describen una persona, corporación o entidad similar. Tiene un elemento obligatorio, name, y dos opcionales, uri y email.

name especifica un nombre para la persona en formato legible para usuarios no-máquinas.

uri contiene la página principal de la persona, (normalmente su página personal, blog o similar).

email contiene la dirección de correo electrónico de la persona.

Texto

title, summary, content y rights contienen texto legible por personas, normalmente en pequeñas cantidades. El atributo type determina la forma en la que esta información está codificada, (el valor por defecto es text):

Si type="text", entonces el elemento contiene texto plano sin código HTML escapado.

<title type="text">AT&amp;T bought by SBC!</title>

Si type="html", entonces el elemento contiene caracteres HTML escapados.

<title type="html">
  AT&amp;amp;T bought &lt;b&gt;by SBC&lt;/b&gt;!
</title>

Si type="xhtml", entonces el elemento contiene XHTML en linea, englobado en un elemento div.

<title type="xhtml">
  <div xmlns="http://www.w3.org/1999/xhtml">
    AT&amp;T bought <b>by SBC</b>!
  </div>
</title>