# OPT version, schema & document

**Category:** [Archetype Designer](https://discourse.openehr.org/c/archetype-designer/30)
**Created:** 2020-03-19 03:02 UTC
**Views:** 2859
**Replies:** 38
**URL:** https://discourse.openehr.org/t/opt-version-schema-document/486

---

## Post #1 by @seungjong.yu

Hi. 
Many thanks to great contributors !
I'm Seung-Jong Yu and not a newbie but kind of lurker  :slight_smile: 

I can't categorize my topic, so post here.
I have some OPT-related questions while I'm making  some templates and export it in OPT using Better's Archetype Designer.

Here are questions.

1)   OPT of Better's Archetype Designer has some unknown attributes and omits those (via Cabolabs' Operational Template XML Validator). For example, the former are "**matches_negated**" , "**Ontology**" and "**component_ontologies**", the latter are "**<node_id/>**" and "\<view>...\</view> ". 
Do those follow the openEHR specification? If yes,  gap in different OPT versions?

2) For checking 1), I am searching OPT document and schema. But I have not found any clues in various resources yet. Then is below right?

(1) The link of OPT1.4 is dead ,but from other threads, there is no link now, so if I have question, a specific question needs to be posted on this forum. And OPT2 document is not finalized.

(2) All OPT Schemas are in https://github.com/openEHR/specifications-ITS-XML. Those are latest.

Any helpful comments are welcomed !

Best regards

Seung-Jong Yu        MD
seungjong.yu@gmail.com

---

## Post #2 by @ian.mcnicoll

Hi ,

Thanks for flagging this up. 

Could you send the template fileset AD-> Export-Template Fileset so we can see  the specific example? Just attach it here?

I might try to move this to a more technical category but carry on replying here

Ian

---

## Post #3 by @seungjong.yu

Thank you for fast reply.

Please file attached and you also can see my "SOAP" template in "Seung-Jong" repository of Better's Archetype Designer.

Seung-Jong Yu        MD

2020년 3월 19일 (목) 오후 6:08, Ian McNicoll via openEHR <discourse@openehr.org>님이 작성:


(Attachment SOAP.zip is missing)

---

## Post #4 by @ian.mcnicoll

Hi sorry - the attachment is missing - I think Discourse may block some file attachments - can you send it to ian@freshehr.com and I will post it.

@sebastian.garde @borut.fabjan  - can you help with this ?

Template File set is at - https://www.dropbox.com/s/odu67dh3c2x2lsd/SOAP.zip?dl=0

---

## Post #5 by @sebastian.garde

I cannot contribute much to this, but since you asked, I'll share what little I know:
*  I can't remember seeing *matches_negated* before. 
* Re *ontology*: this seems to exist as a separate element, but I am not sure I have seen this used. It seems you can just add term_definitions etc. directly to the definition in the opt14 and this seems to be what is done instead of separating this out into ontology and component_ontologies. Not sure if this is just interchangable. But if so, I would have expected the term_definitions etc. to be underneath, whereas in your example it is just the archetype ids on their own...This is probably syntactically ok, but not sure what purpose it would serve?

---

## Post #6 by @pablo

Hi, I don't know if the schemas are being correctly versioned right now, but for OPT 1.4 validity you can check them on the openEHR Toolkit that validates against the  OPT 1.4 XSD https://server001.cloudehrserver.com/cot/

I mentioned on another thread that the Marand tools might generate OPTs differently from the Template Designer, and also might be different to the OPT 1.4 XSD.

---

## Post #7 by @seungjong.yu

@sebastian.garde I add component_ontologies and \<view>..\</view> to original thread as unknown & omitting cases.

@pablo I agree. Better's Archetype Designer may have their own syntaxes. 

how can I solve it?

---

## Post #8 by @ian.mcnicoll

Ontology, component ontology and views were definitely introduced by the Ocean Template Designer so it is possible that the XSD has not been updated

I'm not sure about <match_negated> @borut.fabjan @matijap - any idea what this is for in the .opt? It is certainly not in the Ocean .opt that I can see.

The .opt generated by CKM (which based on an Ocean webservice, which should match TD behaviour) does contain the <view> 

https://openehr.org/ckm/templates/1013.26.280/opt

Compared to the Better .opt it also does not contain <ontology> and <component_ontologies> but I have checked and I know that TD definitely used to generate these elements. They are used to carry multiple languages within an .opt. I suspect the difference is that the Better version is always to generate these elements, even if the template carries only a single language, whilst Ocean generate it only when there are multiple languages.

So the upshot is that I think the only real difference in the two formats is <match_negated> which Better seeme to have introduced, and that the .xsd that Pablo has (and I think this was the only one that could be found) does not reflaect some other more recent changes (at least 5 years old) in .opt generation, whoich are in fact common to both Better and Ocean. 

Suggest we clarify and then update the .xsd

---

## Post #9 by @seungjong.yu

@ian.mcnicoll Thank for your very helpful summary !

---

## Post #10 by @pablo

[quote="ian.mcnicoll, post:8, topic:486"]
the .xsd that Pablo has (and I think this was the only one that could be found) does not reflaect some other more recent changes (at least 5 years old) in .opt generation, whoich are in fact common to both Better and Ocean.
[/quote]


The issue I see is we don't have a managed versioned environment for OPT XSDs, so everyone might be using a slightly different OPT structure. We need to know what is OPT 1.4 XSD v1.0 and what is OPT 1.4 XSD v2.0, and that should be differentiated from OPT 2.0 XSD v1.0 (note we have two versions of the OPT spec and different versions and revisions for the correspondent XSDs for each OPT version, and AFAIK no XSD is currently versioned so we don't know what we are using, or what is current). This should be formally defined, "common practice" or "recent changes" is not a formal versioning system :(

Also AFAIK, this wasn't discussed in the SEC and IMO should be a priority to avoid confusing devs.

---

## Post #11 by @ian.mcnicoll

Completely agree Pablo. It is confusing for relative outsiders (and some of us insiders!!). The good news is, I think, that for practical purposes there is not a major issue - the various differences in actual .opt formats are  pretty minor and any 'real' incompatibilities seem to have been resolved between Ocean and Better's tooling.

The real issue is that the formal .xsd has not kept up with  'de-facto standard' usage and I suspect is not used internally by either Ocean or Better.

Id be happy to help pester tooling suppliers if someone (hello Pablo!!) could have a go at updating the .xsd to reflect current usage. 

1. Support ontology and component ontologies (Better and Ocean)
2. Support view (Ocean only)

3. Find out from Better about match_negated - Ian

---

## Post #12 by @pablo

I guess we need, before updating anything, to establish a versioning scheme and identify different XSDs around as different versions of the same initial XSD, which I would say is v1.0

In my case the first OPT 1.4 XSD that I found was in 2015, I think was part of the Template Designer or ADL Workbench, and did small changes since then, which are documented here https://github.com/ppazos/cabolabs-ehrserver/commits/branch_v1.5.1/xsd/OperationalTemplate.xsd

So the main thing would be to gather XSDs differnt implementers are using and do a diff to check what they have added, then say "this is v1.0, that is v1.1, etc", after that, agree with them to use that version number/semver.

After that, I would also ask implementers to manage change requests in the main repo to avoid local changes, so the SEC can manage versions and releases.

Also would be useful to identify which XSD version is used on different modelling tools to avoid issues, which we are having right now between Ocean and Marand tools. In LinkEHR I think you can upload any XSD and work with that, would need input from @yampeku

---

## Post #13 by @yampeku

Currently support to OPT in LinkEHR is handcrafted. If I remember correctly, I found some parts in OPT that weren't in the XSD Pablo provided me back in the day, so kind of reverse engineered it. 
On other matter, XSD import in LinkEHR is restricted to RM creation or data source definition for mapping.

---

## Post #14 by @pablo

Thanks Diego, would it be possible to use different OPT model versions or would that be a huge change to LinkEHR?

---

## Post #15 by @yampeku

Probably they can be supported with not too much work, as more or less everything should be there. If it changes completely then more work would be needed.

---

## Post #16 by @ian.mcnicoll

I'm not sure we need ot support multiple versions, just a latest version, then properly handle it from there. In practice , things seem to be working pretty well without a 'current' XSD, and TBH if the tooling vendors are not rally using an XSD internally it is going to be quite tricky to find/pin-down older versions. 

We basically have 3 'public' tooling vendors

Better
Ocean
LinkEHR

Right now Better / Ocean are virtually aligned, in working practice i.e the .opts are interchangable other than for some minor differences. Let;'s sort out those differences. document them, and cross-check with  LinkEHR and go with that as the baseline. Then govern properly from now on?

Let's be careful not to waste too much energy on an issue which I agree should be fixed but is not actually a practical problem right now for working tooling.

---

## Post #17 by @thomas.beale

Probably need to check with @sebastian.iancu who did a lot of work organising XSDs; don't know whether he got a definitive one for the OPT 1.4, but the only things anyone should be using are in the  [specifications-ITS-XML Git repo](https://github.com/openEHR/specifications-ITS-XML/tree/master/components). I don't see an OPT XSD in there, but if we have a candidate, let's put it in.

---

## Post #18 by @ian.mcnicoll

That's the problem - the only candidate that anyone could identify  is the old version that Pablo has. It is out of date but the new aspects have mostly been in place for a long time - that version just needs updated to reflect what is actually a high degree of alignment in .opt.

---

## Post #19 by @pablo

[quote="ian.mcnicoll, post:16, topic:486"]
I’m not sure we need ot support multiple versions
[/quote]


I don't think we need to "support" but to start "tracking" changes. Support means maintaining old versions, what I was referring to was to detect changes between versions and assign a version number to each one, then keep maintaining the last one, but have all the XSD versions under one versioned environment.

[quote="ian.mcnicoll, post:16, topic:486"]
Let’s be careful not to waste too much energy on an issue
[/quote]

This is very easy thing to do, and I can do it, we just need the XSDs each provider is using, I can merge the XSDs into one file (http://www.strategicdevelopment.io/tools/SchemaLightener.php) then do a diff comparing 2 by 2 and noting the changes. The file with most changes will be the latest version, and I guess the one I have imported in 2015 is the first version.

Also this comparison will let us know if there are any incompatibilities between the XSDs out there, that is a more difficult thing to solve since different implementations might rely on different rules. That is why we can't just keep track of the latest version only: implementations using incompatible XSDs will be forced to adapt and that might not be possible. Incompatible means some element is required by the new schema but was optional or didn't exist on a previous one.

Would it be possible to get the XSDs from Better and Ocean?

---

## Post #20 by @pablo

[quote="ian.mcnicoll, post:18, topic:486"]
the only candidate that anyone could identify is the old version that Pablo has
[/quote]


BTW the one I have is a merge from the multiple modular XSDs I found back in 2015, just because working with one file is easier than working with many. But I might have the original files somewhere on an old VM.

---

## Post #21 by @ian.mcnicoll

I have asked for any current XSDs from Ocean and Better

---

## Post #22 by @heath.frankel

@ian.mcnicoll I tried to upload the OPT Template.xsd here but it looks like there is a limit on the file types that can be uploaded here so i will email it to you.
In short, the OPT schema was updated back in 2010 to support annotations.  
In Aug 2012 there were some changes made relating to annotations that may have introduced some inconsistencies, these we reverted in Mar/Apr 2015 and the OPTs generated by CKM and Ocean Template Designer should be compatible with the original 2010 XSD.

Just to reiterate, the only changes and possible inconsistencies between some versions of the Ocean Template Designer is related to Annotations, nothing else has changed since 2010.

---

## Post #23 by @pablo

Can you zip them or share via drive/ Dropbox?

---

## Post #24 by @ian.mcnicoll

Heath  has emailed me the Ocean xsd - Better do not use one. So basically we need to test he xsd against bteer and Marand current .opt generation anyone else @yampeku @pieterbos - do you make use of the .op 1.4 xsd or genrrate 1.4 .opt?

---

## Post #25 by @yampeku

LinkEHR can import/export OPT, in principle follows the format TD can export/read

---

## Post #26 by @ian.mcnicoll

Ok - I have spoken to Pieter @Pablo.

1. Nedap do not use .opt 1.4
2. linkEHR just tracks Ocean
3. Better do not have an internal XSD and have made a tweak or two from the Ocean .opt format
4. The Ocean XSD that Heath has sent over is probably the 'gold standard' for now

I suggest we run a few text examples from Ocean TD, CKM and Better AD past this and see what falls over.

---

## Post #27 by @sebastian.iancu

I cannot recall why we don't have the OPT XSD on github.
Once you get the final OPT XDS, I will worked it out into ITS-XML repo.

---

## Post #28 by @pablo

@ian.mcnicoll I'm checking differences between the XSD I have (CaboLabs) and the one provided by @heath.frankel (Ocean)

1.  CaboLabs XSD has a DEFAULT_VALUE type and types extending that:

DEFAULT_BOOLEAN
DEFAULT_STRING
DEFAULT_INTEGER
DEFAULT_REAL
DEFAULT_DATE
DEFAULT_DATE_TIME
DEFAULT_TIME
DEFAULT_DURATION
DEFAULT_CODE_PHRASE
DEFAULT_DV_ORDINAL
DEFAULT_DV_QUANTITY
DEFAULT_DV_STATE

All those "DEFAULT_" types are not defined in Ocean's XSD.

Those are used in the C_ARCHETYPE_ROOT.default_values element, which is not defined in Ocean's XSD.


2. Ocean XSD has these elemets that are not in the CaboLabs's XSD

OPERATIONAL_TEMPLATE.is_controlled
OPERATIONAL_TEMPLATE.annotation
OPERATIONAL_TEMPLATE.revision_history
OPERATIONAL_TEMPLATE.ontology *
OPERATIONAL_TEMPLATE.component_ontologies *

\* both have type FLAT_ARCHETYPE_ONTOLOGY which is also not included in CaboLabs' XSD. FLAT_ARCHETYPE_ONTOLOGY is an extension of ARCHETYPE_ONTOLOGY that adds an archetype_id attribute to the ARCHETYPE_ONTOLOGY.


3. OPERATIONAL_TEMPLATE.view seems to be in conflict:

Ocean:

- has OPERATIONAL_TEMPLATE.view with type T_VIEW
- has OPERATIONAL_TEMPLATE.constraints with type T_CONSTRAINT

CaboLabs: 

- has OPERATIONAL_TEMPLATE.view with an inline type (not explicit T_VIEW), 
- the inline type has an optional 'id' attribute, which is mandatory in Ocean XSD. Also 'path' is optional in CaboLabs XSD but required in Ocean's XSD.
- doesn't have OPERATIONAL_TEMPLATE.constraints element.


4. CaboLabs XSD has PROPORTION_KIND type which is not present in Ocean's XSD.

I think that one is missing because there is one missing XSD from the Ocean ones, basetypes.xsd (and anything included there). Without all the dependencies I might find more missing types, so I'll stop here until we get the complete set.

---

## Post #29 by @ian.mcnicoll

I can't upload here - - see slack.

---

## Post #30 by @pablo

I was able to add the missing XSD to the flat file and recheck, yes the PROPORTION_KIND is defined in Ocean XSD, so we are good for point 4.

5. AUTHORED_RESOURCE is abstract in CaboLabs XSD, but is not in the Ocean's XSD.

CaboLabs:

`<xs:complexType name="AUTHORED_RESOURCE" abstract="true">`

Ocean:

`<xs:complexType name="AUTHORED_RESOURCE">`


6. RESOURCE_DESCRIPTION.details minOccurs = 1 in CaboLabs XSD but is 0 in Ocean's XSD.

CaboLabs:

`<xs:element name="details" type="RESOURCE_DESCRIPTION_ITEM" maxOccurs="unbounded"/>`

Ocean:

`<xs:element name="details" type="RESOURCE_DESCRIPTION_ITEM" minOccurs="0" maxOccurs="unbounded"/>`


7. DV_IDENTIFIER elements are optional in Ocean's XSD while mandatory in CaboLabs XSD.

CaboLabs:

    <xs:element name="issuer" type="xs:string"/>
     <xs:element name="assigner" type="xs:string"/>
     <xs:element name="id" type="xs:string"/>
     <xs:element name="type" type="xs:string"/>

Ocean:

    <xs:element name="issuer" type="xs:string" minOccurs="0"/>
    <xs:element name="assigner" type="xs:string" minOccurs="0"/>
    <xs:element name="id" type="xs:string"/>
    <xs:element name="type" type="xs:string" minOccurs="0"/>


Ocean is compliant with RM 1.0.4, and CaboLabs with RM 1.0.2:

  - https://specifications.openehr.org/releases/RM/Release-1.0.2/data_types.html#_overview_2
  - https://specifications.openehr.org/releases/RM/latest/data_types.html#_overview_2


8. Modification done to the CaboLabs XSD: OBJECT_ID

Added constraint to OBJECT_ID.value to be a non empty string, to comply with the RM:

Original/Ocean:

`<xs:element name="value" type="xs:token"/>`

CaboLabs:

    <xs:element name="value" type="NotEmptyToken"/>

    <xs:simpleType name="NotEmptyToken">
         <xs:restriction base="xs:token">
           <xs:minLength value="1" />
         </xs:restriction>
      </xs:simpleType>


Check the modification history: https://github.com/ppazos/cabolabs-ehrserver/commit/1c1a453ad8b01315bbfe26272f82c7e21cbd7b55#diff-1bb01a8b3db81ef3b88ee42fac41d6ba


9. Modification done to the CaboLabs XSD: OBJECT_VERSION_ID

Added a constraint over the format of OBJECT_VERSION_ID.value, because didn't have any constraint on the original OPT.

Original/Ocean:

    <xs:complexType name="OBJECT_VERSION_ID">
            <xs:complexContent>
                <xs:extension base="UID_BASED_ID"/>
            </xs:complexContent>
    ...

CaboLabs:

    <xs:complexType name="OBJECT_VERSION_ID">
             <xs:complexContent>
                  <xs:restriction base="UID_BASED_ID">
                     <xs:sequence>
                          <xs:element name="value" type="OBJECT_VERSION_ID_VALUE_FORMAT"/>
                     </xs:sequence>
                  ...

    <!-- https://github.com/ppazos/cabolabs-ehrserver/issues/913 -->
      <xs:simpleType name="OBJECT_VERSION_ID_VALUE_FORMAT">
         <xs:restriction base="NotEmptyToken">
            <xs:pattern value="[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}::(\w.*)::([0-9]+[0-9]*(\.[0-9]+[0-9]*(\.[0-9]+[0-9]*)?)?)"/>
         </xs:restriction>
      </xs:simpleType>


10. Modification done to the CaboLabs XSD: view element was not generated by the Template Designer.

Added a minOccurs=0 to the view element. Change and associated issue here: https://github.com/ppazos/cabolabs-ehrserver/commit/989147f3956b754b5b0b624d4cc3deb5d25da0a7#diff-1bb01a8b3db81ef3b88ee42fac41d6ba


11. REVISION_HISTORY_ITEM audit vs audits:

Ocean: REVISION_HISTORY_ITEM.audit
CaboLabs: REVISION_HISTORY_ITEM.audits

I guess this is a typo in "audits" and should be "audit", need to check the RM.


12. Optional vs. mandatory PARTICIPATION.mode

CaboLabs: mode is mandatory

`<xs:element name="mode" type="DV_CODED_TEXT"/>`

Ocean: mode is optional

`<xs:element name="mode" type="DV_CODED_TEXT" minOccurs="0"/>`


In the RM 1.0.4, PARTICIPATION.mode is optional, but in RM 1.0.2 mode is required. **This makes me think we also need to release XSDs for each RM version.**


That's all I can find.

IMO, the Ocean one was updated recently, at least for RM 1.0.4 and CaboLabs keeps compliance with RM 1.0.2.

---

## Post #31 by @heath.frankel

@pablo , it looks like you have a very old version of the OPT that was authored way back in 2007. 
The XSD I provided has been used by the Template Designer since 2010, including version 2.6 and above.

All the default values where removed as it was deemed that these should not be included in an OPT, they are only relevant to archetypes.

---

## Post #32 by @pablo

@heath.frankel The one I have is compliant with what the Template Designer 2.8.beta is exporting as OPT. We are using that and RM 1.0.2 for the EHRServer.

---

## Post #33 by @linforest

This is indeed an incompatibility  issue that should be addressed.
For example, the  OPTs in the directory "opts" of the EHRServer's GitHub repository couldn't be opened by Ocean Template Designer (v3.0.169) due to Schema validation problems, such as the root element  "template".

As an intrim workaround, an older version of Ocean Template Designer could be recommended on the github Readme page.  And some older versions should also be available for this purpose.

---

## Post #34 by @pablo

The template designer only opens OET files, not OPTs, OPT is an exported file while the OET is the source. I guess you are trying to edit an OPT file and that is not the correct way of editing templates. That is why it gives you the validation errors. Those are different formats!

---

## Post #35 by @linforest

Pablo, Thank you so much.  Exactly, you are right :slight_smile:

---

## Post #36 by @pablo

Just in case you are using the EHRServer and want to edit the templates, I tried to maintain the source files under this repo https://github.com/ppazos/knowledge

Might be out of date, just in case you need some OET in particular and it's not in that repo, I can look for it on my local test data sets.

---

## Post #37 by @linforest

Wow, that would be great!

---

## Post #38 by @sebastian.iancu

I realize this issue might not be solved yet.
Is there any newer variant of these OPT types schemas (a new XSD file) from Ocean (@sebastian.garde) or Better (@matijap @borut.fabjan) that we could use to update specifications-ITS-XML repo?

---

## Post #39 by @sebastian.garde

I don't think the Ocean one has changed. 

Not all, but most of the differences described seem rather small and partly due to RM version differences.
If we are after one schema that is 100% normative and as restrictive as possible, I think we do not have a choice but to specify its RM version?

---


**Canonical:** https://discourse.openehr.org/t/opt-version-schema-document/486
**Original content:** https://discourse.openehr.org/t/opt-version-schema-document/486