Skip to main content
Version: v5.3

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.
  • CREATE permission on aosvc: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:

  1. Create the ontology. Note the _id in the response.

    POST /aosvc/api/v1/ontologies?nsfilter=myapp

    {
    "_name": "Facilities Ontology",
    "_description": "Equipment and spaces"
    }

    For more information, see Create an ontology.

  2. Create a draft version to edit. Note the _versionNumber in the response.

    POST /aosvc/api/v1/ontologies/{ontologyId}/drafts?nsfilter=myapp

    Note: A new ontology starts with version 1 as a draft. If you just created the ontology, skip this step and use 1 as the draft number.

    For more information, see Create a draft.

  3. List the base ontology classes, and note the _id of the class you want to extend, such as Entity.

    GET /aosvc/api/v1/ontologies/base/classes?nsfilter=myapp

    For more information, see List base ontology classes.

  4. Create your classes in the draft. Send the draft number in the X-Ontology-Draft header. Note the _id of each class.

    POST /aosvc/api/v1/ontologies/{ontologyId}/classes?nsfilter=myapp
    X-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.

  5. Declare the relationships between your classes.

    POST /aosvc/api/v1/ontologies/{ontologyId}/relationships?nsfilter=myapp
    X-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.

  6. 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.

  7. Request a promotion of the published version. Note the _requestId in 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.

  8. If the request has a _reportId, review the impact report before you confirm. For more information, see Get an impact report.

  9. Confirm the promotion. For a first promotion, send an empty body. Otherwise, send the _reportId you reviewed.

    POST /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests/{requestId}/confirm?nsfilter=myapp

    {}

    For more information, see Confirm a promotion.

  10. Get the promotion request until _status is PROMOTED. If it's FAILED, read _failureReason, fix the cause, and confirm again.

    GET /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests/{requestId}?nsfilter=myapp

    For 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.