Network Working Group J. Montoya
Internet-Draft Mountain State Software Solutions
Intended status: Informational February 26, 2019
Expires: August 30, 2019
Profiled Hypertext Application Language
draft-montoya-phtal-00
Abstract
This document defines PHTAL, a generic representation format for
hypertext applications guided by REST constraints. PHTAL could be
compared to HTML without graphical requirements.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
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."
This Internet-Draft will expire on August 30, 2019.
Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Montoya Expires August 30, 2019 [Page 1]
Internet-Draft phtal February 2019
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Definitions and Terminology . . . . . . . . . . . . . . . 2
1.1.1. Terminology and Conformance Language . . . . . . . . 3
1.1.2. General . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.3. Documents description . . . . . . . . . . . . . . . . 3
1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . 4
2. PHTAL Representations . . . . . . . . . . . . . . . . . . . . 4
2.1. Hypermedia as the engine of application state . . . . . . 4
2.1.1. Document Root . . . . . . . . . . . . . . . . . . . . 4
2.1.2. Link . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.3. Operation . . . . . . . . . . . . . . . . . . . . . . 9
2.1.4. HTTP Operation . . . . . . . . . . . . . . . . . . . 11
2.1.5. SecurityRequirement . . . . . . . . . . . . . . . . . 12
2.1.6. Partial . . . . . . . . . . . . . . . . . . . . . . . 13
2.2. Self-descriptive messages . . . . . . . . . . . . . . . . 14
2.2.1. Linking to a profile . . . . . . . . . . . . . . . . 15
2.3. Code-On-Demand . . . . . . . . . . . . . . . . . . . . . 16
2.3.1. Script . . . . . . . . . . . . . . . . . . . . . . . 16
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
3.1. application/phtal+xml . . . . . . . . . . . . . . . . . . 18
3.2. application/phtal+json . . . . . . . . . . . . . . . . . 19
4. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.1. Normative References . . . . . . . . . . . . . . . . . . 21
4.2. Informative References . . . . . . . . . . . . . . . . . 22
4.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 23
Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 23
B.1. How can I submit comments or feedback to the editors? . . 23
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 23
1. Introduction
This document defines PHTAL, a generic representation format for
hypertext applications guided by REST constraints. PHTAL could be
compared to HTML without graphical requirements.
This document registers two media-type identifiers with the IANA:
"application/phtal+json" and "application/phtal+xml". This
registration is for community review and will be submitted to the
IESG for review, approval, and registration with IANA.
1.1. Definitions and Terminology
Montoya Expires August 30, 2019 [Page 2]
Internet-Draft phtal February 2019
1.1.1. Terminology and Conformance Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
1.1.2. General
Representational State Transfer, or *REST*, is an architectural style
for distributed hypermedia systems. Introduced and first defined in
2000 in Chapter 5, REST, of the doctoral dissertation "Architectural
Styles and the Design of Network-based Software Architecture" by Roy
Fielding.
*Hypermedia*, or hypertext, is defined by the presence of application
control information embedded within, or as a layer above, the
presentation of information. Hypermedia allows for a virtually
unbound network of resources while also guiding users through an
application as they navigate said relationships.
A *hypermedia relationship*, also known as a link relation, describes
the semantics behind a virtual uni-directional association between
two resources.
A *hypermedia relationship name* is an identifier for a hypermedia
relationship.
A *resource* is the intended conceptual target of a hypertext
reference.
*Representational state* indicates the current state of the requested
resource, the desired state for the requested resource, or the value
of some other resource, such as a representation of the input data
within a client's query form, or a representation of some error
condition for a response.
*Application state* is the state of the user's application of
computing to a given task, controlled and stored by the user agent
and can be composed of representations from multiple servers.
1.1.3. Documents description
A trailing question mark, for example *description?*, indicates an
optional property.
Montoya Expires August 30, 2019 [Page 3]
Internet-Draft phtal February 2019
1.2. Motivation
The essential trade-off that REST makes when compared to an
architectural style like RPC is dynamic modifiability over
efficiency. Dynamic modifiability is the degree to which an
application can be changed without stopping and restarting the entire
system. This is what REST promises through the Uniform Interface,
and optionally Code-On-Demand, constraints.
Guided by these constraints PHTAL introduces the necessary elements
to enable application authors to create evolvable and extensible
applications.
2. PHTAL Representations
2.1. Hypermedia as the engine of application state
The Uniform Interface constraint dictates that hypermedia be the
engine of application state. This means that the state of the
application and its potential transitions are dictated by the
presence of hypermedia relationships in-band and by the navigation of
those relationships by an user (human or automated). In order for
users to traverse a selected relationship they depend on the server
to provide instructions for communicating with the target resource.
When servers provide control information at run-time instead of at
deploy-time, they retain control of their implementation space and
enable dynamic evolvability; they can change their implementation
without having to restart or deploy clients. Applications servers
are free to change their URI structure, they are free rearrange
resources into different servers, they are free introduce new links
that provide new features in existing representations, nothing will
break already deployed components as long as links are not broken.
PHTAL introduces generic but comprehensive hypertext markup so that
instead of creating and registering a new, application specific,
hypertext enabled media type, authors can choose to make use of
PHTAL's markup. This frees authors to spend most of their
descriptive efforts in defining application-specific representation
and possibly on extended link relations to drive application state.
2.1.1. Document Root
The in-band elements defined by PHTAL aim to provide just what's
necessary for agents to evaluate the hypertext relationship
alternatives provided and invoke the appropriate operation to get the
agent to the next application state.
Montoya Expires August 30, 2019 [Page 4]
Internet-Draft phtal February 2019
2.1.1.1. Properties
+-------------+---------------+-------------------------------------+
| Name | Type | Description |
+-------------+---------------+-------------------------------------+
| links? | Map["string", | The links element is a map where |
| | [Link | the keys are hypermedia |
| | (Section | relationship identifiers and the |
| | 2.1.2)]] | values are single or multiple Link |
| | | elements. The relationship |
| | | identifier MUST be a IANA |
| | | registered relation type or an URI |
| | | that when dereferenced resolves to |
| | | an XREL [I-D.draft-montoya-xrel-00] |
| | | document. |
| | | |
| operations? | [Operation | Informs an agent of what operations |
| | (Section | are allowed to be invoked on the |
| | 2.1.3)] | context resource. |
+-------------+---------------+-------------------------------------+
The operations element MAY be included as part of an HTTP GET
response body, or as the response body to an HTTP OPTIONS, for
example.
Detailed mappings to XML and JSON are provided through the
appropriate schemas in Section #5 of this document.
2.1.1.2. PHTAL examples
*JSON Representation Example*
Montoya Expires August 30, 2019 [Page 5]
Internet-Draft phtal February 2019
{
"name": [
{
"use": "official",
"family": "Chalmers",
"given": [
"Peter",
"James"
]
}
],
"_links": {
"https://api-docs.myclinic.com/fhir/rel/encounter": [{
"href": "http://fhir.myclinic.com/Encounter/1234",
"operation": {
"HTTP": {
"method": "GET",
"produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Encounter\",
application/phtal+xml;profile=\"http://hl7.org/fhir/encounter.xsd\""
}
}
}]
},
"_operations": {
"HTTP": {
"method": "PUT",
"consumes": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Encounter\",
application/phtal+xml;profile=\"http://hl7.org/fhir/encounter.xsd\""
"produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/OperationOutcome\",
application/phtal+xml;profile=\"http://hl7.org/fhir/operationoutcome.xsd\""
}
}
}
*XML Representation Example*
Montoya Expires August 30, 2019 [Page 6]
Internet-Draft phtal February 2019
<Patient xmlns="http://hl7.org/fhir" xmlns:phtal="http://www.phtal.org/v1/XMLSchema.xsd">
<id value="example"/>
<name>
<use value="official"/>
<family value="Chalmers"/>
<given value="Peter"/>
<given value="James"/>
</name>
<phtal:link rel="https://api-docs.myclinic.com/fhir/rel/encounter">
<phtal:href>http://fhir.myclinic.com/Encounter/1234</phtal:href>
<phtal:operation protocol="HTTP">
<phtal:method>GET</phtal:method>
<phtal:produces>application/phtal+json;profile="http://hl7.org/fhir/json-schema/Encounter",
application/phtal+xml;profile="http://hl7.org/fhir/encounter.xsd"
</phtal:produces>
</phtal:operation>
</phtal:link>
<phtal:operation protocol="HTTP">
<phtal:method>PUT</phtal:method>
<phtal:consumes>application/phtal+json;profile="http://hl7.org/fhir/json-schema/Encounter",
application/phtal+xml;profile="http://hl7.org/fhir/encounter.xsd"
</phtal:consumes>
<phtal:produces>application/phtal+json;profile="http://hl7.org/fhir/json-schema/OperationOutcome",
application/phtal+xml;profile="http://hl7.org/fhir/operationoutcome.xsd"
</phtal:produces>
</phtal:operation>
</Patient>
2.1.2. Link
2.1.2.1. Properties
Montoya Expires August 30, 2019 [Page 7]
Internet-Draft phtal February 2019
+----------------+---------------+----------------------------------+
| Name | Type | Description |
+----------------+---------------+----------------------------------+
| href | "string" | The link's target resource. The |
| | | href property MUST be a URI |
| | | [RFC3986] or a URI Template |
| | | [RFC6570]. |
| | | |
| uriParameters? | Map["string", | A map where the keys are the |
| | "string"] | names of the variables in the |
| | | href property when it is an URI |
| | | Template, and the values are |
| | | URIs that resolve to RAML 1.0 |
| | | Spec [RAML] Data Type |
| | | declarations explaining the |
| | | format and semantics of the |
| | | variables. |
| | | |
| operation? | Map["string", | The protocol specific operation |
| | Operation | for traversing this link. There |
| | (Section | SHOULD NOT be two operations for |
| | 2.1.3)] | the same protocol. |
| | | |
| partial? | Partial | A partial representation of the |
| | (Section | target resource. |
| | 2.1.6) | |
+----------------+---------------+----------------------------------+
When the operation element is not present the client SHOULD assume
that the required operation is an HTTP GET.
2.1.2.2. Link Examples
*JSON Representation Example*
Montoya Expires August 30, 2019 [Page 8]
Internet-Draft phtal February 2019
{
"href": "http://fhir.myclinic.com/Patient/{id}/{?_pretty,_elements}",
"uriParameters": {
"id": "https://api-docs.myclinic.com/fhir/patientId.raml",
"_pretty": "https://api-docs.myclinic.com/fhir/parameters/_pretty.raml",
"_elements": "https://api-docs.myclinic.com/fhir/parameters/_elements.raml"
},
"operation": {
"HTTP": {
"method": "GET",
"produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Encounter\",
application/phtal+xml;profile=\"http://hl7.org/fhir/encounter.xsd\""
}
}
}
*XML Representation Example*
<phtal:link rel="https://api-docs.myclinic.com/fhir/rel/encounter">
<phtal:href>http://fhir.myclinic.com/Patient/{id}/{?_pretty,_elements}</phtal:href>
<phtal:uriParameter type="https://api-docs.myclinic.com/fhir/patientId.raml">id</phtal:uriParameter>
<phtal:uriParameter type="https://api-docs.myclinic.com/fhir/parameters/_pretty.raml">_pretty</phtal:uriParameter>
<phtal:uriParameter type="https://api-docs.myclinic.com/fhir/parameters/_elements.raml">_elements</phtal:uriParameter>
<phtal:operation protocol="HTTP">
<phtal:method>GET</phtal:method>
<phtal:produces>application/phtal+json;profile="http://hl7.org/fhir/json-schema/Encounter",
application/phtal+xml;profile="http://hl7.org/fhir/encounter.xsd"
</phtal:produces>
</phtal:instructions>
</phtal:link>
2.1.3. Operation
The most important element that PHTAL representations provide is the
operation element. This element instructs the agent on how to
interact with a resource through a particular communication protocol.
This allows the server to control its own URI space and the clients
to be undisrupted when URI changes are made or new representation or
protocol support is added.
Identifying protocol specific instructions allows servers to separate
communication protocols from resource identification. This is
consistent with the URI specification [RFC3986] and allows PHTAL to
support arbitrary protocols.
Montoya Expires August 30, 2019 [Page 9]
Internet-Draft phtal February 2019
2.1.3.1. Properties
+-----------------+----------------+--------------------------------+
| Name | Type | Description |
+-----------------+----------------+--------------------------------+
| method? | "string" | Instructs the agent what |
| | | protocol method to use when |
| | | interacting with the |
| | | identified resource. The |
| | | default value is whatever |
| | | protocol specific method |
| | | results in information |
| | | retrieval, eg. HTTP GET. |
| | | |
| produces? | "string" | Indicates to the client what |
| | | media types the server |
| | | supports as response content |
| | | to following the current link. |
| | | It MUST be a media range and |
| | | parameters according to |
| | | Section 5.3.2 'Accept' of the |
| | | HTTP Specification [RFC7231]. |
| | | |
| consumes? | "string" | Indicates to the client what |
| | | media types the server |
| | | supports as request content to |
| | | following the current link. It |
| | | MUST be a media range and |
| | | parameters according to |
| | | Section 5.3.2 'Accept' of the |
| | | HTTP Specification [RFC7231]. |
| | | |
| requestContent? | "boolean" | Indicates to the client |
| | | whether a request content is |
| | | required or not for the |
| | | following the current link. |
| | | The default value is "false". |
| | | |
| onInvoke? | EventAttribute | Script function which is to be |
| | | executed when this operation |
| | | is invoked. |
+-----------------+----------------+--------------------------------+
The quality weight parameters MAY be used in the "consumes" and
"produces" properties to indicate to the client which media types are
preferred, possibly allowing the client to know when a known media
type has been superseded and a new one is preferred.
Montoya Expires August 30, 2019 [Page 10]
Internet-Draft phtal February 2019
2.1.3.2. Operation Examples
*JSON Representation Example*
{
"method": "POST",
"consumes": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Appointment\"",
"produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/OperationOutcome\"",
"requestContent": true,
"onInvoke": "..."
}
*XML Representation Example*
<phtal:operation protocol="HTTP" onInvoke="...">
<phtal:consumes>application/phtal+xml;profile="http://hl7.org/fhir/appointment.xsd"
</phtal:consumes>
<phtal:produces>application/phtal+xml;profile="http://hl7.org/fhir/operationoutcome.xsd"
</phtal:produces>
<phtal:requestContent>true</phtal:requestContent>
</phtal:operation>
2.1.4. HTTP Operation
The HTTP Operation element is an extension of the Operation element
specifically for interactions using the HTTP protocol.
2.1.4.1. Added Properties
+------------+----------------------+-------------------------------+
| Name | Type | Description |
+------------+----------------------+-------------------------------+
| securedBy? | [SecurityRequirement | An array of |
| | (Section 2.1.5)] | SecurityRequirement elements, |
| | | the operation can be |
| | | authenticated by any of the |
| | | specified security schemes. |
| | | |
| headers? | Map["string", | A map where the keys are the |
| | "string"] | names of the HTTP headers to |
| | | be sent and the values are |
| | | URIs that resolve to RAML 1.0 |
| | | Spec [RAML] Data Type |
| | | declarations explaining the |
| | | format and semantics of the |
| | | variables. |
+------------+----------------------+-------------------------------+
Montoya Expires August 30, 2019 [Page 11]
Internet-Draft phtal February 2019
2.1.4.2. HTTP Operation Examples
*JSON Representation Example*
{
"method": "POST",
"consumes": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Appointment\"",
"produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/OperationOutcome\"",
"requestContent": true,
"securedBy": [
{
"scheme": "https://api-docs.myclinic.com/fhir/security/basicAuth"
},
{
"scheme": "https://api-docs.myclinic.com/fhir/security/oauth2.0",
"scopes": [
"appointment:write"
]
}
],
"headers": {
"trace-id": "https://api-docs.myclinic.com/fhir/traceId.raml"
}
}
*XML Representation Example*
<phtal:operation protocol="HTTP">
<phtal:consumes>application/phtal+xml;profile="http://hl7.org/fhir/appointment.xsd"
</phtal:consumes>
<phtal:produces>application/phtal+xml;profile="http://hl7.org/fhir/operationoutcome.xsd"
</phtal:produces>
<phtal:requestContent>true</phtal:requestContent>
<phtal:securedBy scheme="https://api-docs.myclinic.com/fhir/security/basicAuth">
<phtal:scope>appointment:write</phtal:scope>
</phtal:securedBy>
<phtal:securedBy scheme="https://api-docs.myclinic.com/fhir/security/oauth2.0"/>
</phtal:operation>
2.1.5. SecurityRequirement
2.1.5.1. Properties
Montoya Expires August 30, 2019 [Page 12]
Internet-Draft phtal February 2019
+---------+------------+--------------------------------------------+
| Name | Type | Description |
+---------+------------+--------------------------------------------+
| scheme | "string" | An URI that MUST resolve to RAML 1.0 Spec |
| | | [RAML] Security Scheme declarations. |
| | | |
| scopes? | ["string"] | A list of the scopes required for |
| | | authorization. Scopes are required when |
| | | the security scheme is of type OAuth 2.0. |
+---------+------------+--------------------------------------------+
2.1.6. Partial
Partial representation of the linked resource.
2.1.6.1. Properties
+------+----------+-------------------------------------------------+
| Name | Type | Description |
+------+----------+-------------------------------------------------+
| type | "string" | Identifies the media type that describes the |
| | | partial representation. |
| | | |
| data | Any | The actual partial representation content. |
+------+----------+-------------------------------------------------+
Partial content SHOULD NOT be considered full representations even if
their contents happen to be complete. It is RECOMMENDED partial
representations provide just enough information for agents to be able
to discern which link they want to follow and SHOULD NOT be used as
mechanism to batch interactions.
In the case of XML it is the content of the "partial" element, in
JSON it is the value of a "data" property.
2.1.6.2. Partial Examples
*JSON Representation Example*
Montoya Expires August 30, 2019 [Page 13]
Internet-Draft phtal February 2019
{
"type": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Encounter\"",
"data": {
"status": "in-progress",
"class": {
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "IMP",
"display": "inpatient encounter"
}
}
}
*XML Representation Example*
<phtal:partial type="application/phtal+xml;profile=\"http://hl7.org/fhir/json-schema/Encounter\"">
<Encounter xmlns="http://hl7.org/fhir">
<status value="in-progress"/>
<class>
<system value="http://terminology.hl7.org/CodeSystem/v3-ActCode"/>
<code value="IMP"/>
<display value="inpatient encounter"/>
</class>
</Encounter>
</phtal:partial>
2.2. Self-descriptive messages
The Uniform Interface constraint also dictates that messages be self-
descriptive. This is achieved by message metadata, of which content
type metadata is an important part. However, the purpose of content
type metadata in web interactions is not only to indicate
representation format or schema, but the sender's preferred
interpretation of that format, an application-specific format.
By making use of media type parameters, PHTAL representations allow
participants to retain the ability to signal their preferred
interpretation of a message through metadata. Message authors only
have to identify the document that defines the application-specific
format of their representation and attach it to an otherwise generic
PHTAL representation.
When web participants identify an application-specific format in
metadata they promote visibility and evolvability. Intermediaries
(i.e., proxies and gateways) are able to accurately and more
efficiently perform significant functions such as encapsulating
legacy services, and enhancing client functionality.
Montoya Expires August 30, 2019 [Page 14]
Internet-Draft phtal February 2019
2.2.1. Linking to a profile
For example consider the following interactions:
POST http://www.example.com/someIdentifier
Content-Type: application/json
Accept: application/json
200 OK
Content-Type: application/json
This interaction can only be accurately interpreted to mean that the
client requested resource "http://www.example.com/someIdentifier" to
process an "application/json" request and it successfully responded
with an "application/json" response. "application/json" offers
intermediaries no semantic information about the content of the
message besides how it's (de)serialized.
To indicate the format and semantics of a PHTAL representation, the
sender SHOULD identify a document that explains additional semantics
using a "profile" media type parameter.
POST http://www.example.com/someIdentifier
Content-Type: application/phtal+json;profile="http://hl7.org/fhir/json-schema/Appointment"
Accept: application/phtal+json;profile="http://hl7.org/fhir/json-schema/OperationOutcome"
200 OK
Content-Type: application/phtal+json;profile="http://hl7.org/fhir/json-schema/OperationOutcome"```
In contrast, this second interaction is perfectly clear. The client
asked "http://www.example.com/someIdentifier" to process a clinical
Appointment request and it successfully responded with an
OperationOutcome response that details the results of the processing.
Intermediaries are able to parse and manipulate the message, perhaps
defaulting values of the appointment request, or adding and/or
removing links from the response, or maybe redirecting the message to
different resources based on the profile information.
The profile parameter SHOULD be a dereferenceable URI that resolves
to a RAML 1.0 Spec [RAML] Data Type declaration. RAML data types are
used because of their ability to describe representations independent
of their runtime media type, as well as supporting XSD and JSON
Schema documents.
TODO: Consider restricting profile parameter to a single value,
forego the link rel definition.
Montoya Expires August 30, 2019 [Page 15]
Internet-Draft phtal February 2019
2.3. Code-On-Demand
In order to further promote modifiability of a system REST defines
code-on-demand as an optional constraint. An optional constraint
would observe desired behavior where supported, but with the
understanding that it may not be the general case. Code-on-demand is
a style of code mobility in which the processing logic is moved from
the server into the client, thus providing dynamic extensibility;
functionality can be added to a deployed component without impacting
the rest of the system.
Very similar to HTML's script element PHTAL provides ways to embed
code into its representations.
Ultimately, application servers may prefer if legacy clients could
adapt to new representations or communication protocols instead of
having to support overloaded versions of a feature. At the cost of
visibility, code-on-demand allows application servers to re-program a
deployed component to support new features, thus freeing the server
from the responsibility of maintaining backwards compatibility.
It's worthy to mention other advantages of code-on-demand outside of
modifiability. Scalability of the server is improved, since it can
off-load work to the client. User-perceived performance and
efficiency are enhanced when the code can adapt its actions to the
client's environment and interact with the user locally rather than
through remote interactions.
2.3.1. Script
A script element is equivalent to the script element in HTML and thus
is the place for scripts (e.g., ECMAScript). Any functions defined
within any script element have a "global" scope across the entire
current document.
TODO: Consider what to include about DOM and Events.
2.3.1.1. Properties
Montoya Expires August 30, 2019 [Page 16]
Internet-Draft phtal February 2019
+---------+----------+----------------------------------------------+
| Name | Type | Description |
+---------+----------+----------------------------------------------+
| type | "string" | Identifies the media type that describes the |
| | | script content. |
| | | |
| source? | "string" | An URI that references the script's content. |
| | | |
| data? | Any | The actual contents of the script. It is |
| | | mutually exclusive with the source property. |
+---------+----------+----------------------------------------------+
*JSON Representation Example*
{
"_scripts": [{
"type": "text/javascript",
"source": "http://fhir.myclinic.com/scripts/patientScript"
},
{
"type": "text/javascript",
"data": "..."
}]
}
*XML Representation Example*
<Patient xmlns="http://hl7.org/fhir" xmlns:phtal="http://www.phtal.org/v1/XMLSchema.xsd">
<phtal:script type="text/javascript" src="http://fhir.myclinic.com/scripts/patientScript"/>
<phtal:script type="text/javascript">
<![CDATA[
function foo(evt) {
...
}
]\]>
</phtal:script>
</Patient>
3. IANA Considerations
This specification establishes two media types: 'application/
phtal+xml' and 'application/phtal+json'
TODO: Update schemas linked.
Montoya Expires August 30, 2019 [Page 17]
Internet-Draft phtal February 2019
3.1. application/phtal+xml
*Type name:* application
*Subtype name:* phtal+xml
*Required parameters:* none
*Optional parameters:*
*charset:* This parameter has identical semantics to the charset
parameter of the 'application/xml' media type as specified in
[RFC7303].
*profile:* A whitespace-separated list of URIs identifying
specific constraints or conventions that apply to a PHTAL
document. A profile must not change the semantics of the resource
representation when processed without profile knowledge, so that
clients both with and without knowledge of a profiled resource can
safely use the same representation. The profile parameter may
also be used by clients to express their preferences in the
content negotiation process. Profile URIs MUST be dereferenceable
and resolve to a profile document as defined in Section #5.1 of
this document.
*Encoding considerations:*
*binary:* Same as encoding considerations of application/xml as
specified in [RFC7303].
*Security considerations:*
This format shares security issues common to all XML content
types. The security issues of [RFC7303], section 10, should be
considered.
Several PHTAL elements may cause arbitrary URIs to be referenced.
In this case, the security issues of [RFC3986], section 7, should
be considered.
In common with HTML, PHTAL documents may reference external
scripting language media. Scripting languages are executable
content. In this case, the security considerations in the Media
Type registrations for those formats shall apply.
*Interoperability considerations:* An xsd document detailing the
format of application/phtal+xml is located at
http://www.phtal.org/schema/phtal+xml.xsd [1]
Montoya Expires August 30, 2019 [Page 18]
Internet-Draft phtal February 2019
*Fragment identifier considerations:*
*Published specification:* This Document
*Applications that use this media type:* Various
*Additional information:*
*magic number(s):* none
*file extensions:* .xml
*macintosh type file code:* TEXT
*object idenfiers:* none
*Person to contact for further information:*
*Name:* Jose Montoya
*Email:* jmontoya@ms3-inc.com
*Intended usage:* Common
*Author/change controller:* Jose Montoya
3.2. application/phtal+json
*Type name:* application
*Subtype name:* phtal+json
*Required parameters:* none
*Optional parameters:*
*profile:* A whitespace-separated list of URIs identifying
specific constraints or conventions that apply to a PHTAL
document. A profile must not change the semantics of the resource
representation when processed without profile knowledge, so that
clients both with and without knowledge of a profiled resource can
safely use the same representation. The profile parameter may
also be used by clients to express their preferences in the
content negotiation process. Profile URIs MUST be dereferenceable
and resolve to a profile document as defined in Section #5.1 of
this document.
*Encoding considerations:* binary
Montoya Expires August 30, 2019 [Page 19]
Internet-Draft phtal February 2019
*Security considerations:*
This media type shares security issues common to all JSON content
types. The security issues of [RFC8259], section 6, should be
considered.
Several PHTAL elements may cause arbitrary URIs to be referenced.
In this case, the security issues of [RFC3986], section 7, should
be considered.
In common with HTML, PHTAL documents may reference external
scripting language media. Scripting languages are executable
content. In this case, the security considerations in the Media
Type registrations for those formats shall apply.
*Interoperability considerations:* A json-schema document detailing
the format of application/phtal+json is located at
http://www.phtal.org/schema/phtal+json.yaml [2]
*Fragment identifier considerations:* none
*Published specification:* This Document
*Applications that use this media type:* Various
*Additional information:*
*magic number(s):* none
*file extensions:* .json
*macintosh type file code:* TEXT
*object idenfiers:* none
*Person to contact for further information:*
*Name:* Jose Montoya
*Email:* jmontoya@ms3-inc.com
*Intended usage:* Common
*Author/change controller:* Jose Montoya
Montoya Expires August 30, 2019 [Page 20]
Internet-Draft phtal February 2019
4. References
4.1. Normative References
[I-D.draft-montoya-xrel-00]
Montoya, J., "Extended Link Relationships", draft-montoya-
xrel-00 (work in progress), February 2019.
[RAML] The RAML Workgroup, "RAML Specification", n.d.,
<https://github.com/raml-org/raml-
spec/blob/master/versions/raml-10/raml-10.md>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570,
DOI 10.17487/RFC6570, March 2012,
<https://www.rfc-editor.org/info/rfc6570>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/info/rfc6838>.
[RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303,
DOI 10.17487/RFC7303, July 2014,
<https://www.rfc-editor.org/info/rfc7303>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
Montoya Expires August 30, 2019 [Page 21]
Internet-Draft phtal February 2019
4.2. Informative References
[I-D.draft-handrews-json-schema-hyperschema-01]
Andrews, H. and A. Wright, "JSON Hyper-Schema: A
Vocabulary for Hypermedia Annotation of JSON", draft-
handrews-json-schema-hyperschema-01 (work in progress),
January 2018.
[I-D.draft-kelly-json-hal-08]
Kelly, M., "JSON Hypertext Application Language", draft-
kelly-json-hal-08 (work in progress), May 2016.
[OpenAPI] "OpenAPI Specification", n.d., <https://github.com/OAI/
OpenAPI-Specification/blob/master/versions/3.0.0.md>.
[REST] Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", Ph.D. Dissertation,
University of California, Irvine, 2000,
<http://www.ics.uci.edu/~fielding/pubs/dissertation/
fielding_dissertation.pdf>.
[RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906,
DOI 10.17487/RFC6906, March 2013,
<https://www.rfc-editor.org/info/rfc6906>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>.
[W3C.hydra]
Lanthaler, M., "A Vocabulary for Hypermedia-Driven Web
APIs", 2018, <http://www.hydra-cg.com/spec/latest/core/>.
[W3C.TAG.role-media-types]
Fielding, R. and I. Jacobs, "Role of Internet Media
Types", 2001, <https://www.w3.org/2001/tag/doc/
mime-respect-20130422#media-type>.
4.3. URIs
[1] http://www.phtal.org/schema/phtal+xml.xsd
[2] http://www.phtal.org/schema/phtal+json.yaml
[3] https://github.com/phtal-org/internet-draft-phtal/issues
[4] https://phtal-org.github.io/internet-draft-phtal/
Montoya Expires August 30, 2019 [Page 22]
Internet-Draft phtal February 2019
Appendix A. Acknowledgments
Thanks to Mike Kelly, Henry Andrews, Marcus Lanthaler, Mike Amundsen,
Stu Charlton, and Jeff Michaud for their contributions in this space
even if not directly related to PHTAL.
Appendix B. Frequently Asked Questions
B.1. How can I submit comments or feedback to the editors?
The issues list for this draft can be found at https://github.com/
phtal-org/internet-draft-phtal/issues [3]. For additional
information, see https://phtal-org.github.io/internet-draft-phtal/
[4].
To provide feedback, use this issue tracker, the communication
methods listed on the homepage, or email the document editors.
Author's Address
Jose Montoya
Mountain State Software Solutions
Email: jmontoya@ms3-inc.com
Montoya Expires August 30, 2019 [Page 23]