# Get an instance of the RM from an Archetype

**Category:** [Reference Implementation: Java (archive)](https://discourse.openehr.org/c/reference-implementation-java-archive/154)
**Created:** 2009-06-14 04:50 UTC
**Views:** 16
**Replies:** 16
**URL:** https://discourse.openehr.org/t/get-an-instance-of-the-rm-from-an-archetype/14902

---

## Post #1 by @pablo

Hi,

I see that the parsed definition section of an archetype is instanced to the constraint model, but the definition section is (in some way) also a description of the RM instance.

Is there some way to get an instance of the OpenEHR RM from a parsed archetype?

Thank you!

---

## Post #2 by @system

An RM\-instance is always data\. It are the data modelled following the
archetype\-definition\.

One way to present these data is DADL, you need the DADL\-parser together
with the RM\-builder to create an RM\-instance

Another way is create an special formed of an XML file to contain the
data\. In that case you can use JAXB or Castor to create an RM\-instance
Tip: create with JAXB or Castor an XML\-file containing example data, so
it is easier to check what your XML\-file containing data to make it
importable\.

If you use XML instead of DADL, then you don't need the DADL\-parser and
RM\-builder\.

regards,
Bert

---

## Post #3 by @pablo

Hi Bert,

I was thinking on the RM instance not as the data itself, I was thinking
that the RM instance is de structure that contains the data\. I think if the
archetype defines the structure of the RM \(I think it's like a class in
OOP\), I can use this definition to make instances of the RM that match that
definition, and I can put the data inside this structure and validate it
against the constraints defined on the same archetype\. \(that was all I
suposed, is it wrong?\)

If I work with JAXB I think that I need to create the XSDs for all my
archetype definitions, so the XML instances of the RM that I create with
JAXB are the same I constraint on the archetype, is this the way I should do
it? \(\*\) if not, I don't see how my XML instances of the RM can match the
definition I made on the archetype\.

\(\*\) I don't want to define things twice, one on my custom archetype and the
same on the XSD\.

thanks for the patience\.

Pablo

---

## Post #4 by @system

> Hi Bert,
>
> I was thinking on the RM instance not as the data itself, I was thinking
> that the RM instance is de structure that contains the data\. I think if the
> archetype defines the structure of the RM \(I think it's like a class in
> OOP\), I can use this definition to make instances of the RM that match that
> definition, and I can put the data inside this structure and validate it
> against the constraints defined on the same archetype\. \(that was all I
> suposed, is it wrong?\)

I don't know if I understand what you say\.
A RM\-class\-instance \(coming from locatable\) has its structure, in that
structure do fit data\. An archetype is an extra layer above this
class\-definition to add constraints, restrict the class, and other
things like terminology\.

> If I work with JAXB I think that I need to create the XSDs for all my
> archetype definitions, so the XML instances of the RM that I create with
> JAXB are the same I constraint on the archetype, is this the way I should do
> it? \(\*\) if not, I don't see how my XML instances of the RM can match the
> definition I made on the archetype\.

Because an archetype always depends on the structure of a
locatable\-class, any data belonging to an archetype can fit in a
XML\-file which need to fit to an XSD created with JAXB\.

So you do not need to extra define XSD's belonging to a specific
archetype\.

What you need to do is write routines which validate the data in a
RM\-class\-instance \(which you created from XMLled\-data by using JAXB and
the XSD's\) to the archetype constraints\. You can find help in the
openehr\-aom and the adl\-parser code\. Both hand to you the
information\-structures needed to validate the data\.

Maybe I do not say it clear and is there somewhere a document where this
is explained better\.

Bert

---

## Post #5 by @pablo

Hi, my comments are between lines:

Thanks a lot\!

---

## Post #6 by @system

> ```
> Hi, my comments are between lines:
>
> Thanks a lot!
>
> ```

I am glad to help.

> ```
>
> ```
>
> ```
> Sorry for my english :)
> I understand what you say, but I don't see where is the definition of the
> structure that contains the data (an structure of RM-class-instances, not
> just one RM-class-instance).
>
> ```

A structure of RM classes is always headed by a single RM-class. You always end up at a single RM class which is the root of an archetype
Excuse me for not going into your example. Always when I just see a medical phrase it gives me shivers. I have other people which examine the medical stuff.

> ```
> I thought that the archetypes defines that structure. May be an example can
> guide my doubts:
>
> 1. I need the "Blood pressure" concept in my clinical application.
> 2. I have a generic XSD of an Observation (Blood pressure is a particular
> Observation) >
>
> ```

You need that.

> ```
> [http://www.openehr.org/releases/1.0.1/its/XML-schema/documentation/Content.xsd.html](http://www.openehr.org/releases/1.0.1/its/XML-schema/documentation/Content.xsd.html)
> 3. In the "Blood pressure" archetype I define constraints for an generic
> Observation but I use the particular structure of de Blood pressure concept.
> 4. Now <<I need to create an instance>> of the Blood pressure concept, so I
> can fill it with my data (Systolic an Diastolic pressures).
> 4.1 If I undertand what you said, I can make my own XML (I must program some
> custom logic to do it) that is the structure I need. That XML must match the
> generic Observation XSD.
>
> ```

That is what I say, and how I work. There are more ways to do, but this seems the most convenient way.

> ```
> 4.2 Now, I fill the structure with data (I know, when I create the XML I
> fill it with the data, I separate 4.1 and 4.2 for better understanding).
>
> ```

Yes,

> ```
> 4.3 Here I have a Blood pressure instance (the structure and data), I can
> validate it against the generic Observation XSD.
>
> ```

Exactly

> ```
> 4.4 I can validate 4.3 against the Blood pressure archetype (3).
> 4.5 If it's all right, I have a valid instance of the RM that represents a
> concept in my clinical application.
>
> Is it correct?
>
> ```

Completely, maybe we oversee one step, but that will show up.

> ```
> I still have some doubts, if you see in step 4.1 I have to write some code
> to create a custom Blood pressure XML, <<that's the definition>> of Blood
> pressure to my application. So, I have that definition (D), and I have an
> archetype with the same??? definition (D') to constraint (D), so I have to
> write the "same" thing 2 times (the definition of my custom XML and the
> Archetype that constraint my XML).
>
> ```

Yes, you need to constraint the data-entry to get useful data. It is a possibility to write code which translate archetypes to GUI-code.

There is some example, very rudimentary, in the Java-archetype-editor.

> ```
> If this process is right, why not just wirte the archetypes I need (or use
> the ones on the archetype repository of OpenEHR) and use the structure in
> the "definition" section of the archetype to build my XML instance of the
> RM?
>
> ```

It is possible to do. What seems convenient

> ```
>
> ```
>
> > > ```
> > > If I work with JAXB I think that I need to create the XSDs for all my
> > > archetype definitions, so the XML instances of the RM that I create with
> > > JAXB are the same I constraint on the archetype, is this the way I should
> > > do
> > > it? (*) if not, I don't see how my XML instances of the RM can match the
> > > definition I made on the archetype.
> > >
> > > ```
> >
> > ```
> > Because an archetype always depends on the structure of a
> > locatable-class, any data belonging to an archetype can fit in a
> > XML-file which need to fit to an XSD created with JAXB.
> >
> >
> > ```
>
> ```
>
> I don't know why I need to create an XSD with JAXB if I have the RM XSDs
> > [http://www.openehr.org/releases/1.0.1/its/XML-schema/](http://www.openehr.org/releases/1.0.1/its/XML-schema/)
>
> ```

The scheme did not work for me, but I modified the RM-kernel a bit. And than there are problems. But it is "easy" to generate a new XSD from the kernel, although I had to annotate quite a lot.

> ```
>
> ```
>
> > ```
> > So you do not need to extra define XSD's belonging to a specific
> > archetype.
> >
> > What you need to do is write routines which validate the data in a
> > RM-class-instance (which you created from XMLled-data by using JAXB and
> > the XSD's) to the archetype constraints. You can find help in the
> > openehr-aom and the adl-parser code. Both hand to you the
> > information-structures needed to validate the data.
> >
> > ```
>
> ```
>
> Is it the process I described before?
>
> ```

Yes, about. I think you understand me well. There is a lot of work done by Rong, but still there is a lot to do.
You also need to write the RM-instacne-data to a persistence store, and be prepared for AQL (archetype query language)

So don't hurry into solutions is my advice.

Good luck
Bert Verhees

---

## Post #7 by @pablo

Great, I think it's to late, I hurried to a solution! XD

I think it is possible to write a method on the archetype class (or locatable) to obtain the structure of the RM that matches to de definition section of the archetype.

To fill the RM with data, you can create a method on the RM classes, that takes a map as parameter. That map contains entries with: path->value, so each value needed is filled on the RM instance.

Then you can validate the instance against the archetype (that constraint the values).

Now you can serialize the RIM instance to XML and store it in some place, or you can communicate it to another system, etc. You can use XStream lib to do so. http://xstream.codehaus.org/

You can give me the pros&cons of this solution.

Thanks a lot!

Cheers,
Pablo.

---

## Post #8 by @Seref

Hi Pablo,
Basically it is all about the relationship between the archetype and RM, and for the developer, this becomes managing the links between RM, AOM and Data.
However, do not think that the archetype and its nodes will have a one to one correspondence to RM instances. Here is an example: the archetype can easily say that zero or more instances of an RM class go here (insert a path here), like codes that correspond to observations. Now if you try to create an RM instance based completely on the archetype, how do you know the right amount of RM type instances for a particular node? You can't. The archetype describes an RM structure, with some flexibility, some things, like the number of child nodes of a particular RM node will be determined by the user. So the relationship between the RM instance and the archetype can get more complicated than you imagine at first.
Path -> value method is quite useful, but it has its tricks too. Now imagine you have a path that contains a DV_Quantity. Great, but how do you pass the value? The value of a DV_Quantity is not something like 3 or 5, it is a combination of different fields like magnitude, and unit, and maybe even more (check out the uml diagram to see what fields it inherits) .
So, even if your fundemental approach looks right, there are traps you need to watch for :) Too see an example of the things I'm talking about, you can check out [http://opereffa.chime.ucl.ac.uk](http://opereffa.chime.ucl.ac.uk) Take a look at the source. Even if I did not use XML, it should help you to see the the relationship between Archetypes, RM instances and data.
Finally, remember that the specifications do not limit your ways of implementation. You can go your own way and implement the same specification completely different than others. You'd still be working on the same major concepts you've listed though.

Kind regards
Seref

---

## Post #9 by @pablo

Hi Seref,

I understand that an archetype is no enought to define an RM structure, your example is very clear.

I'm thinking a solution (implementation) in wich the RM structure and the AOM structure that
constraints it, are defined in the same way (may be in the same file! so I can check consistency
of things just looking at one source).
This way I can model with the RM a health concept in my system, and at the same time define
the constraints that concept must meet.
Any suggestions?

With the path -> value mechanism, can't you define a path to a simple value? I know that OpenEHR
datatypes are complex types, but I think you can reach a simple value with a path:
path_to_dv_quantity/units, path_to_dv_quantity/magnitude, etc.

Your opinions are very helpful!

Thanks a lot!
Pablo.

---

## Post #10 by @Seref

Hi Pablo,
I am not sure I can understand your approach clearly. For anyone interested in openEHR, it is vital to understand the differences and roles of different layers/component groups. There is a reason that AOM and RM are expressed differently, and they server different purposes. First of all, AOM is the result of a parsing action, it is the representation of an Archetype, so I can't understand in which context you'd like to have it in a file??
Here is a tip for you: do not try to invent generic methods, or in other words programmatic shortcuts when using openEHR. A lot of people reading the specs (including me) get the feeling that they can write some sort of code that can work in many dimensions and many cases. Somehow, it creates this illusion. This approach however, always ends up with frustration, since your generic method will start hitting more and more bumps on the way, due to increasing specialization in the leaf nodes of archetypes, in other words, RM types :)
Yes, you can write generic code for things like walking on an AOM structure, and some other things, but I can say that IMHO making an openEHR based system work requires you to write a lot of type specific, RM related code. I can't see a magic way of coding to bypass this, and if there is someone out there who is willing to prove me wrong, I would love to hear them.
So my suggestions are as follows:
Even if you are going to give a new method a try, start with the simpler approach. Assuming you are going to use Java, take a look at Rong's excellent work in Java reference implementatation, especially check out unit test codes which create RM type instances, they will help you to get an understanding of how RM instances are created, and what they contain etc.
Start with this very simple task: read an ADL file, and use Rong's unit test code to create values for the RM types you'll encounter in AOM. Sounds very simple right? Just give it a try, and you'll have an understanding of the differences of main parts.
If you can continously generalize a piece of code that satisfies your functional requirements, then I don't think anyone can say that what you are doing is wrong. It is just that as you try to add new functionality, your approach may not handle the new cases, so be ready to throw away your code. There is a reason software is called software, it can change!

Regarding what you say about path, value method: it is the method that is used in Opereffa too, all I'm trying to say is, it gets more complicated than single name, value pairs, but the basic idea is usable, at least I've used it to create a piece of software, and it seems to work ;)

Give me more details, and you'll get clearer answers.

Kind regards
Seref

---

## Post #11 by @pablo

Hi Seref !

> **From:** [Seref Arikan](mailto:serefarikan@kurumsalteknoloji.com)
> **To:** [List for the development team for the reference implementation of openEHRin Java language and technologies.](mailto:ref_impl_java@openehr.org)
> **Sent:** Sunday, June 21, 2009 5:01 PM
> **Subject:** Re: Get an instance of the RM from an Archetype
>
> Hi Pablo,
> I am not sure I can understand your approach clearly. For anyone interested in openEHR, it is vital to understand the differences and roles of different layers/component groups. There is a reason that AOM and RM are expressed differently, and they server different purposes. First of all, AOM is the result of a parsing action, it is the representation of an Archetype, so I can't understand in which context you'd like to have it in a file??

The parsing action you describe is done by parsing an ADL file, I was talking about that file (I'm thinking of something like an ADL file that contains also the definition of the RM structure).

In OOP, this definition is like a class file where I declare fields and I can make instances from it.

For example if you see a domain class defined in GRAILS framework ([http://grails.org/doc/1.1.x/ref/Domain%20Classes/constraints.html](http://grails.org/doc/1.1.x/ref/Domain%20Classes/constraints.html)) tha constraints are defined in the same file (the class definition file) where is defined the class fields.

I just feel that if the definition of the RM structure and the constraints to that structure are done in diferent (ADL, XML, OWL, other) and separated ways (2 or more files), both can be inconsistent (may be a method for syntactic validation is required in the middle to check consistency between what is defined and the constraints over that definition), if you define both things in the same file, the parsing process can include this syntactic checking.

In the other hand I thought of the reusability of an archetype. If I define an RM structure (S) with the archetype (A), I force all other archetypes that have a reference to (A) to use the same RM structure (S). But I see that an archetype suggest a RM structure when it defines constraints, because it must constraint "something", so anyway I have to use the structure suggested by the archetype. So when you reuse an archetype, I think you also reuse the RM structure that is constrained. I don't know if my point is clear here... (sorry for my poor english :P)

I'm just brainstorming, all your tips and points of view are appreciated!

> Here is a tip for you: do not try to invent generic methods, or in other words programmatic shortcuts when using openEHR. A lot of people reading the specs (including me) get the feeling that they can write some sort of code that can work in many dimensions and many cases. Somehow, it creates this illusion. This approach however, always ends up with frustration, since your generic method will start hitting more and more bumps on the way, due to increasing specialization in the leaf nodes of archetypes, in other words, RM types :)

Good tip!
The only generic method I can think of now is the method that validates if the definition of the RM structure and the AOM (in ADL form) that constraints it are consistent. Later, with the ADL parser I can do the half of the job, and with an RM definition parser I can do the complete job.

> Yes, you can write generic code for things like walking on an AOM structure, and some other things, but I can say that IMHO making an openEHR based system work requires you to write a lot of type specific, RM related code. I can't see a magic way of coding to bypass this, and if there is someone out there who is willing to prove me wrong, I would love to hear them.

I don't know if i'm trying this, I think I try to find a simple way to write all the type specific RM code having that "things can change" in mind, so make something that can change quickly with new medical knowledge or new requirements on the system. I also think that we have to write a lot of specific type code, this is the definition of the concepts in ours systems (a lot of concepts!!!)

> So my suggestions are as follows:
> Even if you are going to give a new method a try, start with the simpler approach. Assuming you are going to use Java, take a look at Rong's excellent work in Java reference implementatation, especially check out unit test codes which create RM type instances, they will help you to get an understanding of how RM instances are created, and what they contain etc.

Great, I'll look into those tests.

> Start with this very simple task: read an ADL file, and use Rong's unit test code to create values for the RM types you'll encounter in AOM. Sounds very simple right? Just give it a try, and you'll have an understanding of the differences of main parts.
> If you can continously generalize a piece of code that satisfies your functional requirements, then I don't think anyone can say that what you are doing is wrong. It is just that as you try to add new functionality, your approach may not handle the new cases, so be ready to throw away your code. There is a reason software is called software, it can change!

:) I agree

Regarding what you say about path, value method: it is the method that is used in Opereffa too, all I'm trying to say is, it gets more complicated than single name, value pairs, but the basic idea is usable, at least I've used it to create a piece of software, and it seems to work ;)

I went to the opereffa site but I can't find what you tell me before (to see the relationships between RM, AOM and data) can you help me to find this?

> Give me more details, and you'll get clearer answers.

Great, thank you!

Cheers,
Pablo.

Kind regards
Seref

---

## Post #12 by @pablo

Hi Seref,

I was thinking about what you said when you have zero or more instances of an RM class in some place of the RM structure, I think that with the info in the archetype you cannot make a complete instance of the RM structure, but when you set the data (may be with a path/value approach) I can have the complete structure with all the data inside ready to be validated by the AOM constraints declared on the archetype.

I still think that the <definition> section of the archetype define the RM structure that must be created to hold the data (not completly as we can see in your example), but relatively complete. I now that the <definition> section of the archetype is based on the AOM instead of the RM, but (if I understood the concepts) the AOM is based on the RM in order to constraint it, so with AOM we can have an indirect way to define a RM structure that is mostly complete, and can be completed when we set the data (creating the missing parts of the structure an setting all the data inside this structure).

Any thoughts?

Thank you a lot.

Cheers,
Pablo.

---

## Post #13 by @Seref

Hi Pablo,
AOM is not based on RM. I guess you can call AOM as a processed form of ADL. It is the object based way of representing the ADL (file). So ADL is simply a text file, and AOM is the output of the parser that represents AOM. They both do the same thing, but AOM is created for consuming ADL files (or ADL text stored in a db table) in an object oriented manner.
If you did not have AOM, each ADL parser would return a different parse tree, and this would significantly diminish the reusability of parsers. Here is a very rough summary of the lifecycle (there are other possible flows of course, but this should be valid)

ADL File -----> [Parser] -------> AOM representation in memory ----------> [Some code creates a UI form using AOM] -------------------> UI form -------------------> [Data Entry by user] ------------------------> [Some code creates RM class instances using data from UI (which was created by AOM in the first place)] ----------------------------> [Some code saves values of RM classes, with a link to original archeytpe]

In short do not see AOM something other than the ADL, it is just ADL for the machines.
In case someone thinks this is not clear enough or wrong, please correct me, so that I don't misguide anyone.

All the best
Seref

---

## Post #14 by @pablo

Hi Seref,

Yes, you're right and only the datatypes have a correspondence with the AOM (the C_XXXX classes).

I understand the relation beetween ADL and AOM.

Now, if we see some ADL (I've downloaded all the archetypes from the SVN) they are archetypes defined for: cluster, composition, entry, section and structure (all RM classes).

Inside them, all have references to the RM classes in the "definition" section. I understand that the definition is parsed to an AOM structure, but is defined in terms of an RM structure:

A classic (blood presure):

Here we have an RM structure: OBSERVATION > HISTORY > EVENT > ITEM_LIST > ELEMENT
And only the leafs are AOM: C_DV_QUANTITY.

definition
OBSERVATION[at0000] matches { -- Blood pressure
data matches {
HISTORY[at0001] matches { -- history
events cardinality matches {1..*; unordered} matches {
EVENT[at0006] occurrences matches {0..*} matches { -- any event
data matches {
ITEM_LIST[at0003] matches { -- blood pressure
items cardinality matches {0..*; ordered} matches {
ELEMENT[at0004] occurrences matches {0..1} matches { -- systolic
value matches {
C_DV_QUANTITY <
property = <[openehr::125]>
list = <
["1"] = <
units = <"mm[Hg]">
magnitude = <|0.0..<1000.0|>
precision = <|0|>
>
>
>
}
...

So I think, if we need to get the AOM we parse the archetype with the current ADL parser, but if we need an RM instance, we can parse the structure OBSERVATION > HISTORY > EVENT > ITEM_LIST > ELEMENT to instance the RM, and instead of a C_DV_QUANTITY instance (the same for al the C_XXXXX leafs) we use datatypes of the RM, here we use DV_QUANTITY. So, this is another parser but is using the same archetype as input.

If I'm right (I don't know, here I'm just brainstorming) it's not necesary to define other metadata than the archetype to have an instance of the RM in memory.

If I follow your example but I see things a bit different:

ADL File
-----> [Parse2AOM]
-----> AOM representation in memory
-----> [Parse2RM]
-----> RM representation in memory

-----> [Some code creates a UI form using RM] (I think the UI must be created from RM instead of AOM because the values entered by user must be saved on a RM instance)
-----> UI form
-----> [Data Entry by user]

------> [Fill structure with data entered]
------> [Validate RM against it's archetype constraints]
------> If the data is OK, Save the RM instance with a link to the original archetype.

What do you think? Is it a possible way to do things right?

Thanks a lot!
Pablo Pazos Gutiérrez.

---

## Post #15 by @Seref

Hi Pablo,
There is no second parser. When you parse the AOM, you have all that you need to create the RM instance, except data. An AOM object tells you what is RM type of the node it represents. So in AOM, objects have a property named RMTypeName. For example an AOM node that describes a C_DV_QUANTITY, has DV_QUANTITY in its RMType property.
So whatever you want to do around RM instances, like creating instances of them or assigning values to them, you do it with the guidance of AOM. Operffa source code contains implementations of everything we have discussed so far. I suggest downloading it and taking a look at it.

Kind regards
Seref

---

## Post #16 by @pablo

Great!

Let's make some RM!

Cheers,
Pablo.

---

## Post #17 by @pablo

Hi Seref,

I've downloaded the Opereffa source but I don't know where I must look for the code to create RM instantes, can you give me some "entry points" to the source code?

Thank you!
Pablo.

---


**Canonical:** https://discourse.openehr.org/t/get-an-instance-of-the-rm-from-an-archetype/14902
**Original content:** https://discourse.openehr.org/t/get-an-instance-of-the-rm-from-an-archetype/14902