| TOC |
|
This document is an Internet-Draft and is NOT offered in accordance with Section 10 of RFC 2026, and the author does not provide the IETF with any rights other than to publish as an Internet-Draft.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”
The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
This Internet-Draft will expire on October 7, 2009.
This document specifies a JSON-based web content and metadata syndication format.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (, “,” .) [RFC2119].
1.
Introduction
1.1.
Notational Conventions
1.2.
Relationship to the Atom Syndication Format
2.
Object Types
2.1.
Item
2.2.
Feed
2.3.
Entry
2.4.
Person
2.5.
Link
3.
IANA Considerations
4.
Normative References
§
Author's Address
| TOC |
This specification describes a JSON-based data schema that that describes lists of related information known as "feeds". Feeds are composed of a number of items, known as "entries", each with attached metadata. For example, each entry has a title.
| TOC |
This specification describes conformance in terms of two artifacts: Feed Objects and Entry Objects. Additionally, it places some requirements on Processors.
This specification is specified in terms of the constructs defined in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.).
When describing the structure of a JSON object, a list of the following form will be used:
- title : string
- REQUIRED. The title of the entry.
- links : array<Link>
- An array of Link objects giving links for which this entry is the source.
The "title : string" notation indicates a property whose value is of type "string". Types that are all lowercase refer to fundamental types defined in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.). Types that are in CamelCase refer to object types defined within this specification. The notation "array<Link>" indicates a JSON array structure whose members are all of type "Link"; this might be read as "array of Link". The "REQUIRED" prefix on a property indicates that it may not be omitted and must always have a value of the specified type, though unless otherwise stated that value may be the type's empty value.
Unless otherwise stated, all properties of an object are optional. An omitted property is considered to be equivalent to a property whose value is explicitly given as null. null is an acceptable value for properties of any type that are not explicitly marked as required.
The order in which properties are defined is not significant. Publishers may produce objects with properties in any order, but MUST NOT include the same named property more than once within a given object.
Some properties may be defined as accepting multiple types using the "or" combinator. For example, the type "string or number" indicates that a property may accept either a string or a numeric value.
The special type "html" is used to describe a JSON string which contains a string of characters that would be valid if used within a DIV container element in an HTML document, as defined by [HTML5] (Hickson, I. and D. Hyatt, “HTML 5,” February 2009.). Since JSON strings are strings of unicode characters rather than octets, care may be required in some implementations to ensure that the default character encoding of an HTML parser used to parse the content of such a string is correctly configured to match the encoding of the string in that implementation's internal string representation.
The special type "time" is used to describe a JSON string which contains a timestamp using the syntax described in [RFC3339] (Newman, C. and G. Klyne, “Date and Time on the Internet: Timestamps,” July 2002.). In addition, an uppercase "T" character MUST be used to separate date and time, and an uppercase "Z" character MUST be present in the absence of a numeric time zone offset.
The special type "iri" is used to describe a JSON string which contains an IRI as defined in [RFC3987] (Düerst, M. and M. Suignard, “Internationalized Resource Identifiers (IRIs),” January 2005.). Note that the definition of "IRI" excludes relative references. Though the IRI might use a dereferencable scheme, Atom Processors MUST NOT assume it can be dereferenced. Because of the risk of confusion between IRIs that would be equivalent if they were mapped to URIs and dereferenced, the following normalization strategy SHOULD be applied when generating values for properties of type "iri":
The description of a given object or one of its properties may impose additional constraints in addition to those described using this notation.
| TOC |
[RFC4287] (Nottingham, M. and R. Sayre, “The Atom Syndication Format,” December 2005.) defines an XML-based Document format for representing feeds and entries. This specification is based on the high-level concepts used by the Atom Syndication Format, but it does not attempt to provide a format that can be transformed mechanically to or from Atom without loss.
The Atom Syndication Format is designed to be extensible via the namespacing features offered by XML. The JSON-based schema defined by this specification is not designed to be extensible, instead incorporating some commonly-used extensions into the core specification to cater for common use-cases only. If extensibility is required for a particular application, Atom may be a better choice of representation format for that application.
| TOC |
The following sections describe the object structures that can be used to represent feeds, entries and other ancillary objects.
| TOC |
Item is the abstract supertype of both Feed and Entry. The Item type has the following properties:
- id: iri
- REQUIRED. Conveys a permanent, universally unique identifier for a the item. When an item is relocated, migrated, syndicated, republished, exported, or imported, the content of this property MUST NOT change.
- title : html
- REQUIRED. Conveys a human-readable title for the item.
- updated : time
- Indicates the most recent instant in time when the item was modified in a way the publisher considers significant. Therefore, not all modifications necessarily result in a change to the value of this property.
- author : Person
- Indicates the author of the item.
- contributors : array<Person>
- Indicates people or other entities who contributed to the item.
- categories : array<Category>
- Conveys information about categories associated with the item.
- links : array<Link>
- Defines a reference from this item to a web resource.
| TOC |
A Feed object represents a feed. The Feed type extends the abstract type "Item" and has the following additional properties:
- entries : array<Entry>
- The list of entries that are contained within the feed.
- subtitle : html
- Conveys a human-readable description or subtitle for the feed.
| TOC |
An Entry object represents an entry. The Entry type extends the abstract type "Item" and has the following additional properties:
- content : html
- Conveys the body content of the entry. This is a human-readable representation of the entry that may be presented to a user alongside the entry title, author and links.
- summary : html
- Conveys a short summary, abstract, or excerpt of the entry.
- source : Feed
- If an entry is copied from one feed to another feed, a copy of the original feed element with the entries property set to null SHOULD be provided in the source property in the copy of the entry if the original entry does not already have a value for source.
- inReplyTo : Entry
- If present, indicates that that this entry is in response to the entry described by the value. The entry object MAY contain only a subset of the properties of the original entry, and MAY contain a "self" Link indicating a location from which the full representation can be retrieved.
| TOC |
A Person object represents a person, corporation, or similar entity. The Person type has the following properties:
- displayName : string
- Conveys the name of this person, suitable for display to end-users.
| TOC |
A Link object represents a reference to a Web resource. The Link type has the following properties:
- href : iri
- REQUIRED. Gives the IRI of the target resource.
- rel : string
- Indicates the link relation type. The value of this element must be valid as the value of the rel attribute on the atom:link element as described in section 4.2.7.2 of [RFC4287] (Nottingham, M. and R. Sayre, “The Atom Syndication Format,” December 2005.). If this property is omitted it must be processed as if the value were the string "alternate".
- type : string
- Indicates an advisory media type. The value is a hint about the type of the representation that is expected to be returned when the value of the href attribute is dereferenced. Note that the type attribute does not override the actual media type returned with the representation. Link elements MAY have a type attribute, whose value MUST conform to the syntax of a MIME media type.
- title : string
- Conveys a human-readable title for the link.
- length : number
- Indicates an advisory length of the linked content in octets; it is a hint about the content length of the representation returned when the IRI in the href attribute is mapped to a URI and dereferenced. Note that the length attribute does not override the actual content length of the representation as reported by the underlying protocol.
- total : number
- When the target resource is of a type that conveys a list of items, such as a serialized Feed object or an Atom Feed Document, indicates the total number of items in the target list.
- width : number
- When the target resource is a visual media item, for example if the media type is image/* or video/*, indicates the item's intrinsic or ideal width in pixels.
- height : number
- When the target resource is a visual media item, for example if the media type is image/* or video/*, indicates the item's intrinsic or ideal height in pixels.
- duration : number
- When the target resource is a time-based media item, for example if the media type is video/* or audio/*, indicates the item's approximate duration in seconds.
| TOC |
A Feed object, when serialized to a byte stream using the JSON grammar, can be identified with the following media type:
- MIME Media Type Name
- application
- MIME Subtype Name
- feed+json
- Required Parameters
- none
- Optional Parameters
- none
- Encoding Considerations
- As defined for application/json in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.).
- Security Considerations
- As defined for application/json in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.).
- Published Specification
- This specification.
- Applications that use this media type
- No applications are currently known to use this media type.
An Entry object, when serialized to a byte stream using the JSON grammar, can be identified with the following media type:
- MIME Media Type Name
- application
- MIME Subtype Name
- entry+json
- Required Parameters
- none
- Optional Parameters
- none
- Encoding Considerations
- As defined for application/json in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.).
- Security Considerations
- As defined for application/json in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.).
- Published Specification
- This specification.
- Applications that use this media type
- No applications are currently known to use this media type.
| TOC |
| [HTML5] | Hickson, I. and D. Hyatt, “HTML 5,” February 2009. |
| [RFC2119] | “.” |
| [RFC3339] | Newman, C. and G. Klyne, “Date and Time on the Internet: Timestamps,” July 2002. |
| [RFC3987] | Düerst, M. and M. Suignard, “Internationalized Resource Identifiers (IRIs),” January 2005. |
| [RFC4287] | Nottingham, M. and R. Sayre, “The Atom Syndication Format,” December 2005. |
| [RFC4627] | Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006. |
| TOC |
| Martin Atkins |