align Reference with canonical

[ericprud]

Turtle filename
procedure-example-f201-tpf.ttl

FHIR Resource
Reference:

• definition
• use: Observation.subject
  canonical:
• defintion
• use: Procedure.instantiatesCanonical

ShEx shape
@<Reference>~fhir:link
@<Canonical>
example use: @<Procedure>~fhir:instantiatesCanonical and @<Procedure>~fhir:subject

Description
Reference is a (complex) datatype, canonical is a primitive type. Currently, FHIR/RDF adds a fhir:link to the root of the Reference datatype; there's no analog for canonical. Since canonical is a primitive datatype, it would have to go on the bnode that has the fhir:v property.

subject Reference

  fhir:subject [ # a fhir:Reference ;
     fhir:link <../Patient/f201> ;
     fhir:reference [
       fhir:v "Patient/f201"
     ] ; #   It entails Roel's TPF treatment  
     fhir:display [ fhir:v "Roel" ]
  ] ; # 

instantiates Reference

  fhir:instantiates ( [
     a fhir:Reference ;
     fhir:link <http://example.org/fhir/PlanDefinition/KDN5> ; # current
     fhir:reference [
       # proposed: fhir:link <http://example.org/fhir/PlanDefinition/KDN5> ;
       fhir:v "http://example.org/fhir/PlanDefinition/KDN5"^^xsd:anyURI # note: no version on referene
    ]
  ] ) ; # 

instantiates canonical

  fhir:instantiates ( [
     a fhir:canonical ;
     # proposal A: fhir:link <http://example.org/fhir/PlanDefinition/KDN5> ;
     # proposal B: fhir:link <http://example.org/fhir/PlanDefinition/KDN5?version=v123> ;
     fhir:v "http://example.org/fhir/PlanDefinition/KDN5|v123"^^xsd:anyURI ;
     # proposed-ish: fhir:version? "v123"
  ] ) ; # 

Reference aligned with canonical

  fhir:subject [
     fhir:link <../Patient/f201>   # move link from here
     fhir:reference [
       # proposed: fhir:link <../Patient/f201> ; # to here
       fhir:v "Patient/f201"
     ] ; #   It entails Roel's TPF treatment  
     fhir:display [ fhir:v "Roel" ]
  ] ; # 

Options:

1. align Reference with canonical
2. remove fhir:link from canonical
3. keep Reference and canonical the way they are.
4. fhir:Reference has a fhir:link at the root; fhir:canonical has a fhir:link at its root (i.e. next to the fhir:v) and that value encodes anything after a vertical bar as a ?version=X search parameter.

proposal 4B example

#  instantiates Reference
  fhir:instantiates ( [
     a fhir:Reference ; # type needed because fhir:instantiates is polymorphic
     fhir:link <http://example.org/fhir/PlanDefinition/KDN5> ; # current
     fhir:reference [
       fhir:v "http://example.org/fhir/PlanDefinition/KDN5"^^xsd:anyURI # note: no version on referene
    ]
  ] ) ; 
#  instantiates canonical
  fhir:instantiates ( [
     a fhir:canonical ; # type needed because fhir:instantiates is polymorphic
     fhir:link <http://example.org/fhir/PlanDefinition/KDN5?version=v123> ; # new with this proposal
     fhir:v "http://example.org/fhir/PlanDefinition/KDN5|v123"^^xsd:anyURI ;
  ] ) ;

diff from proposal 1

 #  instantiates Reference
   fhir:instantiates ( [
      a fhir:Reference ; # type needed because fhir:instantiates is polymorphic
>      fhir:link <http://example.org/fhir/PlanDefinition/KDN5> ; # current
      fhir:reference [
<       fhir:link <http://example.org/fhir/PlanDefinition/KDN5> ;
        fhir:v "http://example.org/fhir/PlanDefinition/KDN5"^^xsd:anyURI # note: no version on referene
     ]
   ] ) ; 
 #  instantiates canonical
   fhir:instantiates ( [
      a fhir:canonical ; # type needed because fhir:instantiates is polymorphic
      fhir:link <http://example.org/fhir/PlanDefinition/KDN5?version=v123> ; # new with this proposal
      fhir:v "http://example.org/fhir/PlanDefinition/KDN5|v123"^^xsd:anyURI ;
   ] ) ;

See related #138

[ericprud]

BTW, while dealing with this, you may stumble on a bunch of commented-out initiaesCanonical in e.g. task-cpg-example-1.ttl.htmll:

  fhir:text [
     fhir:status [ fhir:v "generated" ] ;
     fhir:div "<div xmlns=\"http://www.w3.org/1999/xhtml\">...</div>"
  ] ; #   <instantiatesCanonical value="http://hl7.org/fhir..."/>
  fhir:status [ fhir:v "ready"] ; # 

That's not a bug, just an odd editorial choice in the authoritative XML which includes scads of commented-out markup. These comments are not present in JSON 'cause no comments are present in JSON.

[gaurav]

Note that Reference has reference as a string field. But I appreciate that we are treating it specially because FHIR internal references are weird.

  fhir:subject [
     fhir:identifier [
        fhir:use [ fhir:v "official" ] ;
        fhir:system [ fhir:v "https://hospital.system.example/" ] ;
        fhir:value [ fhir:v "Patient/1234-ABC" ] ;
     ];
     fhir:reference [
       fhir:link <../Patient/f201> ;
       fhir:v "Patient/f201"
     ] ;
     fhir:display [ fhir:v "Roel" ]
  ] ; # 

[dbooth-boston]

John Moehrke responded to my zulip question about fhir:reference containing a version. Apparently, the version in fhir:reference has different syntax and meaning than the version in a fhir:canonical, as explained here: https://www.hl7.org/fhir/search.html#versions . However, I'm still trying to determine whether the vertical bar in a fhir:canonical is supposed to be percent encoded.

[dbooth-boston]

John Moehrke responded to my zulip question about fhir:reference containing a version. Apparently, the version in fhir:reference has different syntax and meaning than the version in a fhir:canonical, as explained here: https://www.hl7.org/fhir/search.html#versions . However, I'm still trying to determine whether the vertical bar in a fhir:canonical is supposed to be percent encoded.

[dbooth-boston]

Discussed on today's call: https://www.w3.org/2023/07/13-hcls-minutes.html

[tmprd]

John Moehrke responded to my zulip question about fhir:reference containing a version. Apparently, the version in fhir:reference has different syntax and meaning than the version in a fhir:canonical, as explained here: https://www.hl7.org/fhir/search.html#versions . However, I'm still trying to determine whether the vertical bar in a fhir:canonical is supposed to be percent encoded.

I also see vertical bar in a few R5 examples of xsd:anyURI .

grep -E '.*\|.*\^\^xsd:anyURI' *.ttl
bundle-request-simplesummary.ttl:       fhir:url [ fhir:v "/Observation?patient=example&code=http://loinc.org|55284-4&date=ge2015-01-01"^^xsd:anyURI ]
bundle-search-warning.ttl:     fhir:url [ fhir:v "https://example.org/fhir/Observation?patient.identifier=http://example.com/fhir/identifier/mrn|123456"^^xsd:anyURI ]
bundle-transaction.ttl:       fhir:url [ fhir:v "Patient?identifier=http:/example.org/fhir/ids|456456"^^xsd:anyURI ] #    actually, in a transaction, you don't specify the [base], \n         so [base]\/Patient?params becomes just 'Patient?params':   
codesystem-example-metadata-2.ttl:       fhir:v "http://hl7.org/fhir/CodeSystem/example-metadata|20210701"^^xsd:anyURI ;
conceptmap-example-metadata-2.ttl:       fhir:v "http://hl7.org/fhir/ConceptMap/example-metadata|20210701"^^xsd:anyURI ;
namingsystem-example-metadata-2.ttl:       fhir:v "http://hl7.org/fhir/NamingSystem/example-metadata|20210701"^^xsd:anyURI ;
valueset-example-metadata-2.ttl:       fhir:v "http://hl7.org/fhir/ValueSet/example-metadata|20210701"^^xsd:anyURI ;

I found these with HermiT. Which ShEx schemas are used to validate these?

[tmprd]

I believe changes to this will need to be made somewhere in here:
https://github.com/hapifhir/org.hl7.fhir.core/blob/master/org.hl7.fhir.r5/src/main/java/org/hl7/fhir/r5/elementmodel/TurtleParser.java#L372

[dbooth-boston]

Option 4 looks best to me. What do others think?

[gaurav]

I'm not seeing a difference between Option 1 and Option 4, but that's the one I like the best :)

[dbooth-boston]

@ericprud maybe it would be helpful to show both a Reference and a canonical example in the proposed Option 4 syntax.

[tmprd]

With respect to the apparently invalid xsd:anyURI values we found, I’ll mention here that we discovered on 12/7 (technically cancelled meeting) that these values are likely valid according to XSD 1.1, which is more permissible than XSD 1.0.

See: https://stackoverflow.com/questions/33826104/can-xsd-type-of-anyuri-contain-spaces/33832910#33832910
XSD 1.1 https://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/datatypes.html#anyURI
XSD 1.0 https://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html#anyURI

Replacing the vertical bar with ?version=X in a fhir:link will be helpful, but if we want XSD 1.0 based systems to properly validate the existing xsd:anyURI values in fhir:v, those values would need to be converted to remove or encode illegal characters such as the vertical bar. The HermiT reasoner in Protege is one such system, which will infer that "http://hl7.org/fhir/CodeSystem/example-metadata|20210701"^^xsd:anyURI is invalid.

The precedent for making modifications to FHIR RDF to support OWL use cases is to offer separate scripts, such as the one which converts RDF lists, here: https://github.com/w3c/hcls-fhir-rdf/tree/gh-pages/scripts This is probably the best option to avoid complicating broader use cases. ShEx implementers would then need to adopt the XSD 1.1 interpretation, which is far less useful for validation but is technically more up-to-date.

[dbooth-boston]

AGREED to 4B on today's call: https://www.w3.org/2024/01/04-hcls-irc#T16-36-22

[dbooth-boston]

Reopened pending the merge of the actual fix.

[dbooth-boston]

This still needs to be fixed.

[balhoff]

I'll take a look at this one.