Clarify canonical URI - N-Term #57

XMLWordPrintableJSON

    • Type: Change Request
    • Resolution: Persuasive with Modification
    • Priority: Medium
    • FHIR Core (FHIR)
    • STU3
    • FHIR Infrastructure
    • ValueSet
    • Value set uri
    • Hide
      • It is useful to retain the datatype canonical, since although it has the same syntax as uri it represents additional expectations around how a canonical can be used: it references the .Uri property on conformance resources and can be used as a reference (so e.g. _include across a canonical reference would work). This is in many ways comparable as how for example markdown compares to string: they are both strings, but there are additional expectations around how the content is used.
      • Agree that the use of "canonical" is inconsistent, and thus confusing. It is used in 3 ways: "a reference to the .uri property", "the .uri property of a conformance resource" and "a reference to the combinaton of .uri and .version". It is this last meaning that is correct. We shall go over the definitions pointed out by the submitter and make sure that we clear up that a canonical reference (which is represented by the type "canonical") resolves to an instance of a conformance resource, possibly including a version (|verson suffix), which in the conformance resource is resolved to by the combination of the .uri and .version properties.
      • This is also the reason the .uri property is not itself a canonical: it cannot contain a version part, since that is separated out in the .version property of the conformance resource.
      • Canonicals may have fragments, just like uri's do. Agree that we should not mention it this way to make it sound like uri's would not be allowed to have fragments.
      • Since the .uri property of the conformance resources are not canonical uris themselves (as they cannot have the version part), we should not rename them to "canonical".
      • We should not use "canonical" as an unqualified noun, but instead use "canonical reference" unless we mean the datatype "canonical" .
      Show
      It is useful to retain the datatype canonical, since although it has the same syntax as uri it represents additional expectations around how a canonical can be used: it references the .Uri property on conformance resources and can be used as a reference (so e.g. _include across a canonical reference would work). This is in many ways comparable as how for example markdown compares to string: they are both strings, but there are additional expectations around how the content is used. Agree that the use of "canonical" is inconsistent, and thus confusing. It is used in 3 ways: "a reference to the .uri property", "the .uri property of a conformance resource" and "a reference to the combinaton of .uri and .version". It is this last meaning that is correct. We shall go over the definitions pointed out by the submitter and make sure that we clear up that a canonical reference (which is represented by the type "canonical") resolves to an instance of a conformance resource, possibly including a version (|verson suffix), which in the conformance resource is resolved to by the combination of the .uri and .version properties. This is also the reason the .uri property is not itself a canonical: it cannot contain a version part, since that is separated out in the .version property of the conformance resource. Canonicals may have fragments, just like uri's do. Agree that we should not mention it this way to make it sound like uri's would not be allowed to have fragments. Since the .uri property of the conformance resources are not canonical uris themselves (as they cannot have the version part), we should not rename them to "canonical". We should not use "canonical" as an unqualified noun, but instead use "canonical reference" unless we mean the datatype "canonical" .
    • Grahame Grieve/Ewout Kramer: 14-0-7
    • Clarification
    • Non-substantive
    • STU3

      Comment:

      http://hl7.org/fhir/2018Sep/datatypes.html#canonical defines "canonical" as "A URI that refers to a canonical URI."

      This is prima facie confusing. Does this mean that the subject URI a) is a canonical URI, b) that it contains one, c) that it is-contained by one, d) that it refers to some resource from which the canonical URI can be derived, e) or something else?

      The XML representation of canonical-"xs:anyURI"-doesn't help clarify the issue.

      "Note that the type canonical is not used for the actual canonical URls that are the target of these references, but for the URLs that refer to them, and may have the version suffix in them."

      This seems to rule out (a), but it leaves 'refer' unclear.

      "Canonical URLs may also have #fragment references"

      Any URI may have a #fragment reference. Does this constrain non-canonical URLs from doing so?

      http://hl7.org/fhir/2018Sep/references.html#canonical :

      "Many resource types have a defined element "url" which is the canonical URI that always identifies the resource. The canonical is the preferred way to reference a conformance or knowledge resource."

      This seems clear enough, though the use of "canonical" as a noun is a little disorienting, and it might be better to specify "resource instance."

      However, each of the resources identified here as using 'canonical' has a property "uri" of type "url" with text asserting it's 'canonical.' I.e., the 'canonical' type is not used; rather, the set of expected behavior may be asserted in text.

      http://hl7.org/fhir/2018Sep/references.html#canonical

      "References to canonical URLs may include a version"

      Both URI and Canonical have the same xml definition. Does this imply that non-canonical uris may not include a version?

      I believe the source of confusion for me is that the canonical identifier is documented as a type but it's really a property.

      1. Rename the property from "uri" to "canonicalUri" to avoid confusion with the commonly understood term "uri." The datatype seems redundant, and it could be discarded (though it's used in ElementDefinition).

      2. Clarify the relationship.

      Description of property: change from "Canonical identifier for this value set, represented as a URI (globally unique)" to "Globally unique URI for this value set"

      Definitions: change from "This URL can be the target of a canonical reference." to "This URL can be the target of a canonicalUri reference in a resource."

      http://hl7.org/fhir/2018Sep/datatypes.html#canonical: idealy, remove the type, but if we must,

            Assignee:
            Unassigned
            Reporter:
            Jay Lyle
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved: