Objectivity REST : Schema Resources
Schema Resources
Schema is a language-independent data model that describes all the classes used in a particular federated database. The schema resources let you create, modify, or delete the schema of a federated database.
Retrieves a representation of the complete schema for a federated database.
Adds one or more new class descriptions to the schema of a federated database.
Provides one or more class descriptions, each of which results in the creation of a new class or the addition of new attributes to an existing class.
Retrieves the schema representation for a class identified by class name or class number.
Modifies an existing class, either renaming the class or deleting, renaming, or adding attributes.
Deletes the class description for an existing type specified by fully qualified class name or class number.
Returns a list of all schema namespaces in the federated database.
Returns the schema representations for all classes in the specified namespace.
When working with schema using Objectivity REST, you use JSON to create or modify class descriptions. The JSON representations for the available Objectivity/DB types are provided in Objectivity/DB Data Types.
Schema namespaces provide name scopes for grouping sets of classes and are analagous to the namespaces (or packages) supported by various programming languages.
The examples in this section are based on the schema for a sample application for a vehicle rental company; see Schema for Rental Fleet Example.
Schema Evolution
Schema evolution is the process of modifying the schema of a federated database over time. When first created, a class is identified by a unique class number, which is identical to its shape number. If the class is evolved, a new description is added to the schema and the shape number is incremented. New objects use the new class description, and existing objects are converted to use the new description the next time they are accessed.
When accessed either by name or class number, the class automatically gets the latest shape number.
Consequences of Schema Evolution
It’s important to understand that schema evolution can result in data loss depending on the type of change. For example, if you delete an attribute from an existing class, objects that were created under the original class description will be modified when they are next accessed. Specifically, the attribute in question will be removed and its value lost.
The following describes the consequences of various schema modifications on existing objects of the given class. Consider any changes carefully before implementing them.
Schema Change
Consequences for Existing Objects
Add an attribute
Space for the new attribute is added to objects of that class and its subclasses and the shape number of the class is incremented.
Delete an attribute
The attribute is removed from objects of that class and the values are lost. The shape number of the class is incremented.
Rename an attribute
The attribute is renamed and its value is retained. The shape number of the class remains the same.
Delete a class
Before deleting a class, remove all objects of that class from the federated database. Objects of the class become inaccessible to applications after the class is deleted.
Rename a class
Objects can be accessed using the new class name. The shape number of the class remains the same.
Using Retrieved Schema Representations
One approach for creating new class descriptions is to access the schema for an existing federated database and use those JSON representations as guides.
When using this approach, note that some JSON fields in returned representations are for informational purposes and cannot be used when creating schema. For example, the following shows the returned representation of the Vehicle class whose schema was added in the POST /v1/schema example.
  "className": "FleetData.Vehicle",
  "classNumber": "1000010",
  "shapeNumber": "1000010",
  "isReferenceable": true,
  "isInternal": false,
  "isDeleted": false,
  "superClass": null,
    "attributes": [
         "attributeName": "available",
         "logicalType": "boolean",
         "encoding": "binary",
         "storage": "byte"
       }, ...
The entries in red are of interest for understanding existing schema, but are not supported for creating new schema. For example, when creating schema for a new class, the class number and shape number of the class are not yet known (they are assigned automatically at creation time). As another example, the isInternal label indicates whether a class is an internal Objectivity/DB class, which would not be relevant when creating a new class for your application.