Model

A Model is one type in your system. It gives the type a stable identity, says what it means, points at the JSON Schema that gives its structure, and lists what it corresponds to in other systems.

Fields

Field	Type
resourceType	string, required	Always Model.
id	string, required	Short identifier, unique among your models.
url	URL, required	The model’s identity.
version	string, required	The model’s version.
system	string, required	Your own system identifier for the model. internal is conventional for a model that is yours.
name	string, required	Human-readable name, and what a relationship may target.
description	string, optional	What the type means, for a human reader.
schema	URL, optional	The JSON Schema giving its structure. See below.
category	string, optional	Your grouping, for listing models in an order people expect.
icon	string, optional	An icon name, lower case with hyphens.
relationships	array, optional	Named links to other models.
mapsTo	array, optional	Alignments to other systems.
validTime	object, optional	Which properties carry valid time. See below.
publisher	string, optional	Who publishes it, when it differs from the ontology.

Example

{
  "resourceType": "Model",
  "id": "person",
  "url": "https://ours.example.org/models/person.json",
  "version": "1.0.0",
  "system": "internal",
  "name": "Person",
  "description": "A human individual used across ExampleOrg systems.",
  "schema": "https://api.example.org/schemas/User.schema.json",
  "category": "Directory",
  "relationships": [
    {
      "predicate": "memberOf",
      "target": "Organization",
      "description": "The organization this person belongs to."
    }
  ],
  "mapsTo": [
    {
      "system": "http://hl7.org/fhir",
      "schema": "http://hl7.org/fhir/StructureDefinition/Patient",
      "mapping": "https://ours.example.org/mappings/user-to-fhir-patient.json",
      "type": "one-to-one"
    }
  ]
}

schema is optional

Meaning and alignment are publishable before structure is. A publisher whose types are defined in another formalism, FHIR StructureDefinitions for instance, can say what its models mean and what they map to long before it emits JSON Schema for them, and an ontology that cannot be published until then is one that does not get published.

A consumer generating code or validating instances does need it, so a model without a schema earns a warning rather than silence. Warning rather than rejecting keeps an incomplete ontology useful, and honest about what it is missing.

See Schemas for what a model’s JSON Schema may contain.

Relationships

A relationship names a link from this model to another one.

Field	Type
predicate	string, required	What the link means, read as “this model predicate that one”.
target	string, required	Another model, by name or by id.
description	string, optional	What the link means, in prose.

target resolves within the ontology, and pointing at a model that is not there is an error rather than a warning, because a consumer following the link has nowhere to go. Order does not matter: a model may name one that appears later in the bundle.

Valid time

validTime names the properties that carry a record’s valid time when the record does not state one itself. Valid time is when a fact holds in the world being described, as distinct from when the record of it was written.

Field	Type
begin	string, required	Dotted path into the model’s schema, leading to a temporal position.
end	string, optional	The same, for the end of the interval. An interval with no end is open.

"validTime": { "begin": "effectivePeriod.start", "end": "effectivePeriod.end" }

A consumer that knows which fields carry valid time can answer “what did this look like on that date” without being told per-integration which fields to read.

Categories and icons

category and icon carry no meaning to the format. They exist so that a tool rendering your ontology can group and label models the way you would, instead of listing them alphabetically and picking its own glyphs. A consumer transforming data ignores both.