Learn
OURS (pronounced like "oors") is a shared, machine-readable way to publish how your data is structured and how it relates to other standards.
Why does it exist?
Most data integration problems don't come from missing standards. They come from missing explanations of how those standards are used together. Today, those explanations live in documentation, code, or people's heads. OURS turns them into a machine-readable set of files that systems can discover and use automatically.
How it works
OURS follows a simple discovery pattern: start with one well-known file, then fetch what you need.
Discover the ontology
A system starts by fetching your published ontology file (for example, ours.example.org/ontology.json). This tells it where to find your models, vocabularies, and mappings.
Fetch the resources
The system fetches the specific models, vocabularies, and mappings it needs. It only downloads what's required for the integration task.
Use the mappings
Tools can use the StructureMaps and ConceptMaps to automatically convert data between formats. The mappings use FHIR Mapping Language, so existing FHIR tooling can process them directly.
The key benefit: No prior coordination needed. If you publish your ontology at a well-known URL, other systems can discover and integrate with your data automatically by fetching the published maps.
Examples
In practice, you publish an ontology map that points to your model definitions,vocabularies, and data mappings.
Ontology
A single "well-known" file that tells others where to fetch your published materials. For simple cases, you can also include these files in the ontology file itself to avoid multiple HTTP requests. However, this is not recommended for large or complex ontologies to avoid bloating the file size.
{
"resourceType": "Ontology",
"id": "example-org",
"url": "https://ours.example.org/ontology.json",
"version": "1.0.0",
"publisher": "ExampleOrg",
"models": "https://ours.example.org/models.json",
"vocabularies": "https://ours.example.org/vocabularies.json",
"mappings": "https://ours.example.org/mappings.json"
}Models
Define what your models mean (your semantic meaning) and provide the schema you use internally (your structural meaning). If you want to encourage other systems to use your models, you can provide mappings to your models into other standards.
{
"resourceType": "Bundle",
"type": "collection",
"entry": [
{
"fullUrl": "https://ours.example.org/models/person.json",
"resource": {
"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",
"relationships": [{ "predicate": "memberOf", "target": "Organization" }],
"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"
},
{
"system": "https://schema.org",
"schema": "https://schema.org/Person",
"mapping": "https://ours.example.org/mappings/user-to-schemaorg-person.json",
"type": "one-to-one"
}
]
}
},
{
"fullUrl": "https://ours.example.org/models/organization.json",
"resource": {
"resourceType": "Model",
"id": "organization",
"url": "https://ours.example.org/models/organization.json",
"version": "1.0.0",
"system": "internal",
"name": "Organization",
"description": "A company, facility, or department.",
"schema": "https://api.example.org/schemas/Organization.schema.json",
"mapsTo": [
{
"system": "http://hl7.org/fhir",
"schema": "http://hl7.org/fhir/StructureDefinition/Organization",
"mapping": "https://ours.example.org/mappings/org-to-fhir-organization.json",
"type": "one-to-one"
},
{
"system": "https://schema.org",
"schema": "https://schema.org/Organization",
"mapping": "https://ours.example.org/mappings/org-to-schemaorg-organization.json",
"type": "one-to-one"
}
]
}
}
]
}Vocabularies
List all vocabularies you use (both internal and external). When using external vocabularies, you simply reference them (no need to republish). For internal vocabularies, you can include the codes inline or link to where they're defined.
{
"resourceType": "Bundle",
"type": "collection",
"entry": [
{
"fullUrl": "https://www.iso.org/iso-4217-currency-codes.html",
"resource": {
"resourceType": "Vocabulary",
"id": "iso-4217",
"url": "https://www.iso.org/iso-4217-currency-codes.html",
"version": "2015",
"system": "https://www.iso.org",
"name": "ISO 4217 currency codes",
"description": "List of currency codes.",
"mapsTo": [
{
"system": "http://hl7.org/fhir",
"schema": "http://hl7.org/fhir/ValueSet/iso-4217-currency-codes",
"mapping": "https://ours.example.org/mappings/iso-4217-currency-codes-to-fhir-value-set.json",
"type": "one-to-one"
}
]
}
},
{
"fullUrl": "https://api.example.org/codes/invoice-status",
"resource": {
"resourceType": "Vocabulary",
"id": "exampleorg-invoice-status",
"url": "https://api.example.org/codes/invoice-status",
"version": "1.0.0",
"system": "internal",
"name": "ExampleOrg invoice status",
"description": "List of invoice status codes.",
"codes": [
{ "code": "OPEN", "display": "Open" },
{ "code": "PAID", "display": "Paid" },
{ "code": "VOID", "display": "Void" },
{ "code": "UNKNOWN", "display": "Unknown" }
],
"mapsTo": [
{
"system": "http://hl7.org/fhir",
"schema": "http://hl7.org/fhir/ValueSet/invoice-status",
"mapping": "https://ours.example.org/mappings/invoice-status-to-fhir-value-set.json",
"type": "one-to-one"
}
]
}
}
]
}Mappings
Models and vocabularies are mapped to known structures and terminologies using FHIR Mapping Language.
Structure Maps
Map a model to a known structure.
{
"resourceType": "StructureMap",
"id": "user-to-schemaorg-person",
"url": "https://ours.example.org/mappings/user-to-schemaorg-person.json",
"version": "1.0.0",
"name": "UserToSchemaOrgPerson",
"title": "User to Schema.org Person mapping",
"status": "active",
"structure": [
{
"url": "https://api.example.org/schemas/User.schema.json",
"mode": "source"
},
{
"url": "https://schema.org/Person",
"mode": "target"
}
],
"group": [
{
"name": "UserToSchemaOrgPerson",
"input": [
{ "name": "src", "type": "User", "mode": "source" },
{ "name": "tgt", "type": "Person", "mode": "target" }
],
"rule": [
{
"name": "mapFirstName",
"source": [
{
"context": "src",
"element": "firstName"
}
],
"target": [
{
"context": "tgt",
"element": "name.given",
"transform": "copy"
}
]
},
{
"name": "mapLastName",
"source": [
{
"context": "src",
"element": "lastName"
}
],
"target": [
{
"context": "tgt",
"element": "name.family",
"transform": "copy"
}
]
}
]
}
]
}Concept Maps
Map a vocabulary to a known terminology.
{
"resourceType": "ConceptMap",
"id": "invoice-status-to-fhir-value-set",
"url": "https://ours.example.org/mappings/invoice-status-to-fhir-value-set.json",
"version": "1.0.0",
"name": "InvoiceStatusToFhirValueSet",
"title": "Invoice Status to FHIR Value Set",
"status": "active",
"group": [
{
"source": "https://api.example.org/codes/invoice-status",
"target": "http://hl7.org/fhir/ValueSet/invoice-status",
"element": [
{
"code": "OPEN",
"display": "Open",
"target": [
{
"code": "issued",
"display": "Issued",
"relationship": "equivalent"
}
]
},
{
"code": "PAID",
"display": "Paid",
"target": [
{
"code": "balanced",
"display": "Balanced",
"relationship": "equivalent"
}
]
},
{
"code": "VOID",
"display": "Void",
"target": [
{
"code": "cancelled",
"display": "Cancelled",
"relationship": "equivalent"
}
]
}
],
"unmapped": {
"mode": "fixed",
"code": "UNKNOWN",
"display": "Unknown",
"relationship": "not-related-to"
}
}
]
}