Skip to main content

Welcome

This section documents the OntoUML Schema, a JSON Schema that defines how OntoUML ontologies are serialized as JSON.

The schema is a faithful, machine-readable rendering of the OntoUML Metamodel. Where the Metamodel documentation describes what OntoUML elements mean, this section describes how those elements are written to — and read from — a JSON document, so that tools can exchange models reliably over the web.

Why a JSON Schema?​

JSON Schema is a widely adopted web standard for describing and validating the structure of JSON data. Publishing the OntoUML serialization as a JSON Schema gives the ecosystem three things:

  • Interoperability. Any tool, in any programming language, can produce and consume OntoUML models in the same shape. The serialization is designed to support the exchange of models over HTTP requests.
  • Validation. A JSON document can be automatically checked against the schema, catching malformed models before they reach a tool that assumes they are well formed.
  • A single source of truth. The schema is versioned and resolvable by a stable URI, so producers and consumers can agree on exactly which structure they are exchanging.
FAIR by design

The schema makes OntoUML models FAIR (Findable, Accessible, Interoperable, Reusable) by design: globally unique identifiers, standards-aligned metadata, controlled vocabularies, and links into the semantic web are built in. See Metadata → FAIR by design.

The schema at a glance​

  • Standard: JSON Schema Draft 2020-12.
  • Identifier: the schema is published under the versioned URI https://w3id.org/ontouml/schema/v1.0.0.
  • Package: it is distributed on npm as ontouml-schema.
  • Source of truth: the schema is authored in YAML (src/ontouml-schema.yaml) and compiled to JSON (dist/ontouml-schema.json).

A minimal valid document is a single Project — the container of an entire ontology:

{
  "type": "Project",
  "id": "my-ontology",
  "name": { "en": "My Ontology" },
  "created": "2024-09-04",
  "modified": null,
  "alternativeNames": [],
  "description": null,
  "editorialNotes": [],
  "creators": [],
  "contributors": [],
  "elements": [],
  "root": null,
  "publisher": null,
  "designedForTasks": [],
  "license": null,
  "accessRights": [],
  "themes": [],
  "contexts": [],
  "ontologyTypes": [],
  "representationStyle": null,
  "namespace": null,
  "landingPages": [],
  "sources": [],
  "bibliographicCitations": [],
  "keywords": [],
  "acronyms": [],
  "languages": []
}
note

The schema is total: every property defined for an element must be present, even when it carries no information. Absent values are written explicitly as null (for single values) or [] (for collections). The Document Structure page explains this rule in detail.

How this documentation is organized​

PageWhat you will find
Getting StartedHow to obtain the schema and validate a document against it.
Document StructureThe overall shape of a serialization: the type hierarchy, the type discriminator, references by id, and the required-property rule.
StructuralThe reference for the identity/naming backbone: OntoumlElement, NamedElement, and Project.
Abstract SyntaxThe reference for model elements — classes, relations, properties, generalizations, packages, and more.
Concrete SyntaxThe reference for diagrams, views, and shapes — the visual representation of a model.
DatatypesThe reusable value types: id, languageString, resource, pointInTime, and point.
EnumerationsThe controlled value sets: ontological natures (restrictedTo), aggregation kinds, and the class/relation/property stereotype vocabularies.
MetadataAll metadata properties across elements — identity, descriptive, and project-level — and how they make models FAIR by design.