Language grammar and syntax

From Discovery Data Service
Jump to navigation Jump to search

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.

The preferred exchange format is JSON-LD which is json with the @context to handle iri prefixes and @id for indicating RDF IRIs.

The grammar is based on the main stream language RDFS including a profile of SHACL for shape building and ECL in RDF form for Expression constraints.

The information manager supports OWL EL inputs which are out through a reasoner to generate inferred RDFS and removing the OWL. In other words the information model run time is a fully inferred ontology.

The IM also includes a query language DSL for the purposes of logical query definition, which is mapped by the IM to the relevant SPARQL, SQL or OpenSearch syntax for running on live data. The purpose and rationale for the DSL is more full described in the information model query
article and is able to represent all main stream health care queries that generate data sets, but stops short of the data manipulation used by Tableau, Power BI etc.

The use of 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 tis case the JSON field names can use the local names without the full IRI, as long as the JSON complies with the language grammar 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 a data class or language grammar (as long as the language conforms to a JSON or triple structure)..

A special type of 'Shape' (as represented as an entity with rdf:type -> shacl:NodeShape) define the properties of a type. Thus a shape is targeted at a type or class.

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.

Shapes are in effect Closed world interpretation of classes.

This documentation is therefore a documentation of shapes.

Basic shapes

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

Shape Property Card. Value type Comment
IriRef A resource with an iri and name
label 1..1 xsd:string The name of the entity
Entity
(subtype of IrirRef)
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
comment 0..1 xsd:string The description of the entity
type 1..1 rdfs:Resource The base type of the entity i.e. one of the high level entity types
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
IriAlias
(subtype of IrirRef)
An IRI with a name and an alias (for use as variables for reference
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
Property
(subtype of Entity shape)
data model for properties
subClassOf 0..* im:Concept
inverseOf 0..* rdf:Property
domain 0..* rdfs:Class
range 0..* Class
Class
(subtype of Resource)
The class of classes.
Resource The class resource, everything in RDF/OWL/SHACL/RDFS.

Query language shapes

These shapes form the query language DSL for retrieving data from the IM or health records.

Shape Property Card. Value type Comment
Query
(subtype of Entity shape)
A query that is stored as an entity in a query library
query 0..1 QueryDefinition The query definition itself
QueryDefinition
(subtype of ClauseHeading)
A Query definition holding the logical definition of a query in a standard language
resultFormat 0..1 xsd:string Whether the result set is required flat select style json or a nested graphql json object style 'RELATIONAL' or 'OBJECT. Default is OBJECT
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
or
1..1
select 1..1 SelectClause Select query clause logically similar to SQL/SPARQL select but with GraphQL nesting ability

ask

0..1 MatchClause If the query is a boolean true or false use match clauses as an ask
mainEntity 0..1 sh:NodeShape The main entity to which all matches must be related e.g. Patient or organisation. i.e. the IRI of a data model entity (SHACL shape)
ClauseHeading
(subtype of Entity shape)
General headings such as name description and alias
alias 1..1 xsd:string An alias or reference term that can be used throughout a query as shorthand for the result set
SelectClause
(subtype of ClauseHeading)
Defines the objects and properties to retrieve from a graph, subject to a mach clause. Supports graphql type nesting and subselsects for column groups
count 0..1 xsd:boolean If the query result is simply a sum of the main entities found. equivalent to COUNT(id)
or
0..1
property 1..* PropertySelectClause Information about a property or field to includein the results. Property select supports nesting with selects for the objects that may be values of the property

pathToTarget

1..1 PathTargetClause Special function for path query. Information about the target entity when the query is looking to return paths between a source and a target. Both are likely to be passed in as parameters
match 0..* MatchClause The match pattern to which the select clause must comply. Equivalent to a where/filter in SPARQL and JOIN/WHERE in SQL
distinct 0..1 xsd:boolean Whether the entity objects returned should be distinct
or
0..1
entityType 1..1 ConceptReference The entity type for instances this select clause operates on. Options include including subtypes.

entityId

1..1 ConceptReference An instance of an enttu for which this select clause operates. As in entity type, optionally to include subtypes, where the entity id is a concept

entityIn

1..1 rdfs:Resource The consept set, value set, or query result set that forms the base population of instances on which the select clause operates. e.g. a parent cohort.
groupBy 0..* PropertySelectClause If the results need to be grouped, the grouping properties.
orderLimit 0..* OrderLimitClause Ordering of instances via a property value and limiting th enumber returned.
subselect 0..* SelectClause For a query with column groups such as a list report, the select query for each group
MatchClause
(subtype of ClauseHeading)
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
pathTo 0..1 rdfs:Resource A convenient way of traversing properties and objects to get to the match object, avoiding excessive nesting.
The properties are listed and thus traversed in strict order
or
0..1
or 2..* MatchClause Boolean operator OR on subclauses

and

2..* MatchClause Boolean operator AND on subclauses
or
0..1
entityType 1..1 ConceptReference The entity type that matched instances must be (including subtypes). Options include including subtypes.

entityId

1..1 ConceptReference An instance of an entitu for which this match clause operates on. As in entity type, optionally to include subtypes, where the entity id is a concept
or
0..1
entityInSet 1..1 rdfs:Resource The concept set, value set, or query result set that the instances must be in to match.
on which the select clause operates. e.g. a parent cohort.

entityNotInSet

1..1 rdfs:Resource The concept set, value set, or query result set that the instances must NOT be in to match.
on which the select clause operates. e.g. a parent cohort.
graph 0..1 im:Graph The iri of a graph if the query is limied to a particular data set
property 0..* PropertyValueClause Properties and their values required to match (or not match), including any nesting of objects (joins).
The default assumption is the AND operator on the properties. Use orProperty for or operator
orProperty 2..* PropertyValueClause Properties and their values one of which is required to match (or not match), including any nesting of objects (joins).
notExist 0..1 xsd:boolean Negation indicator for this entire clause. i.e. for the instance to be included it must NOT match.
orderLimit 0..1 OrderLimitClause Ability to order and limit the match before the select or matchstatement operates.
Crucially, this is processed before the application of a test or check, enabling things like latest or earliest, max or min
testProperty 0..* PropertyValueClause Further test applied to the result of an ordered limited match.
The rest of the match clause then becomes a sub select query on which these tests operate. Implicit operator is AND
displayText 0..1 xsd:string Optional text for display in query viewer if dfferent from the match clause name
PropertySelectClause
(subtype of ConceptReference)
null
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
select 0..1 SelectClause Nested select clause for graphql style results format
inverseOf 0..1 xsd:boolean Indicates if true that the selected property is an inverse relationship with the target object
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
PathTargetClause
(subtype of IrirRef)
Information about the target of a path query, including the IRI of the target and the number of hops processed.
depth 0..1 xsd:integer How many hops to be taken in the graph between source and target
ConceptReference
(subtype of IriAlias)
null
includeSubtypes 0..1 xsd:boolean Whether to include the subtypes of the entites selected or matched
includeSupertypes 0..1 xsd:boolean Whether to include the supertypes of the entity in a match clause. Used for ascending the hierarch to look for properties inherited
excludeSelf 0..1 xsd:boolean Whether to exclude this entity when either include supbtypes or include suprtypes is set. Rarely used but sometimes found in ECL definitions
OrderLimitClause Orders the value of the property (property as represented by the iri and alias)
orderBy 1..1 IriAlias The property or property variable to order the results by
direction 1..1 xsd:string ASCENDING or DESCENDING to indicate the order direction
limit 0..1 xsd:integer The count of instances to return after ordering
PropertyValueClause
(subtype of ConceptReference)
A property (as a concept reference) and value filter supporting ranges sets and functions,
As a result of the concept references, supports sub properties as well as inferred values
pathTo 0..1 rdfs:Resource A convenient way of traversing properties and objects to get to a property, avoiding excessive nesting.
The properties are listed and thus traversed in strict order
inverseOf 0..1 xsd:boolean Tests the property as an inverse property (inbound relationship)
notExist 0..1 xsd:boolean The property match must not exist. This is negatation at a more granular level than the match clause.
For example to test for a null field or absent property
optional 0..1 xsd:boolean Optional match for this property, used to enable IF a present then A must have X,Y.
N.B for SPARQL experts the OPTIONAL is generally generated automatically from SELECT, so optional need only be set when a test is to be applied to a linked object
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
or
0..1
value 1..1 CompareClause If testing a property value as equal greater than ete. use compare

inSet

1..* ConceptReference The value of the property must be in the concept set IRI.
For teesting simple lists or single concepts use isConcept

notInSet

1..* ConceptReference The value of the property must NOT be in the concept set IRI.
Note that this is not negation of the entire match, only the negation of this entry instance when tested. Equivalent to SPARQL filter not in.
For testing simple lists of concepts use isNotConcept

isConcept

1..* ConceptReference The value of the property be this concept (and otionally its sub types).
Used for inline sets or single concepts

isNotConcept

1..* ConceptReference The value of the property must NOT be this concept (and otionally its sub types).
Used for inline sets or single concepts.
Note that this is not negation of the entire match, only the negation of this entry instance when tested. Equivalent to SPARQL filter not in.

inRange

1..1 RangeClause Test foe a value being between two absolute or relative values

valueMatch

1..1 MatchClause The match clause operating on the property value object.
Equivalent to a join in SQL or '.' in sparql
displayText 0..1 xsd:string Optional text for display in query viewer if dfferent from the match clause name
Argument A named parameter and a value for passing into a function
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 Vaue 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

valueSelect

1..1 SelectClause Argument value that is the result of a select query

valueIri

1..1 im:IriRef Argument value that is an iri
FunctionClause
(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
argument 0..* Argument Arguments to pass into the function. They should match the parameter definitions of the function
CompareClause Tests a value, whether equal, greater than, less than etc.
comparison 1..1 xsd:string Comparison operators : EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, NOT_EQUAL
or
1..1
valueData 1..1 xsd:string The value to compare against. This is a string which will be cast to a number or date, depending on the data type of the property value

valueVariable

1..1 xsd:string The variable (alias) to compare against. The variable may be an argument to the query (e.g. $reference date or an alias in this query or another query. Use the $ prefix to make it clear

valueSelect

1..1 SelectClause The result to compare the property value against is derived from a select sub query
RangeClause A range for use in property value testing
from 1..1 CompareClause The value comparison for lower end of the range
to 1..1 CompareClause The value comparison of upper end of the range
Function
(subtype of Entity shape)
null
parameter 0..* Parameter A list of parameters and data types used in this function
Parameter null
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

Data Model shapes

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

Shape Property Card. Value type Comment
NodeShape
(subtype of Entity shape)
The meta class for a data model type, using a SHACL node shape for both definition and validation
property 0..* PropertyNodeShape
PropertyNodeShape
(subtype of Entity shape)
The data model of a shacl node shape describing a property of a data model entity
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

Concept shapes

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

Shape Property Card. Value type Comment
Concept
(subtype of Entity shape)
data model for terminology concepts
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
TermCodeShape data model for a term code
label 0..* xsd:string
code 0..* xsd:string
status 0..* im:Status
SourceContextShape
(subtype of Entity shape)
Data model for source context for a concept e.g. source system, field etc
sourceSystem 1..* im:ComputerSystem
sourcePublisher 1..* im:Organisation
sourceSchema 1..* xsd:string
sourceTable 1..* xsd:string
sourceField 1..* xsd:string
sourceRegex 1..* xsd:string
sourceHeading 1..* xsd:string
sourceText 1..* xsd:string
sourceValue 1..* xsd:string
RefinedConceptShape
(subtype of Concept shape)
A concept with role groups with roles
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.
RoleGroupShape data model for a role group
Property 0..* im:Concept
ConceptPropertyShape
(subtype of Property shape)
A concept that is a role in another concept and as a property may have domains and ranges
ConceptSet
(subtype of Entity shape)
data model for concept sets and value sets
definition 0..1 QueryShape A definition of set content using the subset of the query language that aligns to Expression constraint language
hasMember 0..* im:Concept The flat list of leaf concepts when generated from the definition, or for many national sets, simple list of concepts
hasTermCode 0..* TermCodeShape

Transactional shapes

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

Shape Property Card. Value type Comment
EntityFileTransaction
(subtype of Entity shape)
An entity with the additional CRUD indicators to enable deletes updates, adding quads etc
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
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
QueryRequest A request for data sent as a body (json in local name format) to the /queryIM API.
Contains either a query or query iri with run time variable values for use in the query
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 query definition for an inline dynamic query. If the query is already defined, use the queryIri. Arguments may be used in eoither approach

queryIri

1..1 im:Query The IRI of a predefined query in the information model. i.e. request the system to run query X
referenceDate 0..1 im:DateTime reference date for date ranges that use reference date. Note that it could be passed in as an argeument
PageInformation Information about paging if the client wishes to page results, including page number and page size
pageNumber 1..1 xsd:integer Page number (starting at 1)
pageSize 1..1 xsd:integer number of entries per page