Create a paragraph in section 6.5 clarifying how resource URL paths are constructed

Added text in section 6.1.2.

Create a subsection in section 6.1.2 to identify forbidden keywords in paths for URLs

Added text in section 6.1.2

6.4.1 GET This operation MUST return an Atom 1.0 compliant feed of all section documents and child sections contained in this section.
Status Code: 200

The implied requirement here is following:
If baseURL does not exist or no sectionpath of name sectionpath exists, the implementation MUST (SHOULD) return a HTTP status code 404.

This would then be consistent with section 6.5.1 for an invalid/non-existing documentname in the URL.

issue withdrawn by submitter, replaced by issue 17238

revise current (20121004) JSON representation of Atom feed and data in section 6.1.2, and incorporate lessons-learned from FHIR implementation

Updated Section 6.1.2 and added non-normative Annex C

• use baseURL/metadata to allow service information
• provide current baseURL/conf as non-normative example

Added the following text as section 6.3.2.

• client pushes feed
• enable "bulk" update
• POST to Section (see 6.4.2.2)

Add paragraph to section 6.4.2.2 that implements this function

Represent DELETE in Atom: XML Fragment in Atom:Content

• Needs to be for 410 resources, not for 404

Add text to section 6.5.4 indicating that this SHOULD be done for SectionDocuments that are DELETED and return a 410.

mime type for format parameter (text/xml vs. xml)

• exception for xml and json
• MUST accept full MIME types

Add text to section 6.1.2 (General Conventions and Considerations) to allow clients to use simplified media types and require server to support this.

Change 6.5.3 to allow PUT creation of new documents to allow the client to suggest location. Same semantics as 6.4.2.2, if conflict return 409

Change section 6.5.3 to reflect updated semantics

• $INCLUDE
• others

Add clarifying paragraph to section 6.6. on searching

• MUST support version specific retrieval of current version
• MAY support version specific retrieval of older version

Add text to the paragraphs on section Atom feed in section 6.4, and version-specific URLs for SectionDocuments in section 6.5.

discuss impact of deletion of resources/SectionDocuments onto the Section level Atom feed/JSON bundle to section 6.4.4

This should apply to section 6.4.1 – GET on baseURL/sectionpath.

Added text clarifying the impact of DELETE of a document (as described in section 6.5.4).

6.2.2 POST ­ Parameters:extensionID, path, name

But the body of the section defines the 'extensionId' parameter with different spelling.

This should be consistent with created sub-section as defined in 6.4.2.1 which uses extensionId in all occurrences.

extensionID should be corrected and renamed to "extensionId".

Make changes to 6.2.2

Describe obligations and error codes around create/updates

• Server can deny update request when update is incorrect
• (HTTP PUT)
• This may be best suited to be resolved at the FHIR specification level

Clarification in section 6.1.2, “Incorrect Updates”

Lack of a Normative References section e.g. including Atom and other documents referenced as being required for an implementation

Update Annex A – Normative References

7.1 line 2: “This pattern may be combined” – unclear what it may be combined with.

Clarify this sentence to reference operations in section 6 of the document; add clarification regarding potentially explicit exclusion.

6.1.1 penultimate sentence, typo “this documents”

Corrected to “this document.”

Throughout the text of the RFC document, you refer to "RESTful" while the cover page uses the term "REST" in the title of the RFC. Please reconcile the use of these terms throughout the document.

Replaced REST globally with RESTful

We had identified a potential issue for a future hData RTF regarding the security negotiation through the use of custom HTTP headers. A future version of hData should use the WWW-Authenticate header instead of any X-hdata-* custom headers.

Section 3, 3rd definition: typo “is access”

Corrected to “is accessed”.

The specification as it is describes a particular pattern of use
that includes
aspects that are specific to hData. It would help us greatly to separate the
general RESTful pattern use from the hData specific features; this way, we could
reference the specification directly and it would be clear how we
could conform to it.

Section 6.2.5 and 6.3 can be combined into a single way to query for
metadata about
the service. The additional HTTP headers created in 6.2.5 are
problematic for some
clients and/or servers to implement. As such the OPTION operation on
the (baseURL)
could return a body with a XML document instead, which contains the information
contained in the 6.2.5. headers, as well at the root.xml manifest.
This would reduce the
number of roundtrips significantly. There should also be a way to
access this information
without using the OPTIONS command to enable the same information to be available
via a <a href=""> link in a web page.

Partially accept. Make OPTIONS on base URL a SHOULD (instead of MUST), and add baseURL/metadata as a reserved URL. Make that document available at baseURL/metadata and also allow sending with OPTIONS body.

The HTTP protocol may be routed through an HTTP proxy such as squid.
Such proxies are transparent to the applications, though implementors
should be alert to the effects of rogue caching.

Interface engines may also be placed between the consumer and the
provider; these differ from proxies because they actively alter the
content and/or destination of the HTTP exchange and are not bound the
rules that apply to HTTP proxies. Such agents are allowed, but must
mark the http header to assist with troubleshooting.

Any agent that modifies an HTTP request or Response content other than
under the rules for HTTP proxie must add a stamp to the HTTP headers
like this:

request-modified-[identity]: [purpose]
response-modified-[identity]: [purpose]

The identity must a single token defined by the administrator of the
agent that will sufficiently identify the agent in the context of use.
The header must specify the agents purpose in modifying the content.
End point systems must not use this header for any purpose; it's aim
is to assist with system troubleshooting.

."

This concern is added as another General Consideration to section 6.1.2.

To support simple searches over Sections and the entire record, for
the section 6.2 and
6.4, the following URL structure is reserved:

5.1. (baseURL)/search?(queryParameter)

This allows a search over the entire record. The (queryParameter) can
be arbitrary,
but it is RECOMMENDED to use HTTP form-encoding style key/value parameters.
The server returns the results of the query in the form of an Atom
feed, with each Entry
representing a search result.

5.2. (baseURL)/(sectionPath)/search?(queryParameter)

The semantics for this query are identical to the one in 4.1., but the
scope is limited to
the section described by the sectionPath.

Created new section 6.6 to implement requested capability.
Added section 6.3.3

Similar to the version-aware resource structure, the following URL for
sectionDocuments is reserved:

(baseURL)/(sectionPath)/(sectionDocument)/validate/

This allows a client to ask the server whether the attached POSTed
content would be
acceptable as a PUT. By this means that client can
(a) validate business logic during testing concerning correct content
(b) implement a lite two-phase commit alternative that reduces the
chance of partial success of multi-resource operations.

The second functionality overlaps a little with existing functionality
around safe commit,
though what is there now solves a different problem. From the point of
view of FHIR, the
first is at least as important: a real world way to test content
without only having to rely
on claims.

Added text defining this mechanism to section 6.5.

This section must be noted as non-normative (in the title)

• Section 9.2 - in the table: replace "(version 1.0.1...)" with the reference [12]

Update the title and reference in the table

Section 8.1 - 2nd paragraph: sentence not parsable: "If the custom security mechanism The URIs..."

• Bullet 2: should be "URI or none" on account of the HTTP Transport Security
• Bullet 5: "State Diagram": what is the format of this UML state diagram? XMI?
• Section 8.3 - last sentence: which "template" are you speaking of?
• Section 8.4 and 8.5: these sections should be noted as informative or non-normative (in their title)

: Incorporated suggested changes for 8.1, 8.4, and 8.5. The reference in section 8.3 was broken and should have pointed back to section 8.1. An additional clarification was added to the 2nd paragraph in section 8.1.

The Get/Put/Delete/Post subsection are not allways listed in the same order, which doesn't ease the reading and the finding of information.

• Section 6.2.5: add a reference to the section 8 which is also speaking about this point.
• Section 6.4.1: ", is RECOMMENDED" -> ", it is RECOMMENDED"

Accepted the request to swap 6.5.2 and 6.5.3.

In the paragraph "hData REST Binding for RLUS": "... HRF specification is access..." -> is accessed

• The paragraph "Semantic signifier" speaks about "The UML diagram below..." while there is no UML diagram. If you decided to add such a UML diagram, the matching XMI would be necessary.

Corrected typo. Removed sentence for Semantic Signifier.

How is this wpecification supposed to evolve wrt the version of OMG's RLUS and HL7's RLUS? I believe this should be a bit explained in section 1.

• Complex operations as well as Security need to be also introduced in this section.
• Last paragraph: add reference [12] when speaking of the OMG RLUS PIM.

Add clarifying paragraph at the end of section 1

Section 7.1: in which way this pattern is "reliable"? A clear explanation of which risks are covered is needed here.

Expanded the introduction in 7.1 to address concerns

Section 6.2.5 states "client MUST NOT use the Max-Forward header when requesting the security mechanisms for a given HDR" but no action is defined for the server.

If Max-Forwards field is truly not permitted on the OPTION operation then recommend adding expected the server action. Suggest to return a 403 Forbidden status code with optional message "Request cannot include Max-Forwards header field".

References:
Max-forwards usage:
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.2

HTTP status codes
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Change section 6.2.5 accordingly

Throughout section 6. of the hData spec, the server should accept the
following HTTP
query string to perform alternate media type negotiation:

(URL)?format=(mediaType)

where (mediaType) MUST be a valid Internet Media type. This explicit content
negotiation takes precedence over the Accept-Header negotiation. The
reason why this
is needed is the unreliable support of the Accept-Header mechanism in
clients, particularly
in older development stacks. While we strongly encourage adoption of
the content negotiation
framework per the HTTP specification, we wish to be as inclusive as possible

Added text defining this mechanism to section 6.1.2

There is no clear conformance point but the understatement made by the use of the RFC2119. I propose to rename section 4 "Conformance point" and to add "Implementations must support the entire mapping" before the description of keywords.

Section 4 modified as suggested

Most of the changes requested in this section apply to 6.5 of the
hData specification.
FHIR will need to be able to access different versions of a resource.
To enable this most
effectively, the spec should support the following URL extensions on
SectionDocuments
for GET, PUT, and POST operations:

(resourceURL) = (baseURL)/(sectionPath)/(sectionDocument)
(versionAwareResourceURL) = (resource)/history/(version-id)

where (version-id) is any unique string. Also, a GET on the (resourceURL) should
return the representation of the resource in the HTTP body, a status
code of 200, and
a Content-Location header containing the (versionAwareResourceURL) of
the current
version of that resource.

If the resource was deleted with a DELETE, the service SHOULD return a
HTTP status
code 410, with no body. However it MAY return a 404 as alternative.

To enable safe updates, the following process MUST be used:

• The client reads obtains the representation of the current version
by performing a GET
on the (resourceURL). This contains the reference to (versionAwareResourceURL).
• The client makes the necessary changes to the state.
• The client MUST then PUT the updates representation to the
(resourceURL) and quote the versionAwareResourceURL in the Content-Location
header of the PUT operation.
• If the (versionAwareResourceURL) provided by the client is the
current version, the
server accepts the representation and persists the change, and returns a HTTP
response with
• a status code of 202 ok,
• a Content-Location header with the (versionAwareResourceURL) of the new

version, and
• the representation of the new version of the resource in the
• If the (versionAwareResourceURL) represents no longer the current version, the
server MUST return a HTTP response with status code 412, a Content-Location
header with the new (versionAwareResourceURL), and a representation of
the latest
version of the resource.

Added version-aware scheme to 6.5, edited 6.5.1 and 6.5.3 (formerly 6.5.2) to address concern

Section 6.5.1 should specify that content negotiation through HTTP Accept headers is possible, and indicate how this interacts with the metadata specified in the HL7 spec.

Accepted, but this was added to section 6.1.2, since this may apply to all resources. Issue 17377 is also fixed in 6.1.2.

Section 6.4.2.2 (Adding new document) describes the case when including metadata in POST operation using
"multipart/form-data", however, it does not describe when not including metadata.

Here's text for the implied requirement:

If POST does not include metadata then MUST POST with a Content Type conforming to the media type of the section. The body of the POST MUST contain the document of the new document. Document metadata in this case MUST be computed from the new document.

This text or something like it must be inserted in this context:
"It is to be treated as informational, since the service MUST compute the valid new metadata based on the requirements found in the HRF specification <INSERT HERE>
The content media type MUST conform..."

Added: “If POST does not include metadata then MUST POST with a Content Type conforming to the media type of the section. The body of the POST MUST contain the document of the new document. Document metadata in this case MUST be created by the system, based on instructions in the hData Content Profile applying to the system.”

Context: 6.5.4 DELETE baseURL/sectionpath/documentname

The implied requirement here is the following, which should be appended to the section to make it consistent with 6.4.4 and 6.5.1:

If baseURL, sectionpath, or target document name does NOT exist, the implementation SHOULD return a 404 - Not found HTTP status code.

Changed as suggested by submitter

The requirements reads as "OPTIONS on HDR baseURL MUST return 200 status".

The implied requirement is the following which should be appended to this requirement:

If there is no HDR at the base URL, the server SHOULD return a 404 - Not found status code.

This would then be consistent with requirement in section 6.2.1 for the GET operation.

Changed in section 6.2.5 to reflect the fact that this only applies to HDR records.

The requirements reads as "This operation returns an XML representation of the current root document, as defined by the HRF specification."

It can be inferred from this requirement that this is an implied “SHALL” or “MUST” mandatory requirement not an implied SHOULD/RECOMMENDED.

Likewise, not defined if the baseURL does not exist, which should return 404 status code as done with similar HTTP operations. This would then be consistent with requirement in section 6.2.

Revised requirement:

This operation MUST return an XML representation of the current root document, as defined by the HRF specification.
If there is no HDR at the base URL, the server SHOULD return a 404 - Not found status code.

Resolved with 17234.

6.3.1 GET

This operation returns an XML representation of the current root document, as defined by the HRF specification.

Status Code: 200

It can be inferred from this requirement that this is an implied “SHALL” or “MUST” mandatory requirement not an implied SHOULD/RECOMMENDED.
This implies the HTTP response contentType is text/xml or application/xml and the target namespace in the returned document ishttp://projecthdata.org/hdata/schemas/2009/06/core as defined by the HRF spec.
Likewise, not defined if the baseURL does not exist, which should return 404 status code as done with similar HTTP operations.

Recommend rewriting this requirement as follows:
6.3.1 GET

This operation MUST return an XML representation of the current root document, as defined by the HRF specification.
If there is no HDR at the base URL, the server SHOULD return a 404 - Not found status code.

Status Code: 200, 404

Rewritten as recommended by submitter. Note that due to renumbering, this section is now 6.3.1.1.

6.2.5 OPTIONS
OPTIONS on HDR baseURL MUST return 200 status

The implied requirement here is following:
If there is no HDR at the base URL, the server SHOULD return a 404 - Not found status code.

This would then be consistent with requirement in section 6.2.1 for GET operation.

Duplicate of Issue 17237, with exception of adding 404. Added the 404 error to address this.

Context:
6.5 baseURL/sectionpath/documentname
6.5.2 PUT

The text "If the request is successful, the new section document MUST show up in the document feed for the section" is not applicable for a document update since it's not a new document but an update.

This is text verbatim from section 6.4.2.2 [Add new document].

The text could be deleted or reworded to something like this:

"If the request is successful, the updated section document MUST [continue to] show up in the document feed for the section".

Changed as suggested by submitter. Note that this applied to the new section 6.5.3, since it was exchanged with 6.5.2.

Context:
6.5 baseURL/sectionpath/documentname
6.5.4 DELETE

Text: Future requests to the section URL MAY return a status code of 410, unless the record is restored.

"section" here should be changed to "document" because that is the context here.

Also for clarification does future request mean only GET requests or does it include any/all operations on the document

The issue is valid and a change was made to address the concern

Context:
6.4 baseURL/sectionpath
6.4.2.1 Add new section

OLD text: When creating the section resource, the server MUST update the root document: in the node of the parent section a new child node must be inserted.

This is the same text copied verbatim from section 6.2.2 which describes creating a new Section at the root of the document: "when creating the section resource, the server MUST update the root document: in the node of the parent section a new child node must be inserted" but in the context of creating a sub-section this is incorrect.

The correct rewording should be:

NEW: When creating the sub-section resource, the server MUST update the Atom 1.0 [3] compliant feed for the parent section: a new child node must be inserted as an entry in the Atom content with a link to the new section.

The suggested update to the parent section’s Atom feed is correct. At the same time, the root document must also be updated to reflect the changed sectional outlay. The suggested text above is added to the paragraph, but does not replace it.

6.4.1 defines a GET with a 200 for success but doesn't address the not found case as defined in other GET operations (e.g. 6.2.1 and 6.5.1)

The implied requirement here is the following, which should be added to the section:

If baseURL does not exist or no sectionpath of name sectionpath exists, the implementation SHOULD (or MUST) return a HTTP status code 404.

This would then be consistent with section 6.5.1 for an invalid/non-existing documentname in the URL

Changed as suggested by submitter

Annex A: reference [1] is normative for this specification but there is no indication of how it can be obatined

Added reference on how to obtain HRF DSTU

8.5 first line type RECOMMEDED

Corrected to RECOMMENDED. Note: this was already corrected in the Beta 1 version