idnits 2.17.1
draft-montoya-phtal-00.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The document seems to lack a Security Considerations section.
** There are 41 instances of too long lines in the document, the longest
one being 48 characters in excess of 72.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (February 26, 2019) is 1885 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
-- Looks like a reference, but probably isn't: '1' on line 947
-- Looks like a reference, but probably isn't: '2' on line 949
-- Looks like a reference, but probably isn't: '3' on line 966
-- Looks like a reference, but probably isn't: '4' on line 968
== Unused Reference: 'RFC6838' is defined on line 888, but no explicit
reference was found in the text
== Unused Reference: 'I-D.draft-handrews-json-schema-hyperschema-01' is
defined on line 908, but no explicit reference was found in the text
== Unused Reference: 'I-D.draft-kelly-json-hal-08' is defined on line 914,
but no explicit reference was found in the text
== Unused Reference: 'OpenAPI' is defined on line 918, but no explicit
reference was found in the text
== Unused Reference: 'REST' is defined on line 921, but no explicit
reference was found in the text
== Unused Reference: 'RFC6906' is defined on line 927, but no explicit
reference was found in the text
== Outdated reference: A later version (-02) exists of draft-montoya-xrel-00
== Outdated reference: A later version (-02) exists of
draft-handrews-json-schema-hyperschema-01
== Outdated reference: A later version (-11) exists of
draft-kelly-json-hal-08
-- Obsolete informational reference (is this intentional?): RFC 7231
(Obsoleted by RFC 9110)
Summary: 2 errors (**), 0 flaws (~~), 10 warnings (==), 6 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group J. Montoya
3 Internet-Draft Mountain State Software Solutions
4 Intended status: Informational February 26, 2019
5 Expires: August 30, 2019
7 Profiled Hypertext Application Language
8 draft-montoya-phtal-00
10 Abstract
12 This document defines PHTAL, a generic representation format for
13 hypertext applications guided by REST constraints. PHTAL could be
14 compared to HTML without graphical requirements.
16 Status of This Memo
18 This Internet-Draft is submitted in full conformance with the
19 provisions of BCP 78 and BCP 79.
21 Internet-Drafts are working documents of the Internet Engineering
22 Task Force (IETF). Note that other groups may also distribute
23 working documents as Internet-Drafts. The list of current Internet-
24 Drafts is at https://datatracker.ietf.org/drafts/current/.
26 Internet-Drafts are draft documents valid for a maximum of six months
27 and may be updated, replaced, or obsoleted by other documents at any
28 time. It is inappropriate to use Internet-Drafts as reference
29 material or to cite them other than as "work in progress."
31 This Internet-Draft will expire on August 30, 2019.
33 Copyright Notice
35 Copyright (c) 2019 IETF Trust and the persons identified as the
36 document authors. All rights reserved.
38 This document is subject to BCP 78 and the IETF Trust's Legal
39 Provisions Relating to IETF Documents
40 (https://trustee.ietf.org/license-info) in effect on the date of
41 publication of this document. Please review these documents
42 carefully, as they describe your rights and restrictions with respect
43 to this document. Code Components extracted from this document must
44 include Simplified BSD License text as described in Section 4.e of
45 the Trust Legal Provisions and are provided without warranty as
46 described in the Simplified BSD License.
48 Table of Contents
50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
51 1.1. Definitions and Terminology . . . . . . . . . . . . . . . 2
52 1.1.1. Terminology and Conformance Language . . . . . . . . 3
53 1.1.2. General . . . . . . . . . . . . . . . . . . . . . . . 3
54 1.1.3. Documents description . . . . . . . . . . . . . . . . 3
55 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . 4
56 2. PHTAL Representations . . . . . . . . . . . . . . . . . . . . 4
57 2.1. Hypermedia as the engine of application state . . . . . . 4
58 2.1.1. Document Root . . . . . . . . . . . . . . . . . . . . 4
59 2.1.2. Link . . . . . . . . . . . . . . . . . . . . . . . . 7
60 2.1.3. Operation . . . . . . . . . . . . . . . . . . . . . . 9
61 2.1.4. HTTP Operation . . . . . . . . . . . . . . . . . . . 11
62 2.1.5. SecurityRequirement . . . . . . . . . . . . . . . . . 12
63 2.1.6. Partial . . . . . . . . . . . . . . . . . . . . . . . 13
64 2.2. Self-descriptive messages . . . . . . . . . . . . . . . . 14
65 2.2.1. Linking to a profile . . . . . . . . . . . . . . . . 15
66 2.3. Code-On-Demand . . . . . . . . . . . . . . . . . . . . . 16
67 2.3.1. Script . . . . . . . . . . . . . . . . . . . . . . . 16
68 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
69 3.1. application/phtal+xml . . . . . . . . . . . . . . . . . . 18
70 3.2. application/phtal+json . . . . . . . . . . . . . . . . . 19
71 4. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
72 4.1. Normative References . . . . . . . . . . . . . . . . . . 21
73 4.2. Informative References . . . . . . . . . . . . . . . . . 22
74 4.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 22
75 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 23
76 Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 23
77 B.1. How can I submit comments or feedback to the editors? . . 23
78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 23
80 1. Introduction
82 This document defines PHTAL, a generic representation format for
83 hypertext applications guided by REST constraints. PHTAL could be
84 compared to HTML without graphical requirements.
86 This document registers two media-type identifiers with the IANA:
87 "application/phtal+json" and "application/phtal+xml". This
88 registration is for community review and will be submitted to the
89 IESG for review, approval, and registration with IANA.
91 1.1. Definitions and Terminology
92 1.1.1. Terminology and Conformance Language
94 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
95 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
96 "OPTIONAL" in this document are to be interpreted as described in
97 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
98 capitals, as shown here.
100 1.1.2. General
102 Representational State Transfer, or *REST*, is an architectural style
103 for distributed hypermedia systems. Introduced and first defined in
104 2000 in Chapter 5, REST, of the doctoral dissertation "Architectural
105 Styles and the Design of Network-based Software Architecture" by Roy
106 Fielding.
108 *Hypermedia*, or hypertext, is defined by the presence of application
109 control information embedded within, or as a layer above, the
110 presentation of information. Hypermedia allows for a virtually
111 unbound network of resources while also guiding users through an
112 application as they navigate said relationships.
114 A *hypermedia relationship*, also known as a link relation, describes
115 the semantics behind a virtual uni-directional association between
116 two resources.
118 A *hypermedia relationship name* is an identifier for a hypermedia
119 relationship.
121 A *resource* is the intended conceptual target of a hypertext
122 reference.
124 *Representational state* indicates the current state of the requested
125 resource, the desired state for the requested resource, or the value
126 of some other resource, such as a representation of the input data
127 within a client's query form, or a representation of some error
128 condition for a response.
130 *Application state* is the state of the user's application of
131 computing to a given task, controlled and stored by the user agent
132 and can be composed of representations from multiple servers.
134 1.1.3. Documents description
136 A trailing question mark, for example *description?*, indicates an
137 optional property.
139 1.2. Motivation
141 The essential trade-off that REST makes when compared to an
142 architectural style like RPC is dynamic modifiability over
143 efficiency. Dynamic modifiability is the degree to which an
144 application can be changed without stopping and restarting the entire
145 system. This is what REST promises through the Uniform Interface,
146 and optionally Code-On-Demand, constraints.
148 Guided by these constraints PHTAL introduces the necessary elements
149 to enable application authors to create evolvable and extensible
150 applications.
152 2. PHTAL Representations
154 2.1. Hypermedia as the engine of application state
156 The Uniform Interface constraint dictates that hypermedia be the
157 engine of application state. This means that the state of the
158 application and its potential transitions are dictated by the
159 presence of hypermedia relationships in-band and by the navigation of
160 those relationships by an user (human or automated). In order for
161 users to traverse a selected relationship they depend on the server
162 to provide instructions for communicating with the target resource.
164 When servers provide control information at run-time instead of at
165 deploy-time, they retain control of their implementation space and
166 enable dynamic evolvability; they can change their implementation
167 without having to restart or deploy clients. Applications servers
168 are free to change their URI structure, they are free rearrange
169 resources into different servers, they are free introduce new links
170 that provide new features in existing representations, nothing will
171 break already deployed components as long as links are not broken.
173 PHTAL introduces generic but comprehensive hypertext markup so that
174 instead of creating and registering a new, application specific,
175 hypertext enabled media type, authors can choose to make use of
176 PHTAL's markup. This frees authors to spend most of their
177 descriptive efforts in defining application-specific representation
178 and possibly on extended link relations to drive application state.
180 2.1.1. Document Root
182 The in-band elements defined by PHTAL aim to provide just what's
183 necessary for agents to evaluate the hypertext relationship
184 alternatives provided and invoke the appropriate operation to get the
185 agent to the next application state.
187 2.1.1.1. Properties
189 +-------------+---------------+-------------------------------------+
190 | Name | Type | Description |
191 +-------------+---------------+-------------------------------------+
192 | links? | Map["string", | The links element is a map where |
193 | | [Link | the keys are hypermedia |
194 | | (Section | relationship identifiers and the |
195 | | 2.1.2)]] | values are single or multiple Link |
196 | | | elements. The relationship |
197 | | | identifier MUST be a IANA |
198 | | | registered relation type or an URI |
199 | | | that when dereferenced resolves to |
200 | | | an XREL [I-D.draft-montoya-xrel-00] |
201 | | | document. |
202 | | | |
203 | operations? | [Operation | Informs an agent of what operations |
204 | | (Section | are allowed to be invoked on the |
205 | | 2.1.3)] | context resource. |
206 +-------------+---------------+-------------------------------------+
208 The operations element MAY be included as part of an HTTP GET
209 response body, or as the response body to an HTTP OPTIONS, for
210 example.
212 Detailed mappings to XML and JSON are provided through the
213 appropriate schemas in Section #5 of this document.
215 2.1.1.2. PHTAL examples
217 *JSON Representation Example*
219 {
220 "name": [
221 {
222 "use": "official",
223 "family": "Chalmers",
224 "given": [
225 "Peter",
226 "James"
227 ]
228 }
229 ],
230 "_links": {
231 "https://api-docs.myclinic.com/fhir/rel/encounter": [{
232 "href": "http://fhir.myclinic.com/Encounter/1234",
233 "operation": {
234 "HTTP": {
235 "method": "GET",
236 "produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Encounter\",
237 application/phtal+xml;profile=\"http://hl7.org/fhir/encounter.xsd\""
238 }
239 }
240 }]
241 },
242 "_operations": {
243 "HTTP": {
244 "method": "PUT",
245 "consumes": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Encounter\",
246 application/phtal+xml;profile=\"http://hl7.org/fhir/encounter.xsd\""
247 "produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/OperationOutcome\",
248 application/phtal+xml;profile=\"http://hl7.org/fhir/operationoutcome.xsd\""
249 }
250 }
251 }
253 *XML Representation Example*
255
256
257
258
259
260
261
262
263
264 http://fhir.myclinic.com/Encounter/1234
265
266 GET
267 application/phtal+json;profile="http://hl7.org/fhir/json-schema/Encounter",
268 application/phtal+xml;profile="http://hl7.org/fhir/encounter.xsd"
269
270
271
272
273 PUT
274 application/phtal+json;profile="http://hl7.org/fhir/json-schema/Encounter",
275 application/phtal+xml;profile="http://hl7.org/fhir/encounter.xsd"
276
277 application/phtal+json;profile="http://hl7.org/fhir/json-schema/OperationOutcome",
278 application/phtal+xml;profile="http://hl7.org/fhir/operationoutcome.xsd"
279
280
281
283 2.1.2. Link
285 2.1.2.1. Properties
286 +----------------+---------------+----------------------------------+
287 | Name | Type | Description |
288 +----------------+---------------+----------------------------------+
289 | href | "string" | The link's target resource. The |
290 | | | href property MUST be a URI |
291 | | | [RFC3986] or a URI Template |
292 | | | [RFC6570]. |
293 | | | |
294 | uriParameters? | Map["string", | A map where the keys are the |
295 | | "string"] | names of the variables in the |
296 | | | href property when it is an URI |
297 | | | Template, and the values are |
298 | | | URIs that resolve to RAML 1.0 |
299 | | | Spec [RAML] Data Type |
300 | | | declarations explaining the |
301 | | | format and semantics of the |
302 | | | variables. |
303 | | | |
304 | operation? | Map["string", | The protocol specific operation |
305 | | Operation | for traversing this link. There |
306 | | (Section | SHOULD NOT be two operations for |
307 | | 2.1.3)] | the same protocol. |
308 | | | |
309 | partial? | Partial | A partial representation of the |
310 | | (Section | target resource. |
311 | | 2.1.6) | |
312 +----------------+---------------+----------------------------------+
314 When the operation element is not present the client SHOULD assume
315 that the required operation is an HTTP GET.
317 2.1.2.2. Link Examples
319 *JSON Representation Example*
321 {
322 "href": "http://fhir.myclinic.com/Patient/{id}/{?_pretty,_elements}",
323 "uriParameters": {
324 "id": "https://api-docs.myclinic.com/fhir/patientId.raml",
325 "_pretty": "https://api-docs.myclinic.com/fhir/parameters/_pretty.raml",
326 "_elements": "https://api-docs.myclinic.com/fhir/parameters/_elements.raml"
327 },
328 "operation": {
329 "HTTP": {
330 "method": "GET",
331 "produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Encounter\",
332 application/phtal+xml;profile=\"http://hl7.org/fhir/encounter.xsd\""
333 }
334 }
335 }
337 *XML Representation Example*
339
340 http://fhir.myclinic.com/Patient/{id}/{?_pretty,_elements}
341 id
342 _pretty
343 _elements
344
345 GET
346 application/phtal+json;profile="http://hl7.org/fhir/json-schema/Encounter",
347 application/phtal+xml;profile="http://hl7.org/fhir/encounter.xsd"
348
349
350
352 2.1.3. Operation
354 The most important element that PHTAL representations provide is the
355 operation element. This element instructs the agent on how to
356 interact with a resource through a particular communication protocol.
357 This allows the server to control its own URI space and the clients
358 to be undisrupted when URI changes are made or new representation or
359 protocol support is added.
361 Identifying protocol specific instructions allows servers to separate
362 communication protocols from resource identification. This is
363 consistent with the URI specification [RFC3986] and allows PHTAL to
364 support arbitrary protocols.
366 2.1.3.1. Properties
368 +-----------------+----------------+--------------------------------+
369 | Name | Type | Description |
370 +-----------------+----------------+--------------------------------+
371 | method? | "string" | Instructs the agent what |
372 | | | protocol method to use when |
373 | | | interacting with the |
374 | | | identified resource. The |
375 | | | default value is whatever |
376 | | | protocol specific method |
377 | | | results in information |
378 | | | retrieval, eg. HTTP GET. |
379 | | | |
380 | produces? | "string" | Indicates to the client what |
381 | | | media types the server |
382 | | | supports as response content |
383 | | | to following the current link. |
384 | | | It MUST be a media range and |
385 | | | parameters according to |
386 | | | Section 5.3.2 'Accept' of the |
387 | | | HTTP Specification [RFC7231]. |
388 | | | |
389 | consumes? | "string" | Indicates to the client what |
390 | | | media types the server |
391 | | | supports as request content to |
392 | | | following the current link. It |
393 | | | MUST be a media range and |
394 | | | parameters according to |
395 | | | Section 5.3.2 'Accept' of the |
396 | | | HTTP Specification [RFC7231]. |
397 | | | |
398 | requestContent? | "boolean" | Indicates to the client |
399 | | | whether a request content is |
400 | | | required or not for the |
401 | | | following the current link. |
402 | | | The default value is "false". |
403 | | | |
404 | onInvoke? | EventAttribute | Script function which is to be |
405 | | | executed when this operation |
406 | | | is invoked. |
407 +-----------------+----------------+--------------------------------+
409 The quality weight parameters MAY be used in the "consumes" and
410 "produces" properties to indicate to the client which media types are
411 preferred, possibly allowing the client to know when a known media
412 type has been superseded and a new one is preferred.
414 2.1.3.2. Operation Examples
416 *JSON Representation Example*
418 {
419 "method": "POST",
420 "consumes": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Appointment\"",
421 "produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/OperationOutcome\"",
422 "requestContent": true,
423 "onInvoke": "..."
424 }
426 *XML Representation Example*
428
429 application/phtal+xml;profile="http://hl7.org/fhir/appointment.xsd"
430
431 application/phtal+xml;profile="http://hl7.org/fhir/operationoutcome.xsd"
432
433 true
434
436 2.1.4. HTTP Operation
438 The HTTP Operation element is an extension of the Operation element
439 specifically for interactions using the HTTP protocol.
441 2.1.4.1. Added Properties
443 +------------+----------------------+-------------------------------+
444 | Name | Type | Description |
445 +------------+----------------------+-------------------------------+
446 | securedBy? | [SecurityRequirement | An array of |
447 | | (Section 2.1.5)] | SecurityRequirement elements, |
448 | | | the operation can be |
449 | | | authenticated by any of the |
450 | | | specified security schemes. |
451 | | | |
452 | headers? | Map["string", | A map where the keys are the |
453 | | "string"] | names of the HTTP headers to |
454 | | | be sent and the values are |
455 | | | URIs that resolve to RAML 1.0 |
456 | | | Spec [RAML] Data Type |
457 | | | declarations explaining the |
458 | | | format and semantics of the |
459 | | | variables. |
460 +------------+----------------------+-------------------------------+
462 2.1.4.2. HTTP Operation Examples
464 *JSON Representation Example*
466 {
467 "method": "POST",
468 "consumes": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Appointment\"",
469 "produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/OperationOutcome\"",
470 "requestContent": true,
471 "securedBy": [
472 {
473 "scheme": "https://api-docs.myclinic.com/fhir/security/basicAuth"
474 },
475 {
476 "scheme": "https://api-docs.myclinic.com/fhir/security/oauth2.0",
477 "scopes": [
478 "appointment:write"
479 ]
480 }
481 ],
482 "headers": {
483 "trace-id": "https://api-docs.myclinic.com/fhir/traceId.raml"
484 }
485 }
487 *XML Representation Example*
489
490 application/phtal+xml;profile="http://hl7.org/fhir/appointment.xsd"
491
492 application/phtal+xml;profile="http://hl7.org/fhir/operationoutcome.xsd"
493
494 true
495
496 appointment:write
497
498
499
501 2.1.5. SecurityRequirement
503 2.1.5.1. Properties
504 +---------+------------+--------------------------------------------+
505 | Name | Type | Description |
506 +---------+------------+--------------------------------------------+
507 | scheme | "string" | An URI that MUST resolve to RAML 1.0 Spec |
508 | | | [RAML] Security Scheme declarations. |
509 | | | |
510 | scopes? | ["string"] | A list of the scopes required for |
511 | | | authorization. Scopes are required when |
512 | | | the security scheme is of type OAuth 2.0. |
513 +---------+------------+--------------------------------------------+
515 2.1.6. Partial
517 Partial representation of the linked resource.
519 2.1.6.1. Properties
521 +------+----------+-------------------------------------------------+
522 | Name | Type | Description |
523 +------+----------+-------------------------------------------------+
524 | type | "string" | Identifies the media type that describes the |
525 | | | partial representation. |
526 | | | |
527 | data | Any | The actual partial representation content. |
528 +------+----------+-------------------------------------------------+
530 Partial content SHOULD NOT be considered full representations even if
531 their contents happen to be complete. It is RECOMMENDED partial
532 representations provide just enough information for agents to be able
533 to discern which link they want to follow and SHOULD NOT be used as
534 mechanism to batch interactions.
536 In the case of XML it is the content of the "partial" element, in
537 JSON it is the value of a "data" property.
539 2.1.6.2. Partial Examples
541 *JSON Representation Example*
543 {
544 "type": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Encounter\"",
545 "data": {
546 "status": "in-progress",
547 "class": {
548 "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
549 "code": "IMP",
550 "display": "inpatient encounter"
551 }
552 }
553 }
555 *XML Representation Example*
557
558
559
560
561
562
563
564
565
566
568 2.2. Self-descriptive messages
570 The Uniform Interface constraint also dictates that messages be self-
571 descriptive. This is achieved by message metadata, of which content
572 type metadata is an important part. However, the purpose of content
573 type metadata in web interactions is not only to indicate
574 representation format or schema, but the sender's preferred
575 interpretation of that format, an application-specific format.
577 By making use of media type parameters, PHTAL representations allow
578 participants to retain the ability to signal their preferred
579 interpretation of a message through metadata. Message authors only
580 have to identify the document that defines the application-specific
581 format of their representation and attach it to an otherwise generic
582 PHTAL representation.
584 When web participants identify an application-specific format in
585 metadata they promote visibility and evolvability. Intermediaries
586 (i.e., proxies and gateways) are able to accurately and more
587 efficiently perform significant functions such as encapsulating
588 legacy services, and enhancing client functionality.
590 2.2.1. Linking to a profile
592 For example consider the following interactions:
594 POST http://www.example.com/someIdentifier
595 Content-Type: application/json
596 Accept: application/json
598 200 OK
599 Content-Type: application/json
601 This interaction can only be accurately interpreted to mean that the
602 client requested resource "http://www.example.com/someIdentifier" to
603 process an "application/json" request and it successfully responded
604 with an "application/json" response. "application/json" offers
605 intermediaries no semantic information about the content of the
606 message besides how it's (de)serialized.
608 To indicate the format and semantics of a PHTAL representation, the
609 sender SHOULD identify a document that explains additional semantics
610 using a "profile" media type parameter.
612 POST http://www.example.com/someIdentifier
613 Content-Type: application/phtal+json;profile="http://hl7.org/fhir/json-schema/Appointment"
614 Accept: application/phtal+json;profile="http://hl7.org/fhir/json-schema/OperationOutcome"
616 200 OK
617 Content-Type: application/phtal+json;profile="http://hl7.org/fhir/json-schema/OperationOutcome"```
619 In contrast, this second interaction is perfectly clear. The client
620 asked "http://www.example.com/someIdentifier" to process a clinical
621 Appointment request and it successfully responded with an
622 OperationOutcome response that details the results of the processing.
623 Intermediaries are able to parse and manipulate the message, perhaps
624 defaulting values of the appointment request, or adding and/or
625 removing links from the response, or maybe redirecting the message to
626 different resources based on the profile information.
628 The profile parameter SHOULD be a dereferenceable URI that resolves
629 to a RAML 1.0 Spec [RAML] Data Type declaration. RAML data types are
630 used because of their ability to describe representations independent
631 of their runtime media type, as well as supporting XSD and JSON
632 Schema documents.
634 TODO: Consider restricting profile parameter to a single value,
635 forego the link rel definition.
637 2.3. Code-On-Demand
639 In order to further promote modifiability of a system REST defines
640 code-on-demand as an optional constraint. An optional constraint
641 would observe desired behavior where supported, but with the
642 understanding that it may not be the general case. Code-on-demand is
643 a style of code mobility in which the processing logic is moved from
644 the server into the client, thus providing dynamic extensibility;
645 functionality can be added to a deployed component without impacting
646 the rest of the system.
648 Very similar to HTML's script element PHTAL provides ways to embed
649 code into its representations.
651 Ultimately, application servers may prefer if legacy clients could
652 adapt to new representations or communication protocols instead of
653 having to support overloaded versions of a feature. At the cost of
654 visibility, code-on-demand allows application servers to re-program a
655 deployed component to support new features, thus freeing the server
656 from the responsibility of maintaining backwards compatibility.
658 It's worthy to mention other advantages of code-on-demand outside of
659 modifiability. Scalability of the server is improved, since it can
660 off-load work to the client. User-perceived performance and
661 efficiency are enhanced when the code can adapt its actions to the
662 client's environment and interact with the user locally rather than
663 through remote interactions.
665 2.3.1. Script
667 A script element is equivalent to the script element in HTML and thus
668 is the place for scripts (e.g., ECMAScript). Any functions defined
669 within any script element have a "global" scope across the entire
670 current document.
672 TODO: Consider what to include about DOM and Events.
674 2.3.1.1. Properties
675 +---------+----------+----------------------------------------------+
676 | Name | Type | Description |
677 +---------+----------+----------------------------------------------+
678 | type | "string" | Identifies the media type that describes the |
679 | | | script content. |
680 | | | |
681 | source? | "string" | An URI that references the script's content. |
682 | | | |
683 | data? | Any | The actual contents of the script. It is |
684 | | | mutually exclusive with the source property. |
685 +---------+----------+----------------------------------------------+
687 *JSON Representation Example*
689 {
690 "_scripts": [{
691 "type": "text/javascript",
692 "source": "http://fhir.myclinic.com/scripts/patientScript"
693 },
694 {
695 "type": "text/javascript",
696 "data": "..."
697 }]
698 }
700 *XML Representation Example*
702
703
704
705
710
711
713 3. IANA Considerations
715 This specification establishes two media types: 'application/
716 phtal+xml' and 'application/phtal+json'
718 TODO: Update schemas linked.
720 3.1. application/phtal+xml
722 *Type name:* application
724 *Subtype name:* phtal+xml
726 *Required parameters:* none
728 *Optional parameters:*
730 *charset:* This parameter has identical semantics to the charset
731 parameter of the 'application/xml' media type as specified in
732 [RFC7303].
734 *profile:* A whitespace-separated list of URIs identifying
735 specific constraints or conventions that apply to a PHTAL
736 document. A profile must not change the semantics of the resource
737 representation when processed without profile knowledge, so that
738 clients both with and without knowledge of a profiled resource can
739 safely use the same representation. The profile parameter may
740 also be used by clients to express their preferences in the
741 content negotiation process. Profile URIs MUST be dereferenceable
742 and resolve to a profile document as defined in Section #5.1 of
743 this document.
745 *Encoding considerations:*
747 *binary:* Same as encoding considerations of application/xml as
748 specified in [RFC7303].
750 *Security considerations:*
752 This format shares security issues common to all XML content
753 types. The security issues of [RFC7303], section 10, should be
754 considered.
756 Several PHTAL elements may cause arbitrary URIs to be referenced.
757 In this case, the security issues of [RFC3986], section 7, should
758 be considered.
760 In common with HTML, PHTAL documents may reference external
761 scripting language media. Scripting languages are executable
762 content. In this case, the security considerations in the Media
763 Type registrations for those formats shall apply.
765 *Interoperability considerations:* An xsd document detailing the
766 format of application/phtal+xml is located at
767 http://www.phtal.org/schema/phtal+xml.xsd [1]
768 *Fragment identifier considerations:*
770 *Published specification:* This Document
772 *Applications that use this media type:* Various
774 *Additional information:*
776 *magic number(s):* none
778 *file extensions:* .xml
780 *macintosh type file code:* TEXT
782 *object idenfiers:* none
784 *Person to contact for further information:*
786 *Name:* Jose Montoya
788 *Email:* jmontoya@ms3-inc.com
790 *Intended usage:* Common
792 *Author/change controller:* Jose Montoya
794 3.2. application/phtal+json
796 *Type name:* application
798 *Subtype name:* phtal+json
800 *Required parameters:* none
802 *Optional parameters:*
804 *profile:* A whitespace-separated list of URIs identifying
805 specific constraints or conventions that apply to a PHTAL
806 document. A profile must not change the semantics of the resource
807 representation when processed without profile knowledge, so that
808 clients both with and without knowledge of a profiled resource can
809 safely use the same representation. The profile parameter may
810 also be used by clients to express their preferences in the
811 content negotiation process. Profile URIs MUST be dereferenceable
812 and resolve to a profile document as defined in Section #5.1 of
813 this document.
815 *Encoding considerations:* binary
816 *Security considerations:*
818 This media type shares security issues common to all JSON content
819 types. The security issues of [RFC8259], section 6, should be
820 considered.
822 Several PHTAL elements may cause arbitrary URIs to be referenced.
823 In this case, the security issues of [RFC3986], section 7, should
824 be considered.
826 In common with HTML, PHTAL documents may reference external
827 scripting language media. Scripting languages are executable
828 content. In this case, the security considerations in the Media
829 Type registrations for those formats shall apply.
831 *Interoperability considerations:* A json-schema document detailing
832 the format of application/phtal+json is located at
833 http://www.phtal.org/schema/phtal+json.yaml [2]
835 *Fragment identifier considerations:* none
837 *Published specification:* This Document
839 *Applications that use this media type:* Various
841 *Additional information:*
843 *magic number(s):* none
845 *file extensions:* .json
847 *macintosh type file code:* TEXT
849 *object idenfiers:* none
851 *Person to contact for further information:*
853 *Name:* Jose Montoya
855 *Email:* jmontoya@ms3-inc.com
857 *Intended usage:* Common
859 *Author/change controller:* Jose Montoya
861 4. References
863 4.1. Normative References
865 [I-D.draft-montoya-xrel-00]
866 Montoya, J., "Extended Link Relationships", draft-montoya-
867 xrel-00 (work in progress), February 2019.
869 [RAML] The RAML Workgroup, "RAML Specification", n.d.,
870 .
873 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
874 Requirement Levels", BCP 14, RFC 2119,
875 DOI 10.17487/RFC2119, March 1997,
876 .
878 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
879 Resource Identifier (URI): Generic Syntax", STD 66,
880 RFC 3986, DOI 10.17487/RFC3986, January 2005,
881 .
883 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
884 and D. Orchard, "URI Template", RFC 6570,
885 DOI 10.17487/RFC6570, March 2012,
886 .
888 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
889 Specifications and Registration Procedures", BCP 13,
890 RFC 6838, DOI 10.17487/RFC6838, January 2013,
891 .
893 [RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303,
894 DOI 10.17487/RFC7303, July 2014,
895 .
897 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
898 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
899 May 2017, .
901 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
902 Interchange Format", STD 90, RFC 8259,
903 DOI 10.17487/RFC8259, December 2017,
904 .
906 4.2. Informative References
908 [I-D.draft-handrews-json-schema-hyperschema-01]
909 Andrews, H. and A. Wright, "JSON Hyper-Schema: A
910 Vocabulary for Hypermedia Annotation of JSON", draft-
911 handrews-json-schema-hyperschema-01 (work in progress),
912 January 2018.
914 [I-D.draft-kelly-json-hal-08]
915 Kelly, M., "JSON Hypertext Application Language", draft-
916 kelly-json-hal-08 (work in progress), May 2016.
918 [OpenAPI] "OpenAPI Specification", n.d., .
921 [REST] Fielding, R., "Architectural Styles and the Design of
922 Network-based Software Architectures", Ph.D. Dissertation,
923 University of California, Irvine, 2000,
924 .
927 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906,
928 DOI 10.17487/RFC6906, March 2013,
929 .
931 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
932 Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
933 DOI 10.17487/RFC7231, June 2014,
934 .
936 [W3C.hydra]
937 Lanthaler, M., "A Vocabulary for Hypermedia-Driven Web
938 APIs", 2018, .
940 [W3C.TAG.role-media-types]
941 Fielding, R. and I. Jacobs, "Role of Internet Media
942 Types", 2001, .
945 4.3. URIs
947 [1] http://www.phtal.org/schema/phtal+xml.xsd
949 [2] http://www.phtal.org/schema/phtal+json.yaml
951 [3] https://github.com/phtal-org/internet-draft-phtal/issues
953 [4] https://phtal-org.github.io/internet-draft-phtal/
955 Appendix A. Acknowledgments
957 Thanks to Mike Kelly, Henry Andrews, Marcus Lanthaler, Mike Amundsen,
958 Stu Charlton, and Jeff Michaud for their contributions in this space
959 even if not directly related to PHTAL.
961 Appendix B. Frequently Asked Questions
963 B.1. How can I submit comments or feedback to the editors?
965 The issues list for this draft can be found at https://github.com/
966 phtal-org/internet-draft-phtal/issues [3]. For additional
967 information, see https://phtal-org.github.io/internet-draft-phtal/
968 [4].
970 To provide feedback, use this issue tracker, the communication
971 methods listed on the homepage, or email the document editors.
973 Author's Address
975 Jose Montoya
976 Mountain State Software Solutions
978 Email: jmontoya@ms3-inc.com