Skip to main content

Object Types & Schema Registry

Object types define the structure and behavior of spatial objects in Terragnos Core. Each object type specifies allowed geometries, attributes, validation rules, and optional workflow bindings. This guide explains how to create, version, and publish object types.

Understanding Object Types​

An object type is a schema definition that describes:

  • Geometry types – Which spatial representations are allowed (point, line, polygon, etc.)
  • Attributes – Custom fields stored as JSONB
  • Validation rules – Constraints on attribute values
  • Workflow bindings – Optional state machine for lifecycle management
  • Public ID templates – Format for human-readable identifiers

Creating an Object Type​

Via API​

Create a new object type using the REST API:

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "traffic-signal",
    "displayName": "Traffic Signal",
    "geometryTypes": ["point"],
    "attributes": {
      "type": "object",
      "properties": {
        "signalType": {
          "type": "string",
          "enum": ["standard", "pedestrian", "emergency"]
        },
        "intersectionId": {
          "type": "string"
        },
        "installationDate": {
          "type": "string",
          "format": "date"
        }
      },
      "required": ["signalType"]
    }
  }' \
  https://core.example.com/v1/object-types

Via Admin Console​

  1. Navigate to Object Types in the Admin Console
  2. Click Create New Type
  3. Fill in the type definition form
  4. Configure geometry types and attributes
  5. Save as draft

Schema Definition​

Geometry Types​

Specify which geometry types are allowed:

  • point – Single point location
  • linestring – Line or path
  • polygon – Closed area
  • multipoint – Multiple points
  • multilinestring – Multiple lines
  • multipolygon – Multiple polygons

Example:

{
  "geometryTypes": ["point", "polygon"]
}

Attributes Schema​

Define attributes using JSON Schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "status": {
      "type": "string",
      "enum": ["active", "inactive", "maintenance"]
    },
    "priority": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "required": ["name", "status"]
}

Indexing​

Configure indexes for faster queries:

{
  "indexes": [
    {
      "path": "$.status",
      "type": "gin"
    },
    {
      "path": "$.priority",
      "type": "btree"
    }
  ]
}

Schema Registry Lifecycle​

Object types follow a versioned lifecycle:

1. Draft​

Initial creation state. Draft types can be modified freely but cannot be used to create objects.

2. Sandbox​

Testing state. Sandbox types can be used to create test objects but are not available in production workflows.

3. Published​

Production state. Published types are immutable and can be used to create production objects.

Publishing a Type​

# Move from draft to sandbox
curl -X POST \
  -H "Authorization: Bearer <token>" \
  https://core.example.com/v1/schema-registry/object-type/{typeId}/sandbox

# Move from sandbox to published
curl -X POST \
  -H "Authorization: Bearer <token>" \
  https://core.example.com/v1/schema-registry/object-type/{typeId}/publish

Versioning​

When you modify a published type, a new version is created automatically. Previous versions remain available for existing objects.

Version History​

View version history:

curl -H "Authorization: Bearer <token>" \
  https://core.example.com/v1/schema-registry/object-type/{typeId}/versions

Migrating Objects​

When a type is updated, existing objects continue using their original schema version. To migrate objects to a new version:

  1. Create a migration script using the SDK
  2. Read objects with the old schema
  3. Transform attributes to match the new schema
  4. Update objects with the new version

Public ID Templates​

Define templates for human-readable identifiers:

{
  "publicIdTemplate": "SIGNAL-{sequence:6}"
}

This generates IDs like SIGNAL-000001, SIGNAL-000002, etc.

Workflow Binding​

Associate a workflow with an object type:

{
  "workflowId": "signal-lifecycle",
  "initialState": "draft"
}

All objects of this type will follow the specified workflow.

Best Practices​

  1. Start with draft – Create types in draft state, test thoroughly before publishing
  2. Use descriptive names – Choose clear, consistent naming conventions
  3. Validate early – Define strict validation rules in the schema
  4. Index frequently queried fields – Add indexes for fields used in filters
  5. Version carefully – Published types are immutable; plan changes ahead
  6. Document attributes – Use JSON Schema description fields for documentation
  7. Test in sandbox – Always test type changes in sandbox before publishing

Example: Complete Object Type​

{
  "name": "road-segment",
  "displayName": "Road Segment",
  "geometryTypes": ["linestring"],
  "attributes": {
    "type": "object",
    "properties": {
      "roadName": {
        "type": "string",
        "description": "Official road name"
      },
      "speedLimit": {
        "type": "integer",
        "minimum": 20,
        "maximum": 130,
        "description": "Speed limit in km/h"
      },
      "surfaceType": {
        "type": "string",
        "enum": ["asphalt", "concrete", "gravel", "dirt"]
      },
      "lanes": {
        "type": "integer",
        "minimum": 1,
        "maximum": 8
      }
    },
    "required": ["roadName", "speedLimit"]
  },
  "indexes": [
    {
      "path": "$.roadName",
      "type": "gin"
    },
    {
      "path": "$.speedLimit",
      "type": "btree"
    }
  ],
  "publicIdTemplate": "ROAD-{sequence:6}",
  "workflowId": "road-lifecycle"
}