DocumentationSupportCosta Rica · Contact
What the service is for

Interoperability rarely fails in transport: it fails in the model.

When two systems fail to understand each other, it is almost never because the message did not arrive. It is because each stores the same clinical fact differently: a free-text field where the other has a code, a homegrown diagnosis table, a date that is sometimes the collection date and sometimes the report date, an identifier that repeats across facilities. Standardizing the exchange without sorting out the model only moves the problem one layer up. This service works where the problem starts: we analyze the current model, review its design, agree on how far the scope reaches and propose a target model with the terminologies, normalization rules and migration plan needed to get there.

Layers

A data model is decided across five layers

All five exist whether or not anyone decided them. When one is skipped, the decision still gets made — by whoever is writing the code at that moment, with no record of it.

Governance

What gets decided here

Who owns each data point, who approves a model change, how often it is versioned and how a decision is documented so it still makes sense three years from now.

What breaks when it is skipped

Every project spawns its own variant of the same concept, no change can be reversed, and understanding the model becomes archaeology.

Semantics

What gets decided here

Exactly what each data point means: which terminology it binds to, at what binding strength, in which units it is expressed and what happens to values that have no code.

What breaks when it is skipped

Systems share identical structures and incomparable data. Analytics aggregates different things under one name and nobody notices.

Syntax

What gets decided here

How information is structured: what is a resource and what is an attribute, how observations nest, which cardinalities apply and what an absent value actually means.

What breaks when it is skipped

Every integration needs its own translator, no mapping can be reused, and the cost of connecting grows with each new system.

Technical

What gets decided here

How it is persisted and queried: physical schema, indexes, record versioning, historization, and the performance of both the clinical query and the analytical one.

What breaks when it is skipped

The model is correct on paper while the query a clinician needs takes minutes, so someone builds a parallel table and the single model stops being single.

Normalization

What gets decided here

Which rules turn real data — the data already loaded, with duplicates, abbreviations and free text — into data that conforms to the model, and what happens to what does not fit.

What breaks when it is skipped

The new model coexists with years of data that does not comply, and the migration turns out to be unworkable after a date has already been promised.

Methodology

From the model you have to the model you need

Five stages. The first one looks at the real data, not just the diagram.

  1. 01

    Analysis of the current model

    We gather what exists: schemas, dictionaries, homegrown code tables, forms and the structures each system actually uses. And we profile the loaded data — distributions, nulls, free text, duplicates — because the documented model and the production model rarely match.

    Outputs
    • Inventory of sources and schemas
    • Consolidated data dictionary
    • Profiling of real data
    • Code tables in use
  2. 02

    Design review

    We assess the model against explicit criteria rather than opinions: clinical expressiveness, traceability of who recorded what and when, extensibility for a new domain, queryability for both care and analytics, and the ability to sustain the exchange the organization needs.

    Outputs
    • Design review report
    • Findings per layer
    • Risks and model debt
    • Decisions that must be made
  3. 03

    Model scope

    We agree how far it reaches: which clinical domains are in scope now, at what granularity, what is represented in a structured way and what is accepted as text for the time being. Where the domain already has a WHO SMART Guidelines DAK, its core data elements are the starting point for that scope rather than a list built from scratch. An honest scope is what makes everything else executable.

    Outputs
    • Scope document
    • Prioritized domains
    • Granularity per domain
    • What is out of scope, and why
  4. 04

    Target model proposal

    We design the destination model and express it in the artifacts of the chosen approach: archetypes and templates, profiles and extensions, or an internal canonical model. With identifiers, terminologies and conformance rules decided, not pending.

    Outputs
    • Target logical model
    • Artifacts of the chosen approach
    • Identifier strategy
    • Terminology bindings
  5. 05

    Governance and evolution

    A model without a change process diverges again on the first urgent project. We define who approves a modification, how it is versioned, how it is communicated and what compatibility is guaranteed between versions.

    Outputs
    • Model versioning policy
    • Change request process
    • Roles and owners per domain
    • Living model documentation
Approaches

What do we standardize, and with what?

openEHR and FHIR are sometimes presented as mutually exclusive. They are not: they solve different problems, and in more than one ecosystem it makes sense to use both.

openEHR

The clinical record

Models and persists clinical information with the model kept separate from the software: archetypes define the maximal dataset of a clinical concept, templates constrain it for a specific use, and queries are written against the model rather than a physical schema. Clinicians govern the content, not the development team.

Artifacts
  • Archetypes (ADL)
  • Operational templates
  • AQL queries
  • Reference model
When it fits
  • When the organization is building or rebuilding its clinical repository and wants the model to outlive the software vendor.
  • When the clinical domain is deep and changes often, and a schema migration per change is not acceptable.
  • When the clinical history has to be queried with semantics that stay stable over the years.

HL7® FHIR®

The exchange

Models how information leaves one system and enters another: resources at a granularity meant for transport, profiles that constrain them to a specific use case and APIs with defined searches and operations. It is the contract with the outside world.

Artifacts
  • Profiles and extensions
  • ValueSets and bindings
  • CapabilityStatement
  • APIs and search parameters
When it fits
  • When you must exchange with systems, networks or national ecosystems that already require it.
  • When the immediate goal is exposing existing data without rebuilding persistence.
  • When conformance must be verifiable by a third party, with no access to the database.

Canonical model

Inside the organization

The common model the organization uses across its own systems, analytics and processes. It does not always need to be an external standard, but it does need to be a single one: it is where differences between sources get resolved before anything is exposed outward.

Artifacts
  • Canonical logical model
  • Data dictionary
  • Derivation rules
  • Per-source mappings
When it fits
  • When legacy systems that will not be replaced any time soon have to coexist.
  • When analytics needs a stable view that does not depend on each source's version.
  • When it makes sense to pay for translation between models once, in one place, rather than in every integration.

How they connect

Choosing one does not rule out the others. The usual path runs from the clinical model to the exchange contract, and the canonical model is what keeps each end from speaking a language of its own.

  • Archetype → template → FHIR profile: clinical detail stays in the repository and is exposed trimmed down for exchange.
  • Canonical model → FHIR profile: legacy systems are normalized once and exposed conformant without touching their persistence.
  • Shared terminology: bindings are defined once and hold for all three approaches; without that, each one reinvents its codes.
  • Common identifiers: patient, practitioner, facility and encounter must mean the same thing in the repository, in the canonical model and in the API.
Terminologies

Adopting a vocabulary is an operational decision, not a catalog one

Downloading SNOMED CT is not adopting it. Each terminology forces decisions about scope, maintenance, licensing and versioning that, left unmade at the start, end up being made by default and badly.

SNOMED CT®

Reference clinical vocabulary for diagnoses, procedures, findings and clinical context.

Decisions it forces
  • Licensing and affiliation in the country where it will be used.
  • Which subsets or refsets are enabled per form and per domain — nobody uses the whole terminology.
  • Whether a national or institutional extension is created, and who governs it.
  • How concepts inactivated in each release are handled without breaking history.

LOINC®

Identification of observations, laboratory tests, panels and clinical variables.

Decisions it forces
  • Which code corresponds to each test in the local catalog, including the part that today exists only as an internal name.
  • How units are represented and whether they are normalized to UCUM.
  • What to do with panels and with tests the laboratory reports grouped together.
  • Who updates the mapping when the laboratory changes method or equipment.

ICD-10 / ICD-11

Classification for statistical reporting, morbidity, mortality and regulatory obligations.

Decisions it forces
  • What is recorded as classification and what as clinical terminology — they are not interchangeable.
  • How the statistical code is derived from the clinical record without forcing double data entry.
  • Which version each mandatory report requires, and how they coexist when they differ.

National CodeSystems and ValueSets

The country's own catalogs — facilities, services, practitioners — and the ValueSets national guides impose.

Decisions it forces
  • Who publishes them, in what format and how often.
  • How they are synchronized with internal catalogs already in production.
  • What happens when the national catalog changes and local systems have not caught up.
  • How traceability between the local code and the national one is declared.

Local codes and ConceptMap

The catalogs the organization already has and that will not disappear overnight.

Decisions it forces
  • Which local codes get mapped, which are retired and which are kept as a secondary identifier.
  • What equivalence each mapping declares: exact, wider, narrower or none at all.
  • Where the mapping lives and who is accountable for it when the source catalog changes.

We work with these terminologies as a technical frame of reference. Licensing and affiliation, where they apply, rest with the organization or the country adopting them.

Migration

Redesigning the model without shutting down operations

A new model is worth nothing if the data that already exists never reaches it. Migration is designed as a project of its own, with phases, acceptance criteria and a way out.

  1. Inventory and profiling

    Measure what is actually there: volumes, quality, free text, duplicates, out-of-range values and data that never met the rule it was said to meet.

  2. Normalization rules

    Define the transformations and quality criteria: what gets cleaned, what gets deduplicated, what gets enriched with terminology and what gets flagged as non-conformant.

  3. Mapping and equivalences

    Map field by field and code by code, declaring the equivalence type of each mapping. Whatever does not map is documented as an exception; it is not silently dropped.

  4. Model coexistence

    Old and new models run side by side for an agreed period, through dual writes or compatibility views, so no system depends on a single cut-over date.

  5. Backfill and validation

    History is migrated in batches and validated by equivalence: volume reconciliation, aggregate comparison and clinical review by sampling. Validation is what authorizes the cut-over.

  6. Cut-over and retirement

    The flow to the old model is cut and the model is retired once nobody is shown to read it, keeping the traceability of every transformation so a data point's origin can be explained later.

The rules that hold a migration together

  • No data is transformed without a record of the rule that transformed it and of its original value.
  • Whatever does not map is flagged and counted: a migration that hides its exceptions cannot be audited.
  • Coexistence has an end date agreed from the start, or it becomes permanent.
  • The cut-over is authorized by validation, not by the schedule.
  • The old model is retired when nobody is shown to query it, not when it is assumed.
  • Each phase delivers value on its own, so a pause in the project does not leave operations halfway.
Results

What your organization receives

Documents used during the redesign and after it — not a report that gets filed away.

Analysis of the current model

Inventory of sources, consolidated dictionary and profiling of the real data.

Design review

Findings per layer, risks, model debt and the decisions still outstanding.

Scope document

Domains, granularity and what is explicitly out of scope for this iteration.

Target model

The logical model and the artifacts of the chosen approach: archetypes and templates, profiles or a canonical model.

Terminology catalog and ConceptMaps

Bindings per element and declared equivalences with the local codes.

Normalization rules

Transformations, quality criteria and explicit handling of exceptions.

Phased migration plan

Sequence, acceptance criteria, coexistence and the conditions that authorize cut-over.

Model governance

Versioning, change process and owners per domain.

Experience

Modeling in real projects

The modeling and terminology work behind implementation guides that are published and in use today.

Modeling angleNational ValueSets and CodeSystems

Terminology IG — Costa RicaOpens in a new tab

Profiles and ValueSets for the clinical terminologies shared across the country's health ecosystem: deciding which vocabulary applies to each element, at what binding strength, and who maintains the catalog.

Modeling angleLaboratory model and LOINC binding

Lab Results IG — Costa RicaOpens in a new tab

Structure and conformance rules for reporting results: what is represented as an observation, how tests are coded and how units, reference ranges and interpretation travel with them.

Modeling angleNormalization for national reporting

Reporting from EDUS/CCSS

Reporting of notifiable diseases, vaccines and laboratory results: aligning what the source system records with what the national guide requires, and receiving it on the first national FHIR server.

These cases cover the modeling and terminology work inside national implementation guides. The openEHR approach is part of the service and is assessed case by case; it does not appear here because it was not part of these projects.

Profile

Who is this service for?

What changes from one organization to the next is not the method, but how expensive it is to keep going without an agreed model.

Hospitals and hospital networks

Several clinical systems recording the same fact in different ways. The common model is what makes a single patient view possible.

Public institutions and national projects

Ecosystems that must agree on the model before requiring conformance, so the national guide rests on a decision rather than an assumption.

Laboratories and imaging centers

Homegrown catalogs that must map to LOINC or national codes without losing the detail the laboratory needs to operate.

Health software vendors

Products whose schema grew by accretion and that now must expose conformant data without rebuilding the database from scratch.

Analytics and data teams

Teams that depend on data meaning the same thing across every source for an indicator to be comparable between facilities.

Insurers

Exchange with many providers where each codes its own way and equivalence has to be declared, not assumed.

Self-assessment

Do any of these sound familiar?

The same clinical fact is recorded differently in every system, and none of them is wrong.
We have free-text fields where we should have codes.
Every system has its own diagnosis table and none of them match.
We want to adopt SNOMED CT or LOINC and do not know where to start or who would maintain them.
Our data dictionary does not match what is actually in the database.
The same indicator comes out differently depending on which source computes it.
Adding a new clinical domain forces a schema migration.
The model is decided by whoever is coding, at the moment of coding.
We have years of historical data that does not comply with the model we want to adopt.
Nobody can explain where a data point came from after three transformations.
Every new integration means writing yet another translator from scratch.
We need to expose FHIR and found that the data the guide requires does not exist in structured form.

If several of these describe your organization, the problem is not in the interfaces: it is in the model underneath them.

Will your model hold up to what will be asked of it?

Before exposing APIs or committing to a national guide, it is worth knowing what the model actually represents and what is missing to get where you need to be.