idnits 2.17.1
draft-montoya-phtal-01.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 39 instances of too long lines in the document, the longest
one being 51 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 (May 05, 2020) is 1451 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
-- Looks like a reference, but probably isn't: '1' on line 945
-- Looks like a reference, but probably isn't: '2' on line 947
-- Looks like a reference, but probably isn't: '3' on line 964
-- Looks like a reference, but probably isn't: '4' on line 966
== Unused Reference: 'RFC6838' is defined on line 893, but no explicit
reference was found in the text
== Unused Reference: 'I-D.draft-handrews-json-schema-hyperschema-01' is
defined on line 918, but no explicit reference was found in the text
== Unused Reference: 'I-D.draft-kelly-json-hal-08' is defined on line 924,
but no explicit reference was found in the text
== Unused Reference: 'REST' is defined on line 928, but no explicit
reference was found in the text
== Outdated reference: A later version (-02) exists of draft-montoya-xrel-01
** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110)
== 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
Summary: 3 errors (**), 0 flaws (~~), 8 warnings (==), 5 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group J. Montoya
3 Internet-Draft May 05, 2020
4 Intended status: Informational
5 Expires: November 6, 2020
7 Profiled Hypertext Application Language
8 draft-montoya-phtal-01
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 any graphical objectives.
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 November 6, 2020.
33 Copyright Notice
35 Copyright (c) 2020 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 . . . . . . . . . . . . . . . 3
52 1.1.1. Terminology and Conformance Language . . . . . . . . 3
53 1.1.2. General . . . . . . . . . . . . . . . . . . . . . . . 3
54 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . 4
55 2. PHTAL Document . . . . . . . . . . . . . . . . . . . . . . . 4
56 2.1. Document description . . . . . . . . . . . . . . . . . . 4
57 2.1.1. Format . . . . . . . . . . . . . . . . . . . . . . . 4
58 2.1.2. Schema . . . . . . . . . . . . . . . . . . . . . . . 4
59 2.2. Hypermedia as the engine of application state . . . . . . 4
60 2.2.1. Document root . . . . . . . . . . . . . . . . . . . . 5
61 2.2.2. Link Object . . . . . . . . . . . . . . . . . . . . . 7
62 2.2.3. Operation Object . . . . . . . . . . . . . . . . . . 9
63 2.2.4. HTTP Operation Object . . . . . . . . . . . . . . . . 11
64 2.2.5. Security Object . . . . . . . . . . . . . . . . . . . 12
65 2.2.6. Partial Object . . . . . . . . . . . . . . . . . . . 13
66 2.3. Self-descriptive messages . . . . . . . . . . . . . . . . 14
67 2.3.1. Linking to a profile . . . . . . . . . . . . . . . . 15
68 2.4. Code-On-Demand . . . . . . . . . . . . . . . . . . . . . 15
69 2.4.1. Script Object . . . . . . . . . . . . . . . . . . . . 16
70 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
71 3.1. application/phtal+xml . . . . . . . . . . . . . . . . . . 17
72 3.2. application/phtal+json . . . . . . . . . . . . . . . . . 19
73 4. References . . . . . . . . . . . . . . . . . . . . . . . . . 20
74 4.1. Normative References . . . . . . . . . . . . . . . . . . 20
75 4.2. Informative References . . . . . . . . . . . . . . . . . 21
76 4.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 22
77 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 22
78 Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 22
79 B.1. How can I submit comments or feedback to the editors? . . 22
80 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22
82 1. Introduction
84 This document defines PHTAL, a generic representation format for
85 hypertext applications guided by REST constraints. PHTAL could be
86 compared to HTML without any graphical objectives.
88 This document registers two media-type identifiers with the IANA:
89 "application/phtal+json" and "application/phtal+xml". This
90 registration is for community review and will be submitted to the
91 IESG for review, approval, and registration with IANA.
93 1.1. Definitions and Terminology
95 1.1.1. Terminology and Conformance Language
97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
99 "OPTIONAL" in this document are to be interpreted as described in
100 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
101 capitals, as shown here.
103 1.1.2. General
105 Representational State Transfer, or *REST*, is an architectural style
106 for distributed hypermedia systems. Introduced and first defined in
107 2000 in Chapter 5, REST, of the doctoral dissertation "Architectural
108 Styles and the Design of Network-based Software Architecture" by Roy
109 Fielding.
111 *Hypermedia*, or hypertext, is defined by the presence of application
112 control information embedded within, or as a layer above, the
113 presentation of information. Hypermedia allows for a virtually
114 unbound network of resources while also guiding users through an
115 application as they navigate said relationships.
117 A *resource* is the intended conceptual target of a hypertext
118 reference.
120 *Representational state* indicates the current state of a requested
121 resource, the desired state for a requested resource, or the value of
122 some other resource, such as a representation of the input data
123 within a client's query form, or a representation of some error
124 condition for a response.
126 A *hyperlink* or link, is the representation of a virtual uni-
127 directional relationship between the context resource represented by
128 the document in which the link is found, and another resource. A
129 link consists of a hypertext reference, a hypermedia relationship
130 identifier, and communication protocol information.
132 A *hypertext reference* or href, is the target's Uniform Resource
133 Identifier.
135 A *hyperlink relationship*, also known as a link relation, identifies
136 the semantics behind a hyperlink.
138 *Application state* is the state of the user's application of
139 computing to a given task, controlled and stored by the user agent
140 and can be composed of representations from multiple servers.
142 1.2. Motivation
144 The essential trade-off that REST makes when compared to an
145 architectural style like RPC is dynamic modifiability over
146 efficiency. Dynamic modifiability is the degree to which an
147 application can be changed without stopping and restarting the entire
148 system. This is what REST promises through the Uniform Interface,
149 and optionally Code-On-Demand, constraints.
151 Guided by these constraints PHTAL introduces generic but
152 comprehensive hypertext markup to enable application authors to
153 create evolvable and extensible applications, while spending most of
154 their descriptive efforts in defining application-specific
155 representations.
157 2. PHTAL Document
159 2.1. Document description
161 2.1.1. Format
163 All field names in the specification are *case sensitive*. This
164 includes all fields that are used as keys in a map, except where
165 explicitly noted that keys are *case insensitive*.
167 The schema exposes two types of fields: Fixed fields, which have a
168 declared name, and Patterned fields, which declare a regex pattern
169 for the field name.
171 Patterned fields MUST have unique names within the containing object.
173 2.1.2. Schema
175 In the descriptions that will follow, if a field is not explicitly
176 *REQUIRED* or described with a MUST or SHALL, it can be considered
177 OPTIONAL.
179 Machine readable mappings to XML and JSON are provided through the
180 appropriate schemas at http://www.phtal.org/xsd/phtal.xsd [1] and
181 http://www.phtal.org/json-schema/phtal.json [2], respectively.
183 2.2. Hypermedia as the engine of application state
185 The Uniform Interface constraint dictates that hypermedia must be the
186 engine of application state. This means that the state of the
187 application and its potential transitions are dictated by the
188 presence of hyperlinks and by the navigation of those links by an
189 user (human or automated). In order for users to traverse a selected
190 relationship they depend on the server to provide communication
191 protocol instructions.
193 When servers provide control information at run-time instead of at
194 deploy-time, they retain control of their implementation space and
195 enable dynamic evolvability; they can change their implementation
196 without having to restart or deploy clients. Applications servers
197 are free to change their URI structure, they are free rearrange
198 resources into different servers, they are free introduce new links
199 that provide new features in existing representations, nothing will
200 break already deployed components as long as links are not broken.
202 2.2.1. Document root
204 The in-band elements defined by PHTAL aim to provide just what's
205 necessary for agents to evaluate the hyperlinks provided and invoke
206 the necessary operation to get the agent to the next application
207 state.
209 2.2.1.1. Fixed Fields
211 +------------+---------------+--------------------------------------+
212 | Name | Type | Description |
213 +------------+---------------+--------------------------------------+
214 | links | Map["string", | The links element is a map where the |
215 | | [Link Object | keys are hypermedia relationship |
216 | | (Section 2.2. | identifiers and the values are |
217 | | 2)]] | single or multiple Link elements. |
218 | | | The relationship identifier MUST be |
219 | | | a IANA registered relation type or |
220 | | | an URI that when dereferenced |
221 | | | resolves to an XREL |
222 | | | [I-D.draft-montoya-xrel-01] |
223 | | | document. |
224 | | | |
225 | operations | Map["string", | A map where the key is a protocol |
226 | | [Operation | identifier and the value is a |
227 | | Object (Secti | collection of Operation elements. |
228 | | on 2.2.3)]] | |
229 +------------+---------------+--------------------------------------+
231 The operations element MAY be included as part of an HTTP GET
232 response body, or as the response body to an HTTP OPTIONS, for
233 example.
235 2.2.1.2. Examples
237 *JSON Representation Example*
239 {
240 "name": [
241 {
242 "use": "official",
243 "family": "Chalmers",
244 "given": [
245 "Peter",
246 "James"
247 ]
248 }
249 ],
250 "_links": {
251 "https://api-docs.myclinic.com/fhir/rel/encounter": [{
252 "href": "http://fhir.myclinic.com/Encounter/1234",
253 "operation": {
254 "HTTP": {
255 "method": "GET",
256 "produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Encounter\",
257 application/phtal+xml;profile=\"http://hl7.org/fhir/encounter.xsd\""
258 }
259 }
260 }]
261 },
262 "_operations": {
263 "HTTP": [{
264 "method": "PUT",
265 "consumes": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Encounter\",
266 application/phtal+xml;profile=\"http://hl7.org/fhir/encounter.xsd\""
267 "produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/OperationOutcome\",
268 application/phtal+xml;profile=\"http://hl7.org/fhir/operationoutcome.xsd\""
269 }]
270 }
271 }
273 *XML Representation Example*
275
276
277
278
279
280
281
282
283
284 http://fhir.myclinic.com/Encounter/1234
285
286 GET
287 application/phtal+json;profile="http://hl7.org/fhir/json-schema/Encounter",
288 application/phtal+xml;profile="http://hl7.org/fhir/encounter.xsd"
289
290
291
292
293 PUT
294 application/phtal+json;profile="http://hl7.org/fhir/json-schema/Encounter",
295 application/phtal+xml;profile="http://hl7.org/fhir/encounter.xsd"
296
297 application/phtal+json;profile="http://hl7.org/fhir/json-schema/OperationOutcome",
298 application/phtal+xml;profile="http://hl7.org/fhir/operationoutcome.xsd"
299
300
301
303 2.2.2. Link Object
305 2.2.2.1. Fixed Fields
306 +---------------+---------------+-----------------------------------+
307 | Name | Type | Description |
308 +---------------+---------------+-----------------------------------+
309 | href | "string" | *REQUIRED* The link's target |
310 | | | resource. The href property MUST |
311 | | | be a URI [RFC3986] or a URI |
312 | | | Template [RFC6570]. |
313 | | | |
314 | uriParameters | Map["string", | A map where the keys are the |
315 | | "string"] | names of the variables in the |
316 | | | href property when it is an URI |
317 | | | Template, and the values are URIs |
318 | | | that resolve to a document that |
319 | | | appropriately describes the |
320 | | | format and semantics of the |
321 | | | variables, e.g.: a DTD, XSD, JSON |
322 | | | Schema, RAML Data Type, OpenAPI |
323 | | | schema, etc. |
324 | | | |
325 | operation | Map["string", | The protocol specific operation |
326 | | Operation | for traversing this link. There |
327 | | Object (Secti | SHOULD NOT be two operations for |
328 | | on 2.2.3)] | the same protocol. |
329 | | | |
330 | partial | Partial | A partial representation of the |
331 | | Object (Secti | target resource. |
332 | | on 2.2.6) | |
333 +---------------+---------------+-----------------------------------+
335 When the operation element is not present the client SHOULD assume
336 that the required operation is an HTTP GET.
338 2.2.2.2. Examples
340 *JSON Representation Example*
342 {
343 "href": "http://fhir.myclinic.com/Patient/{id}/{?_pretty,_elements}",
344 "uriParameters": {
345 "id": "https://api-docs.myclinic.com/fhir/patientId.raml",
346 "_pretty": "https://api-docs.myclinic.com/fhir/parameters/_pretty.raml",
347 "_elements": "https://api-docs.myclinic.com/fhir/parameters/_elements.raml"
348 },
349 "operation": {
350 "HTTP": {
351 "method": "GET",
352 "produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Encounter\",
353 application/phtal+xml;profile=\"http://hl7.org/fhir/encounter.xsd\""
354 }
355 }
356 }
358 *XML Representation Example*
360
361 http://fhir.myclinic.com/Patient/{id}/{?_pretty,_elements}
362 id
363 _pretty
364 _elements
365
366 GET
367 application/phtal+json;profile="http://hl7.org/fhir/json-schema/Encounter",
368 application/phtal+xml;profile="http://hl7.org/fhir/encounter.xsd"
369
370
371
373 2.2.3. Operation Object
375 The most important element that PHTAL representations provide is the
376 operation element. This element instructs the agent on how to
377 interact with a resource through a particular communication protocol.
378 This allows the server to control its own URI space and the clients
379 to be undisrupted when URI changes are made or new representation or
380 protocol support is added.
382 Identifying protocol specific instructions allows servers to separate
383 communication protocols from resource identification. This is
384 consistent with the URI specification [RFC3986] and allows PHTAL to
385 support arbitrary protocols.
387 2.2.3.1. Fixed Fields
389 +----------------+----------------+---------------------------------+
390 | Name | Type | Description |
391 +----------------+----------------+---------------------------------+
392 | method | "string" | Instructs the agent what |
393 | | | protocol specific method to use |
394 | | | when interacting with the |
395 | | | identified resource. The |
396 | | | default value is whatever |
397 | | | protocol specific method |
398 | | | results in information |
399 | | | retrieval, eg. HTTP GET. |
400 | | | |
401 | produces | "string" | Indicates to the client what |
402 | | | media types the server supports |
403 | | | as response content to |
404 | | | following the current link. It |
405 | | | MUST be a media range and |
406 | | | parameters according to Section |
407 | | | 5.3.2 'Accept' of the HTTP |
408 | | | Specification [RFC7231]. |
409 | | | |
410 | consumes | "string" | Indicates to the client what |
411 | | | media types the server supports |
412 | | | as request content to following |
413 | | | the current link. It MUST be a |
414 | | | media range and parameters |
415 | | | according to Section 5.3.2 |
416 | | | 'Accept' of the HTTP |
417 | | | Specification [RFC7231]. |
418 | | | |
419 | requestContent | "boolean" | Indicates to the client whether |
420 | | | a request content is required |
421 | | | or not for the following the |
422 | | | current link. The default value |
423 | | | is "false". |
424 | | | |
425 | onInvoke | EventAttribute | Script function which is to be |
426 | | | executed when this operation is |
427 | | | invoked. |
428 +----------------+----------------+---------------------------------+
430 The quality weight parameters MAY be used in the "consumes" and
431 "produces" properties to indicate to the client which media types are
432 preferred, possibly allowing the client to know when a known media
433 type has been superseded and a new one is preferred.
435 2.2.3.2. Examples
437 *JSON Representation Example*
439 {
440 "method": "POST",
441 "consumes": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Appointment\"",
442 "produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/OperationOutcome\"",
443 "requestContent": true,
444 "onInvoke": "..."
445 }
447 *XML Representation Example*
449
450 application/phtal+xml;profile="http://hl7.org/fhir/appointment.xsd"
451
452 application/phtal+xml;profile="http://hl7.org/fhir/operationoutcome.xsd"
453
454 true
455
457 2.2.4. HTTP Operation Object
459 The HTTP Operation element is an extension of the Operation element
460 specifically for interactions using the HTTP [RFC7231] protocol.
462 2.2.4.1. Added Properties
464 +----------+---------------+----------------------------------------+
465 | Name | Type | Description |
466 +----------+---------------+----------------------------------------+
467 | security | [Security | An array of Security elements, the |
468 | | Object (Secti | operation can be authenticated by any |
469 | | on 2.2.5)] | of the specified security schemes. |
470 | | | |
471 | headers | Map["string", | A map where the keys are the names of |
472 | | "string"] | the HTTP headers to be sent and the |
473 | | | values are URIs that resolve to a |
474 | | | document that appropriately describes |
475 | | | the format and semantics of the |
476 | | | variables, e.g.: a DTD, XSD, JSON |
477 | | | Schema, RAML Data Type, OpenAPI |
478 | | | schema, etc. |
479 +----------+---------------+----------------------------------------+
481 2.2.4.2. Examples
483 *JSON Representation Example*
485 {
486 "method": "POST",
487 "consumes": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Appointment\"",
488 "produces": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/OperationOutcome\"",
489 "requestContent": true,
490 "security": {
491 "https://api-docs.myclinic.com/fhir/security/basicAuth": [],
492 "https://api-docs.myclinic.com/fhir/security/oauth2.0": [
493 "appointment:write"
494 ]
495 },
496 "headers": {
497 "trace-id": "https://api-docs.myclinic.com/fhir/traceId.raml"
498 }
499 }
501 *XML Representation Example*
503
504 application/phtal+xml;profile="http://hl7.org/fhir/appointment.xsd"
505
506 application/phtal+xml;profile="http://hl7.org/fhir/operationoutcome.xsd"
507
508 true
509
510 appointment:write
511
512
513
515 2.2.5. Security Object
517 2.2.5.1. Patterned Fields
518 +---------+------------+--------------------------------------------+
519 | Field | Type | Description |
520 | Pattern | | |
521 +---------+------------+--------------------------------------------+
522 | {name} | ["string"] | Each name MUST resolve to an OpenAPI 3.1 |
523 | | | Spec [OAS] Security Scheme declaration. If |
524 | | | the security scheme is of type "oauth2" or |
525 | | | "openIdConnect", then the value is a list |
526 | | | of scope names required for the execution. |
527 | | | For other security scheme types, the array |
528 | | | MUST be empty |
529 +---------+------------+--------------------------------------------+
531 2.2.6. Partial Object
533 Partial representation of the linked resource.
535 2.2.6.1. Fixed Fields
537 +------+----------+-------------------------------------------------+
538 | Name | Type | Description |
539 +------+----------+-------------------------------------------------+
540 | type | "string" | Identifies the media type that describes the |
541 | | | partial representation. |
542 | | | |
543 | data | Any | The actual partial representation content. |
544 +------+----------+-------------------------------------------------+
546 Partial content SHOULD NOT be considered full representations even if
547 their contents happen to be complete. It is RECOMMENDED partial
548 representations provide just enough information for agents to be able
549 to discern which link they want to follow and SHOULD NOT be used as
550 mechanism to batch interactions.
552 In the case of XML it is the content of the "partial" element, in
553 JSON it is the value of a "data" property.
555 2.2.6.2. Examples
557 *JSON Representation Example*
559 {
560 "type": "application/phtal+json;profile=\"http://hl7.org/fhir/json-schema/Encounter\"",
561 "data": {
562 "status": "in-progress",
563 "class": {
564 "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
565 "code": "IMP",
566 "display": "inpatient encounter"
567 }
568 }
569 }
571 *XML Representation Example*
573
574
575
576
577
578
579
580
581
582
584 2.3. Self-descriptive messages
586 The Uniform Interface constraint also dictates that messages must be
587 self-descriptive. This is achieved by message metadata, of which
588 content type metadata is a vital part. The purpose of content type
589 metadata in web interactions is not only to indicate representation
590 format or schema, but the sender's preferred interpretation of that
591 format, an application-specific format.
593 By making use of media type parameters, PHTAL representations allow
594 participants to retain the ability to signal their preferred
595 interpretation of a message. Message authors only have to identify
596 the document that defines the application-specific format of their
597 representation and attach it to an otherwise generic PHTAL
598 representation.
600 When web participants identify an application-specific format in
601 metadata they promote visibility and evolvability. Intermediaries
602 (i.e., proxies and gateways) are able to accurately and more
603 efficiently perform significant functions such as encapsulating
604 legacy services, and enhancing client functionality.
606 2.3.1. Linking to a profile
608 To indicate their preferred interpretation of a PHTAL representation,
609 the sender SHOULD include a "profile" media type parameter. The
610 profile parameter SHOULD be a dereferenceable URI that resolves to a
611 document that describes the format and semantics of the resource
612 representation, e.g.: a DTD, XSD, JSON Schema, RAML Data Type,
613 OpenAPI schema, etc..
615 For example consider the following interactions:
617 POST http://www.example.com/some-identifier
618 Content-Type: application/json
619 Accept: application/json
621 200 OK
622 Content-Type: application/json
624 This interaction can only be accurately interpreted to mean that the
625 client requested "http://www.example.com/some-identifier" to process
626 an "application/json" request and it successfully responded with an
627 "application/json" response. "application/json" offers intermediaries
628 no semantic information about the content of the message besides how
629 it's (de)serialized.
631 POST http://www.example.com/some-identifier
632 Content-Type: application/phtal+json;profile="http://hl7.org/fhir/json-schema/Appointment"
633 Accept: application/phtal+json;profile="http://hl7.org/fhir/json-schema/OperationOutcome"
635 200 OK
636 Content-Type: application/phtal+json;profile="http://hl7.org/fhir/json-schema/OperationOutcome"```
638 In contrast, this second interaction is perfectly clear. The client
639 requested "http://www.example.com/some-identifier" to process a
640 clinical Appointment request and it successfully responded with an
641 OperationOutcome response that details the results of the processing.
642 Intermediaries are able to parse and manipulate the message, perhaps
643 defaulting values of the appointment request, or adding and/or
644 removing links from the response, or maybe redirecting the message to
645 different resources based on the profile information.
647 2.4. Code-On-Demand
649 In order to further promote modifiability of a system REST defines
650 code-on-demand as an optional constraint. An optional constraint
651 would observe desired behavior where supported, but with the
652 understanding that it may not be the general case. Code-on-demand is
653 a style of code mobility in which the processing logic is moved from
654 the server into the client, thus providing dynamic extensibility;
655 functionality can be added to a deployed component without impacting
656 the rest of the system.
658 Ultimately, application servers may prefer if legacy clients could
659 adapt to new representations or communication protocols instead of
660 having to support overloaded versions of a feature. At the cost of
661 visibility, code-on-demand allows application servers to re-program a
662 deployed component to support new features, thus freeing the server
663 from the responsibility of maintaining backwards compatibility.
665 It's worthy to mention other advantages of code-on-demand outside of
666 modifiability. Scalability of the server is improved, since it can
667 off-load work to the client. User-perceived performance and
668 efficiency are enhanced when the code can adapt its actions to the
669 client's environment and interact with the user locally rather than
670 through remote interactions.
672 Very similar to HTML's script element PHTAL provides ways to embed
673 code into its representations.
675 2.4.1. Script Object
677 A script element is equivalent to the script element in HTML and thus
678 is the place for scripts (e.g., ECMAScript). Any functions defined
679 within any script element have a "global" scope across the entire
680 current document.
682 TODO: Consider what to include about DOM and Events.
684 2.4.1.1. Fixed Fields
686 +--------+----------+-----------------------------------------------+
687 | Name | Type | Description |
688 +--------+----------+-----------------------------------------------+
689 | type | "string" | *REQUIRED* Identifies the media type that |
690 | | | describes the script content. |
691 | | | |
692 | source | "string" | An URI that references the script's content. |
693 | | | |
694 | data | "string" | The actual contents of the script. It is |
695 | | | mutually exclusive with the source property. |
696 +--------+----------+-----------------------------------------------+
698 2.4.1.2. Examples
700 *JSON Representation Example*
702 {
703 "_scripts": [{
704 "type": "text/javascript",
705 "source": "http://fhir.myclinic.com/scripts/patientScript"
706 },
707 {
708 "type": "text/javascript",
709 "data": "..."
710 }]
711 }
713 *XML Representation Example*
715
716
717
718
723
724
726 3. IANA Considerations
728 This specification establishes two media types: 'application/
729 phtal+xml' and 'application/phtal+json'
731 3.1. application/phtal+xml
733 *Type name:* application
735 *Subtype name:* phtal+xml
737 *Required parameters:* none
739 *Optional parameters:*
741 *charset:* This parameter has identical semantics to the charset
742 parameter of the 'application/xml' media type as specified in
743 [RFC7303].
745 *profile:* A dereferenceable URI that resolves to a document that
746 describes the format and semantics of the resource representation,
747 e.g.: a DTD, XSD, RAML Data Type, OpenAPI schema, etc.. A profile
748 must not change the semantics of the resource representation when
749 processed without profile knowledge, so that clients both with and
750 without knowledge of a profiled resource can safely use the same
751 representation. The profile parameter may also be used by clients
752 to express their preferences in the content negotiation process.
754 *Encoding considerations:*
756 *binary:* Same as encoding considerations of application/xml as
757 specified in [RFC7303].
759 *Security considerations:*
761 This format shares security issues common to all XML content
762 types. The security issues of [RFC7303], section 10, should be
763 considered.
765 Several PHTAL elements may cause arbitrary URIs to be referenced.
766 In this case, the security issues of [RFC3986], section 7, should
767 be considered.
769 In common with HTML, PHTAL documents may reference external
770 scripting language media. Scripting languages are executable
771 content. In this case, the security considerations in the Media
772 Type registrations for those formats shall apply.
774 *Interoperability considerations:* none
776 *Fragment identifier considerations:*
778 *Published specification:* This Document
780 *Applications that use this media type:* Various
782 *Additional information:*
784 *magic number(s):* none
786 *file extensions:* .xml
788 *macintosh type file code:* TEXT
790 *object idenfiers:* none
792 *Person to contact for further information:*
793 *Name:* Jose Montoya
795 *Email:* jam01@protonmail.com
797 *Intended usage:* Common
799 *Author/change controller:* Jose Montoya
801 3.2. application/phtal+json
803 *Type name:* application
805 *Subtype name:* phtal+json
807 *Required parameters:* none
809 *Optional parameters:*
811 *profile:* A dereferenceable URI that resolves to a document that
812 describes the format and semantics of the resource representation,
813 e.g.: a JSON Schema, RAML Data Type, OpenAPI schema, etc.. A
814 profile must not change the semantics of the resource
815 representation when processed without profile knowledge, so that
816 clients both with and without knowledge of a profiled resource can
817 safely use the same representation. The profile parameter may
818 also be used by clients to express their preferences in the
819 content negotiation process.
821 *Encoding considerations:* binary
823 *Security considerations:*
825 This media type shares security issues common to all JSON content
826 types. The security issues of [RFC8259], section 6, should be
827 considered.
829 Several PHTAL elements may cause arbitrary URIs to be referenced.
830 In this case, the security issues of [RFC3986], section 7, should
831 be considered.
833 In common with HTML, PHTAL documents may reference external
834 scripting language media. Scripting languages are executable
835 content. In this case, the security considerations in the Media
836 Type registrations for those formats shall apply.
838 *Interoperability considerations:* none
840 *Fragment identifier considerations:* none
841 *Published specification:* This Document
843 *Applications that use this media type:* Various
845 *Additional information:*
847 *magic number(s):* none
849 *file extensions:* .json
851 *macintosh type file code:* TEXT
853 *object idenfiers:* none
855 *Person to contact for further information:*
857 *Name:* Jose Montoya
859 *Email:* jam01@protonmail.com
861 *Intended usage:* Common
863 *Author/change controller:* Jose Montoya
865 4. References
867 4.1. Normative References
869 [I-D.draft-montoya-xrel-01]
870 Montoya, J., "Extended Link Relationships", draft-montoya-
871 xrel-01 (work in progress), October 2019.
873 [OAS] OpenAPI Initiative, a Linux Foundation Collaborative
874 Project, "OpenAPI Specification", n.d.,
875 .
878 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
879 Requirement Levels", BCP 14, RFC 2119,
880 DOI 10.17487/RFC2119, March 1997,
881 .
883 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
884 Resource Identifier (URI): Generic Syntax", STD 66,
885 RFC 3986, DOI 10.17487/RFC3986, January 2005,
886 .
888 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
889 and D. Orchard, "URI Template", RFC 6570,
890 DOI 10.17487/RFC6570, March 2012,
891 .
893 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
894 Specifications and Registration Procedures", BCP 13,
895 RFC 6838, DOI 10.17487/RFC6838, January 2013,
896 .
898 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
899 Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
900 DOI 10.17487/RFC7231, June 2014,
901 .
903 [RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303,
904 DOI 10.17487/RFC7303, July 2014,
905 .
907 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
908 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
909 May 2017, .
911 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
912 Interchange Format", STD 90, RFC 8259,
913 DOI 10.17487/RFC8259, December 2017,
914 .
916 4.2. Informative References
918 [I-D.draft-handrews-json-schema-hyperschema-01]
919 Andrews, H. and A. Wright, "JSON Hyper-Schema: A
920 Vocabulary for Hypermedia Annotation of JSON", draft-
921 handrews-json-schema-hyperschema-01 (work in progress),
922 January 2018.
924 [I-D.draft-kelly-json-hal-08]
925 Kelly, M., "JSON Hypertext Application Language", draft-
926 kelly-json-hal-08 (work in progress), May 2016.
928 [REST] Fielding, R., "Architectural Styles and the Design of
929 Network-based Software Architectures", Ph.D. Dissertation,
930 University of California, Irvine, 2000,
931 .
934 [W3C.hydra]
935 Lanthaler, M., "A Vocabulary for Hypermedia-Driven Web
936 APIs", 2018, .
938 [W3C.TAG.role-media-types]
939 Fielding, R. and I. Jacobs, "Role of Internet Media
940 Types", 2001, .
943 4.3. URIs
945 [1] http://www.phtal.org/xsd/phtal.xsd
947 [2] http://www.phtal.org/json-schema/phtal.json
949 [3] https://github.com/phtal-org/internet-draft-phtal/issues
951 [4] https://phtal-org.github.io/internet-draft-phtal/
953 Appendix A. Acknowledgments
955 Thanks to Mike Kelly, Henry Andrews, Marcus Lanthaler, Mike Amundsen,
956 Stu Charlton, and Jeff Michaud for their contributions in this space
957 even if not directly related to PHTAL.
959 Appendix B. Frequently Asked Questions
961 B.1. How can I submit comments or feedback to the editors?
963 The issues list for this draft can be found at https://github.com/
964 phtal-org/internet-draft-phtal/issues [3]. For additional
965 information, see https://phtal-org.github.io/internet-draft-phtal/
966 [4].
968 To provide feedback, use this issue tracker, the communication
969 methods listed on the homepage, or email the document editors.
971 Author's Address
973 Jose Montoya
975 Email: jam01@protonmail.com