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