Creating an ontology
Creating an ontology
This page shows how to create an application ontology for a namespace, add classes and relationships, and make the ontology live. For background, see Ontologies and Versions and drafts.
Before you start, make sure you have the following:
- A namespace with no application ontology. A namespace can have only one.
CREATEpermission onaosvc:ontology:*.- To confirm the promotion, Item Service permissions on schema definitions and collections. For the list, see Confirm a promotion.
Every request needs an Authorization: Bearer <token> header. The examples use the namespace myapp.
Note: Individuals use the live version, so a class needs a collection mapping in the version you promote. To store individuals, map your classes before you publish. For more information, see Mapping a class to a collection.
To create an ontology, complete the following steps:
-
Create the ontology. Note the
_idin the response.POST /aosvc/api/v1/ontologies?nsfilter=myapp{"_name": "Facilities Ontology","_description": "Equipment and spaces"}For more information, see Create an ontology.
-
Create a draft version to edit. Note the
_versionNumberin the response.POST /aosvc/api/v1/ontologies/{ontologyId}/drafts?nsfilter=myappNote: A new ontology starts with version 1 as a draft. If you just created the ontology, skip this step and use
1as the draft number.For more information, see Create a draft.
-
List the base ontology classes, and note the
_idof the class you want to extend, such asEntity.GET /aosvc/api/v1/ontologies/base/classes?nsfilter=myappFor more information, see List base ontology classes.
-
Create your classes in the draft. Send the draft number in the
X-Ontology-Draftheader. Note the_idof each class.POST /aosvc/api/v1/ontologies/{ontologyId}/classes?nsfilter=myappX-Ontology-Draft: 1[{"_name": "Pump","_parentClass": { "_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39" },"_pluralName": "Pumps","_externalKeyFields": ["_sourceKey"]},{"_name": "Room","_parentClass": { "_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39" }}]Note: The service creates the classes in order. If a class extends another class in the same request, list the parent first.
For more information, see Create classes and Classes.
-
Declare the relationships between your classes.
POST /aosvc/api/v1/ontologies/{ontologyId}/relationships?nsfilter=myappX-Ontology-Draft: 1{"_sourceClassId": "<Pump class ID>","_targetClassId": "<Room class ID>","_type": "locatedAt","_description": "Where this pump is installed"}For more information, see Create a class relationship and Relationships and rules.
-
Publish the draft. A published version can't change.
POST /aosvc/api/v1/ontologies/{ontologyId}/versions/1/publish?nsfilter=myapp{"_label": "First release"}For more information, see Publish a version.
-
Request a promotion of the published version. Note the
_requestIdin the response. If a version is already live, also note the_reportId.POST /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests?nsfilter=myapp{"_versionNumber": 1}For more information, see Request a promotion.
-
If the request has a
_reportId, review the impact report before you confirm. For more information, see Get an impact report. -
Confirm the promotion. For a first promotion, send an empty body. Otherwise, send the
_reportIdyou reviewed.POST /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests/{requestId}/confirm?nsfilter=myapp{}For more information, see Confirm a promotion.
-
Get the promotion request until
_statusisPROMOTED. If it'sFAILED, read_failureReason, fix the cause, and confirm again.GET /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests/{requestId}?nsfilter=myappFor more information, see Get a promotion request.
The version is now live. To change the ontology later, create a new draft and repeat steps 4 to 10.