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