Information model meta model

From Discovery Data Service
Jump to navigation Jump to search

Scope of the meta model

The model meta model consists of a set of specialised classes or 'shapes', made interoperable via the use of the semantic web languages, which use RDF grammar and syntax.

The shapes cover the following areas:

  1. An ontology of terminology concepts, which is a vocabulary and definitions of the concepts used in healthcare, or more simply put, a vocabulary of health. The ontology is made up of the world's leading ontology Snomed-CT, with a London extension and supplemented with additional concepts for data modelling. Whether concepts or Snomed-CT concepts, or the London extension, or any legacy code based concept (e.g. ICD10 or EMIS local codes or Read codes), the class structure is the same.
  2. A data model, which is a set of classes and properties, using the vocabulary, that represent the data and relationships as published by live systems that have published data to a data service that uses these models. The data model is part of the overall ontology and there is seamless boundary between the data model shapes and the terminology concepts, as both use RDF. The data model meta model uses SHACL shapes and thus conforms to the W3C SHACL recommendation.
  3. A library of business specific concept and value sets, which are expression constraints on the ontology for the purpose of query. This uses a specialised "query" or "set definition" class, and encompasses the Snomed-CT expression constraint language with which it is compatible, using a simple translation API
  4. A catalogue of reference data such as geographical areas, organisations and people derived and updated from public resources.
  5. A library of Queries for querying and extracting instance data from reference data or health records. This uses a more extended class model than 3) but fundamentally is a set definition which is mapped to mainstream query languages to get actual data.
  6. A set of maps creating mappings between published concepts and the core ontology as well as structural mappings between submitted data and the data model. This uses a context class.
  7. A set of form generators that are used by the IM application to create forms for the creation and editing of the IM entities which are instances of a meta model class.


General approach

The information model language uses RDF triples as its basic grammar i.e. subject, predicate, and object with graph making up quadruples of an RDF data set.

Thus, RDF is used for the meta model and the W3C language used for the metal model is SHACL. In other words, SHACL is used to define all the meta classes, and the meta classes are used to hold the instances which are the content of the model.

The paradox of the information model content is that the instances of the meta model classes are themselves considered classes in the real world. For example when noting that a patient has 'chest pain' this is recorded as a concept which is an instance of the concept model. But 'chest pain' is also the class of all chest pains, so the same identifiers can be used for subsumption query. Likewise a clinical event in a health record is an instance of a data model meta class, but the clinical event is also a class of all clinical events!

The model itself can be exchanged in JSON-LD, but JSON-LD can be somewhat tedious (as RDF predicates cannot directly map to standard programming language class properties) , so the use of 'local names' for business related APIs (e.g. query) is supported. In this case the JSON field names can use the local names without the full IRI, as long as the JSON complies with the model classes as described here.

Consequently, in order to make the documentation clearer, local names are used in this documentation also with links to the IM viewer or W3C equivalent.

This documentation is auto generated from the information model folders and shapes themselves, and thus the shapes can also be viewed more fully in the Information Model Directory viewing application

Types and shapes

Types (as represented as the value of the rdf: type predicate), are used to indicate the structure of an object in the model. Thus each meta model class is marked as an RDF TYPE.

Shapes are made up of SHACL node shapes and property shapes. A 'type' is defined in the form of a shape.

Shapes are also classes (i.e. also are rdf:type -> rdf:Class), so that any shape that is a subclass of another shape inherits its properties unless overridden by sub properties, or subclass values of the parent properties.




Basic shapes

These shapes are the meta classes of the named entities within the information model.

IrirRef

A reference to resource with an iri and optional name to enable readability

Property Card. Value type Description
name 1..1 xsd:string The name of the entity
Example
{"@id" : "sn:29857009", "name" : "Chest pain (finding)"}

Entity shape

Defines the target class : org.endeavourhealth.imapi.model.tripletree.TTEntity@2ee92e7d The super class and data model for all named resources in the model i.e. the data model of the entities that are labelled with iri label and status

Property Card. Value type Description
label 1..1 xsd:string The preferred full name of the entity
type 1..1 rdfs:Resource The base type of the entity i.e. one of the high level entity types
comment 0..1 xsd:string The description of the entity
status 1..1 im:Status The status of the entity being active, inactive, draft or unassigned
scheme 1..1 im:Graph The code scheme or graph which the entity belongs to
subClassOf 0..* im:EntityShape An entity that this entity inherits from, both semantically and structurally, this is also used for sub properties as properties are classes of properties

IriAlias

Is a subtype of IrirRef

An IRI with a name and an optional alias and a variable name when the iri is passed in as an argument (e.g. $this

Property Card. Value type Description
alias 0..1 xsd:string The column name in a select clause for this property, or a variable used to reference the result set of the values matched
variable 0..1 xsd:string The name of a variable, passed as an argument to the query, which is resolved to the IRI
inverse 0..1 xsd:boolean When used as a property, whether this is an inverse object property i.e. an inbound connection to this entity
includeSubtypes 0..1 xsd:boolean When used in a with or where clause, whether to include the subtypes of this entity
includeSupertypes 0..1 xsd:boolean When used in a with or where clause, whether to include the supertypes of this entity e.g. when ascending a hierrchy to look for a property

Property shape

Defines the target class : null

Is a subtype of Entity shape

data model for properties

Property Card. Value type Description
inverseOf 0..* rdf:Property A property that this property is an inverse of
domain 0..* rdfs:Class The classes or concepts that may have this property as a property, or a role, or a role within a role group
range 0..* Class the type of value for this property.

Query Model and Set definition shapes

These shapes form the model for defining sets (also known as query definitions) for retrieving data from the IM or health records.

Query /Set shape

Defines the target class : org.endeavourhealth.imapi.model.tripletree.TTEntity@42a7d9ef

Is a subtype of Entity shape

A query that is stored as an entity in a query library

Property Card. Value type Description
definition 0..1 QueryDefinition The query definition itself

Query /Set definition

Is a subtype of IriAlias

A set definition holding the logical definition of a set. Usually referred to as a Query as these are used to retrieve data.
Includes most of the main logical query constructs used in mainstream query languages, thus is a constrained version of mainstream languages that is schema independent.

Property Card. Value type Description
description 0..1 xsd:string Optional description of the query definition for support purposes.
from 0..* FromClause The base cohort/ set or type, or instance on which all the subsequent where or filter clauses operate. If more than one this is treated as an OR list.
where 0..1 WhereClause Tests properties and property paths and applies filters. Equivalent to SQL Join/ Where and SPARQL Where
Bollean where clauses supported.
select 1..1 SelectClause Select query clause logically similar to SQL/SPARQL select but with GraphQL nesting ability
groupBy 0..* IriAlias If the results need to be grouped, the grouping properties.
orderBy 0..* IriAlias Ordering of instances via a property value returned.
direction 0..1 xsd:string direction of ordering (DESC or ASC) .
limit 0..1 xsd:integer Number of entities to return. Normally used with order by
subQuery 0..* QueryDefinition SubQueries used to group columns in multi group reports. The sub queries are all subsets of the main query clauses
prefix 0..0 PrefixShape list of prefix to namespace expansion to enable readability of iris
usePrefixes 0..1 xsd:boolean true if you want the results to use IRI prefixes
activeOnly 0..1 xsd:boolean Whether only active entities are included in the match clauses or select clauses

From clause

Is a subtype of IriAlias

A clause defining a base set , or a base type(s), or an object instance, on which the where clause operates.
Set the alias if derived from a result set in the same query. Set the iri if derived from an external result. by default the iri refers to an instance. For querying instances of a type set the is type property as true and for a base cohort, set isSet as true

Property Card. Value type Description
or
1..1
isType 0..1 xsd:boolean If the query results are derived from instances of certain type (or types) then set this flag to true.

isSet

0..1 xsd:boolean If the query results derived the result set of a concept set, value set or query result then set this flag to true.

WhereClause

A clause containing criteria which the objects must conform to. Equivalent to a from/join where clause in SQL and where/filter in sparql.
Supports graph traversal filtering and inference for subsumption query

Property Card. Value type Description
alias 0..1 xsd:string Used to define the clause with a readable term and also used in other clauses for further refinement
description 0..1 xsd:string Optional description for clause
from 0..* FromClause Refers to the alias of another where clause to indicate the set of objects defined by the referenced clause, which will be further refined by this where clause.
Equivalent to accessing a temporary or derived table in SQL.
Also used to refer to an instance object, or instances of a certain type, or external result set (e.g. a base cohort population)
If more than one it is considered an OR List
graph 0..1 im:Graph The iri of a graph if the query is limited to a particular data set
path 0..1 rdfs:Resource A property path made up of space delimited iri strings, from the outer entity to the entity on which this clause operates.
Equivalent to an inner join in SQL
notExist 0..1 WhereClause Points to a nested where clause. If the nested clause returns results then the entity referenced by the outer where clause is excluded.
In other words, for the outer entity to be included, the nested entity must have no results. This contrasts with 'not'
or 2..* WhereClause Boolean operator OR on subclauses
and 2..* WhereClause Boolean operator AND on subclauses
property 0..* IriAlias a property tgo test. Note that this is applied to the entity after the path has been resolved.
in 0..* IriRef Whether the value is in this list of sets or concepts (including any sub types)
is 0..* IriAlias Whether the value is this concept (and optionally if set to include sub or supertypes)
not 0..1 xsd:boolean Testing for the value as a not. Note that this filters out the instances but does not exclude the outer entity (see not exist)
function 1..1 FunctionClause A function that operates on the property value (and other parameters) prior to a compare or range or inclusion test. For example a time difference function operating on the date and a reference date.
Note that properties that ARE functions do not need functions included for example age. For these simply supply the arguments.
argument 0..1 Argument Arguments to pass into a function when the property is a function property.
Note that if the test is a function then the argument list would be in the function clause
value 1..1 ValueClause If testing a property value as equal greater than ete. use compare
range 1..1 RangeClause Test foe a value being between two absolute or relative values
where 1..1 WhereClause A chained where clause operating on the property value object.
Equivalent to a join in SQL or '.' in sparql
orderBy 0..* IriAlias Ordering of instances via a property value in order to further test in another where clause.
direction 0..1 xsd:string direction of ordering (DESC or ASC) .
limit 0..1 xsd:integer Number of entities to return. Normally used with order by

SelectClause

Defines the objects and properties to retrieve from a graph, subject to a mach clause. Supports graphql type nesting and sub selects for column groups

Property Card. Value type Description
count 0..1 xsd:boolean If the query result is simply a sum of the main entities found. equivalent to COUNT(id)
path 0..1 rdfs:Resource A property path made up of space delimited iri strings, from the outer entity to the entity on which this clause operates.
Shortcut for nested selects
property 1..1 IriAlias Information about a property or field to include in the results. Property select supports nesting with selects for the objects that may be values of the property
select 0..* SelectClause Nested select property clauses from the objects that are values of this select's property Note that if the value is null then this select would be absent
where 0..* WhereClause Nested where clause operating on the values of this select's property
Enables multi- level filtering as used in JOIN where clauses in SQL
or
0..1
sum 0..1 xsd:boolean Whether the result is a summation of this property's values

average

0..1 xsd:boolean Whether the result is an average of this property's values

max

0..1 xsd:boolean Whether the result is the maximum of this property's values
function 0..1 im:Function The iri of a function indicating that the result is the result of a function operating on the property values, and any arguments passed in
argument 0..* Argument Arguments to pass into the function

Prefix shape

The model of a class containing an iri prefix map

Property Card. Value type Description
prefix 1..1 xsd:string Prefixe used in the rest of the document
iri 1..1 xsd:string The iri or namespace or graph iri this prefix refers to

FunctionClause

Is a subtype of IrirRef

A function used in a query consisting of the function iri and one or more arguments to pass in at run time

Property Card. Value type Description
argument 0..* Argument Arguments to pass into the function. They should match the parameter definitions of the function

Argument

A named parameter and a value for passing into a function

Property Card. Value type Description
parameter 1..1 xsd:string Parameter name for a function or the parameter name for an argument
or
1..1
valueData 1..1 xsd:string Value that is a literal such as a string or number

valueVariable

1..1 xsd:string argument value which is a variable name to be resolved at run time
valueFrom 1..1 xsd:string Passes in the result set from a previous where clause

ValueClause

Tests a value, whether equal, greater than, less than etc. optionally including a value to compare against

Property Card. Value type Description
<span title="Comparison operators : =, <, <=, >, >=">comparison 1..1 xsd:string Comparison operators : =, <, <=, >, >=
value 1..1 xsd:string The value of the property used in a test. This is a string which will be cast to a number or date, depending on the data type of the property value
relativeTo 0..1 CompareClause The result to compare the property value against is derived from a variable value or property of an object (identified by its alias) defined another where clause

RangeClause

A range for use in property value testing

Property Card. Value type Description
from 1..1 ValueClause The value comparison for lower end of the range
to 1..1 ValueClause The value comparison of upper end of the range
relativeTo 1..1 CompareClause When the range values are relative to another value , information about the other value (e.g. variable or property of the results defined in another clause

CompareClause

null

Property Card. Value type Description
alias 0..1 xsd:string The alias of the result set from another where clause
property 0..1 IriAlias The property of the objects in the result set (as indicated by the alias) to test
variable 0..1 xsd:string If a value is being compared against a variable passed in as an argument, the name of the variable

FunctionShape

Defines the target class : org.endeavourhealth.imapi.model.tripletree.TTEntity@265b317b

Is a subtype of Entity shape

null

Property Card. Value type Description
parameter 0..* Parameter A list of parameters and data types used in this function

Parameter

null

Property Card. Value type Description
label 1..1 xsd:string The name of the parameter
or
1..1
datatype 1..1 rdfs:Resource The iri of The data type of the parameter when the data type is a literal

class

1..1 rdfs:Resource The iri of the class of the parameter when the argument is an object

PathQueryShape

Defines the target class : null A query that returns a set pf paths between a source and target entity, traversing to a certain level

Property Card. Value type Description
source 1..1 IriRef the source entity at the start of the path.
target 1..1 IriRef the target entity at the end of the path.
depth 0..1 xsd:integer How many hops to be taken in the graph between source and target

Set shape

Defines the target class : org.endeavourhealth.imapi.model.tripletree.TTEntity@63ecb53e

Is a subtype of Query /Set shape

data model for concept sets and value sets

Property Card. Value type Description
hasMember 0..* im:Concept The flat list of leaf concepts when generated from the definition, or for many national sets, simple list of concepts

Data Model shapes

These shapes are the meta classes of the data modelling entities within the information model.

Data model shape

Defines the target class : null

Is a subtype of Entity shape

The meta class for a data model type, using a SHACL node shape for both definition and validation

Property Card. Value type Description
property 0..* PropertyNodeShape The list of properties for this shape

PropertyNodeShape

Is a subtype of Entity shape

The data model of a shacl node shape describing a property of a data model entity

Property Card. Value type Description
path 1..1 rdf:Property The iri of the property
minCount 0..1 xsd:integer Minimum cardinality,if null assuming any number including zero
maxCount 0..1 xsd:integer The maximum number allowed. If null then any number
or
1..1
class 1..1 rdfs:Resource The iri for the class range of the property. The range of this property is a subclass of this class

datatype

1..1 rdfs:Resource The range of the property is a data type of this type

node

1..1 rdfs:Resource The property points to a node shape
comment 0..1 xsd:string Description of the property
name 0..1 xsd:string The name of the property used for ease of recognition
order 0..1 xsd:integer The property order for display
inheritedFrom 0..1 NodeShape The shape that this property is inherited from (used in the inferred instance of the information model

Concept shapes

These shapes are the meta classes of the terminology concepts used within the information model.

Concept shape

Defines the target class : org.endeavourhealth.imapi.model.tripletree.TTEntity@4dca9fd

Is a subtype of Entity shape

data model for terminology concepts

Property Card. Value type Description
code 1..1 xsd:string The code for this concept, which may be a local code if local concept, or a core code such as a snomed identifier
hasTermCode 0..* TermCodeShape Alternative terms or synonyms for this concept. A term may also have a description id.
weighting 0..1 xsd:integer A number indicating a weighting for this concept which can be used in free text search
definitionalStatus 0..1 im:VSET_Definitionalstatus Indicates the authoring status of this concept, whether necessary only, or both necessary and sufficient. OWL would use Equivalent class axiom to indicate this.
hasMap 0..* xsd:string Any backward maps from core to legacy. This is limited to complex maps rather than simple matches and are 'backward' matches not suitable for automatic inclusion in subsumption queries
usageTotal 0..1 xsd:integer The approximate number of times this concept has been used in around 1 million primary care and acute care records
im1Id 0..1 xsd:string pointer the original identifer in IM1
matchedTo 0..* im:VSET_Unspecified For a legacy concept, one or more concept this concept matches to. A query for the matched to concepts would entail this concept normally, but NOT the children of this concept
sourceContext 0..* SourceContextShape The source context object for this concept indicating the system, table, field and organisation that published this legacy concept
370124000 0..* im:Concept Indicates the concepts that this concept has been replaced by
isChildOf 0..* im:Concept points to the parent legacy concept that this concept is in. Note that it may or may not be a true subtype. Reflects the original taxonomy

Term code shape

data model for a term code

Property Card. Value type Description
label 0..* xsd:string The term or synonym for the concept
code 0..* xsd:string Descriptionid or code for this particular term
status 0..* im:Status The status of this particular term code, may be active or inactive

Source context shape

Is a subtype of Entity shape

Data model for source context for a concept e.g. source system, field etc

Property Card. Value type Description
sourceSystem 1..* im:ComputerSystem the name of the system that was responsible for sending the message or extract, usually referring to the health care record system
sourcePublisher 1..* im:Organisation The organisation (usually a provider) that was the source of this message or extract
sourceSchema 1..* xsd:string The schema or data set or other identifier that identifies the format of this extract
sourceTable 1..* xsd:string If a table or message the name of the source table or source message type
sourceField 1..* xsd:string The source field containing this data item
sourceRegex 1..* xsd:string In the case of text, the nature of a regex expression or nlp algorithm used to parse the source text
sourceHeading 1..* xsd:string For an item that depends on the context in which it appears, the heading which provides context
sourceText 1..* xsd:string Source text or term for coded or non coded data
sourceValue 1..* xsd:string The value or code for this concept. Note that a scheme for the code can be inferred from the other context information. In the event of a scheme/code pair, use different fields in the source context

Refined concept shape

Is a subtype of Concept shape

A concept with role groups with roles

Property Card. Value type Description
roleGroup 0..* RoleGroupShape Zero or many role groups, each group containing one or more roles. These represent constraints on the super types i.e. more specific. Generated by inference making sure to remove duplicate properties or super properties.

Role group shape

data model for a role group

Property Card. Value type Description
Property 0..* im:Concept The concept identifier of the concept that is the role. Role Groups are unique in that their properties are any properties from an ontology,usually concepts

Transactional shapes

These shapes form the meta classes for structures pass into APIs for query of, or filing into, the model or health records.

EntityFileTransaction

Is a subtype of Entity shape

An entity with the additional CRUD indicators to enable deletes updates, adding quads etc

Property Card. Value type Description
crud 1..1 im:CrudOperation Indicates the nature of the CRUD transaction which must be one of im:DeleteAll, im:AddQuads (adds in additional triples), im:UpdateAll (replaces all the predicates for this entity in the graph with te ones submitted), im:UpdatePredicates ( replaces all the objects of these submitted predicates for this graph
graph 1..1 im:Graph The graph to which these triples apply.
This means you can add predicates to any entity without affecting the original authored entity, those predicates belonging only to this module or graph

EntityDocument

A document containing any number of triples to file as a batch.
Note that if the document is sent as Json-LD with prefixed iris, a @context object will be required

Property Card. Value type Description
crud 1..1 im:CrudOperation Indicates the nature of the default CRUD transaction for entities in thisdocument. Thes can be overridden in each entity. Must be one of: im:DeleteAll, im:AddQuads (adds in additional triples), im:UpdateAll (replaces all the predicates for this entity in the graph with te ones submitted), im:UpdatePredicates ( replaces all the objects of these submitted predicates for this graph
graph 1..1 im:Graph The graph to which these entities apply by default.
This may be overridden by the entities
This means you can add predicates to any entity without affecting the original authored entity, those predicates belonging only to this module or graph
entities 1..* EntityShape Set of entities to file. If the entities do not have crud or graphs oftheir own then the default from the document are used

Query Request

A request for data sent as a body (json in local name format) to the /queryIM API.
Contains a query as an iri or inline query with run time variable values as arguments for use in the query

Property Card. Value type Description
name 0..1 xsd:string optional name for debugging purposes. Is not used in the query process
page 0..1 PageInformation optional page number and size if the client is looking for paged results
textSearch 0..1 xsd:string If a free text search is part of the query
argument 0..* Argument arguments to pass in to the query as parameters. Parameter name and value pairs. Values ,may be strings, numbers or IRIs
or
1..1
query 1..1 QueryDefinition The requested query, either by iri reference or inline definition If the query is already defined, use the queryIri. Arguments may be used in eoither approach
referenceDate 0..1 im:DateTime reference date for date ranges that use reference date. (Note that it could be passed in as an argument)

PageInformation

Information about paging if the client wishes to page results, including page number and page size

Property Card. Value type Description
pageNumber 1..1 xsd:integer Page number (starting at 1)
pageSize 1..1 xsd:integer number of entries per page