Skip to content

Latest commit

 

History

History
327 lines (255 loc) · 18.2 KB

uber-hypermedia.asciidoc

File metadata and controls

327 lines (255 loc) · 18.2 KB
Raw

Uniform Basis for Exchanging Representations (UBER)

Table of Contents

1. Document Status

Author

Mike Amundsen, [email protected]

Status

Working Draft

Last Updated

2024-12-20

Proposed IANA Registrations

application/vnd.amundsen-uber+xml, application/vnd.amundsen-uber+json

Supported H-Factors

LO, LE, LT, LI, LN, CR, CU, CM, CL

2. General

The UBER message format is a minimal read/write hypermedia type designed to support simple state transfers and ad-hoc hypermedia-based transitions. This document describes both the XML and JSON variants of the format and provides guidelines for supporting UBER messages over the HTTP protocol.

2.1. Design Goals

The UBER message model has a number of design goals:

  • Keep the message structure as lean as possible.

  • Support all the H-Factors [HFactor].

  • Be compatible with multiple protocols (e.g. [HTTP], [CoAP], etc.)

  • Maintain fidelity for more than one base message format (XML, JSON, etc.)

2.2. Messages, Not Code

The UBER message model is designed to be a message format and not a source code format. It is optimized for cross-format use (XML and JSON) and not optimized to be directly serialized into source code or data objects. This is especially noticeable in the JSON variant of UBER. However, the UBER message model is designed to make it relatively easy to write a parser that can consistently transform UBER messages into object models (and back again).

2.3. Compliance

An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED elements. An implementation that satisfies all the MUST and REQUIRED elements as well as all the SHOULD and RECOMMENDED elements is said to be "unconditionally compliant"; one that satisfies all the MUST and REQUIRED elements but not all the SHOULD and RECOMMENDED elements is said to be "conditionally compliant."

Note

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].

3. The UBER Message Model

The UBER message model is very minimal. There are three elements, eleven possible properties, and seven reserved string values.

3.1. Elements

There are only three elements in the UBER message model:

<uber>

The root element of all UBER messages

<data>

The main element in UBER messages.

<error>

The element that carries error details from the previous request.

3.2. Properties

There are eleven properties in the UBER design:

id

The document-wide unique identifier for this element.

name

A document-wide non-unique identifer for this element.

rel

Contains one or more link relation values.

url

A resolvable URL associated with this element.

action

The network request verb associated with this element.

transclude

Indicates whether the content that is returned from the URL should be embedded within the currently loaded document

model

Contains a template to be used to construct URL query strings or request bodies depending on the value in the action property.

sending

Contains one or more media type identifiers for use when sending request bodies.

accepting

Contains one or more media type identifiers to expect when receiving request bodies.

value

In the XML variant of the UBER mesage format, inner text of the <data> element contains the value associated with that element. In the JSON variant there is a value property that contains the associated value.

version

Indicates the UBER message version information.

3.3. Reserved Strings

There are seven reserved strings used as possible values for UBER properties.

Reserved strings for the action property

  • append : An unsafe, non-idempotent request to add a new item.

  • partial : An unsafe, non-idempotent request to modify parts of an existing item.

  • read : A safe, idempotent request.

  • remove : An unsafe, idempotent request to delete an existing item.

  • replace : An unsafe, idempotent request to replace an existing item.

Reserved strings for the transclude property

  • true : embed the results of the request into the current document

  • false : treat the associated url value as a navigation to a new document.

3.4. Link Relation Values

There are no UBER-specific link relation values. Document authors SHOULD use registered link relation values that comply the guidance provided in RFC5988 [RFC5988] and from shared public sources such as:

3.5. Message Map

Below is a simple ‘map’ of the UBER message format (XML variant). Along with the three elements, there are ten properties (indicated by the ‘@’ character). The <data> element can appear as a child element of <uber> and <error> and may be nested as many times as needed.

UBER Message Model (XML)
link:includes/message-model.xml[role=include]

3.6. The <uber> Element

This is the root element of an UBER message. Every UBER message MUST have this as its root. The <uber> element has one optional property: version which carries the UBER message version information. For this release, all UBER messages SHOULD be set to the value of "1.0". If the version property is missing, it SHOULD be assumed to be set to "1.0".

Example <uber> Elements
<!-- XML format -->
<uber version="1.0">
...
</uber>

// JSON format
{"uber" : {"version" : "1.0", ...} }

3.7. The <data> Element

The <data> element is the key element in the model. A valid UBER message SHOULD contain at least one <data> element. If it does appear, the <data> element appears as a child of the <uber> or <error> elements. The <data> element MAY be nested as many times as needed. The <data> element has the following property (all properties are OPTIONAL):

id

The document-wide unique identifier for this element. The value of id must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods ("."). If the id property is present, it SHOULD be treated as an in-document reference as described in section 3.5 of RFC3986 [RFC3986].

name

A document-wide non-unique identifer for this element. The value of name must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods ("."). If the name property is present it MAY be used as a variable in the UBER model property as described in [RFC6570].

rel

Contains a list of link relation values. These values SHOULD conform to the guidance provided in RFC5988 [RFC5988]. In the XML variant the list of link relation values appears as a space-separated list. In the JSON variant the list of link realtion values appears as an array.

url

A resolvable URL associated with this element. The value SHOULD conform to that described in RFC3986 [RFC3986].

action

The network request verb associated with this element. The list of valid values for this element are:

  • append : An unsafe, non-idempotent request to add a new item (e.g. HTTP.POST [RFC2616])

  • partial : An unsafe, non-idempotent request to modify parts of an existing item (e.g. HTTP.PATCH [RFC5789])

  • read : A safe, idempotent request (e.g. HTTP.GET [RFC2616])

  • remove : An unsafe, idempotent request to delete an existing item (e.g. HTTP.DELETE [RFC2616])

  • replace : An unsafe, idempotent request to replace an existing item (e.g. HTTP.PUT [RFC2616])

When the <data> element has a url property but no action property, it SHOULD be assumed the action property is set to read. Any value other than those listed here SHOULD be treated as read.

transclude

Indicates whether the content that is returned from the URL should be embedded within the currently loaded document (transclude="true") or treated as a navigation to a new document (transclude="false"). If the property is missing, it SHOULD be assumed to be set to false (e.g. navigation).

model

Contains a RFC6570-compliant [RFC6570] string to be used to construct URL query strings or request bodies depending on the value in the action property. Variables in UBER model strings SHOULD be resolved using the values from name properties, but MAY come from any source available to the client application. If the action property is set to read or remove then the model is applied to the query string. If the action value is set to append, partial, or replace then the model is applied to the request body.

sending

Contains one or more media type identifiers for use when sending request bodies. One of the supplied identifiers SHOULD be selected as a guide when formatting the request body. For HTTP implementations, the selected identifier SHOULD be used as the value for the Content-Type header. If this property is missing the setting should be assumed to be application/x-www-form-urlencoded as described in RFC1867 [RFC1867].

In the XML variant the list of media-type identifiers appears as a space-separated list. In the JSON variant the list of media-type identifiers appears as an array.

accepting

Contains one or more media type identifiers to expect when recieving request bodies. The contents of this property SHOULD indicate the formats in which the server is able to return a response body. For HTTP implementations the contents of this property SHOULD be used as the value for the Accept header. If this property is missing, the setting should be assumed to be set to the same value as that of the currently loaded representation (application/vnd.uber-amundsen+xml or application/vnd.uber-amundsen+json).

In the XML variant the list of media-type identifiers appears as a space-separated list. In the JSON variant the list of media-type identifiers appears as an array.

value

In the XML variant of the UBER mesage format, inner text of the <data> element contains the value associated with that element.

In the JSON variant there is a value property that contains the associated value. Note that the content of this field MUST NOT be a JSON object or array and MUST be one of the following scalar values (listed in Section 2.1 of RFC4627 [RFC4627]):

  • number

  • string

  • false

  • true

  • null

For both the XML and JSON variants, it is the responsibility of the document author to make sure the contents of the value property are properly escaped as needed (per Section 2.4 of [REC-XML] and Section 2.5 of [RFC4627]).

Example <data> Elements (XML)
link:includes/search-sample.xml[role=include]
Example <data> Elements (JSON)
link:includes/search-sample.js[role=include]

3.8. The <error> Element

The <error> element contains any error information returned by the server regarding the previous request. The <error> element has no properties. This is an OPTIONAL element. When present, it SHOULD contain one or more <data> child elements. It is the <data> child elements that contains error details.

Example <error> Element (XML)
link:includes/error-sample.xml[role=include]
Example <error> Element (JSON)
link:includes/error-sample.js[role=include]

4. Implementation Guidelines

Since the UBER messsage format was designed to work with multiple application protocols (HTTP, CoAP, etc.), there needs to be some guidelines for creating a protocol-specific implementation that supports UBER documents. Below is the HTTP guidance for UBER documents. This can be used as a guide in creating (and documenting) other protocol-specific implemenations.

4.1. Supporting UBER Documents over HTTP

This section decribes the details of implementing UBER support over HTTP.

4.1.1. Mapping UBER action Values to HTTP Methods

When implementating support for UBER documents over HTTP one of the key details is to map the value of UBER’s action property to HTTP methods. Table #1 below provides this mapping:

Table 1. Mapping HTTP Methods to UBER action and model Values
UBER Action HTTP Method UBER Model Modifies

append

POST

Request Body

partial

PATCH

Request Body

read

GET

Query String

remove

DELETE

Query String

replace

PUT

Request Body

4.1.2. Using UBER model Values to create HTTP Query Strings

When applied to HTTP, any model value associated with a data element with the action property set to read or remove MUST be converted into a valid query string. The follwing example shows how an UBER message snippet is converted into a valid HTTP query string:

Converting an UBER read Action into an HTTP Query String
link:includes/uber-query-string.txt[role=include]

4.1.3. Using UBER model Values to create HTTP Request Bodies

Any model value associated with a data element with the action property set to append, partial, or replace MUST be convereted into a valid HTTP request body. The follwing example shows how an UBER message snippet is converted into a valid HTTP request body:

Converting an UBER append Action into an HTTP Request
link:includes/uber-request-body.txt[role=include]

4.2. Supporting UBER Documents Over other Protocols

It is possible that UBER documents can be exchanged using a protocol other than HTTP. In that case, it is the responsibility of the implementor to provide a guideline document that covers the same material included in the "Implementation Guidelines" of the UBER Message specification.

5. Message Examples

UBER messages may appear in XML or JSON formats. Below are examples of each.

5.1. XML Example

Below is an XML Example of an UBER message.

XML Example
link:includes/full-example.xml[role=include]

5.2. JSON Example

Below is a JSON Example of an UBER message.

UBER JSON Example
link:includes/full-example.js[role=include]

6. Extensibility

This document describes the UBER message format markup vocabulary. Markup from other vocabularies ("foreign markup") can be used in an UBER document. Any extensions to the UBER Hypermedia vocabulary MUST not redefine any objects (or their properties), arrays, properties, link relations, or data types defined in this document. Clients that do not recognize extensions to the UBER vocabulary SHOULD ignore them.

The details of designing and implementing UBER extensions is beyond the scope of this document.

Note

It is possible that future forward-compatible modifications to this specification will include new objects, arrays, properties, link-relations, and data types. Extension designers should take care to prevent future modifications from breaking or redefining those extensions.

7. IANA Considerations

Below are the related IANA considerations for this media type design.

7.1. XML Media Type Registration

[pending submission]

7.2. JSON Media Type Registration

[pending submission]

7.3. Security Considerations

The XML variant of the UBER message format shares security issues common to all XML content types. It does not provide executable content. Information contained in UBER documents do not require privacy or integrity services.

The JSON variant of the UBER message format shares security issues common to all JSON content types. See RFC4627 Section #6 [RFC4627] for additional information. The UBER message format does not provide executable content. Information contained in UBER documents do not require privacy or integrity services.

7.4. Internationalization Considerations

The UBER message format does not have any internationalization considerations other than those which are discussed in referenced RFC documents (see below).

8. References

Below are the references used in this document.

8.1. Normative References

8.2. Informative References

9. Acknowledgements

The author would like to thank everyone who commented upon, encouraged, and gave feedback to this specification, especially Cédric Brancourt, Mark W. Foster, Steve Klabnik, Matthew McClure, Stephen Mizell, Irakli Nadareishvili.

.