Get Schema

The Get Schema endpoint returns detailed information about a specific schema within a business area, including its field definitions and validation rules.

Prerequisites

Valid access token (see Get Access Token)
Permission to access schemas in your tenant
Valid business area ID and schema ID

Authentication

Include your access token in the Authorization header.

Pass the token directly without the “Bearer” prefix.

Authorization: your_access_token

Request

Path Parameters

businessAreaId

string

required

The unique identifier of the business area containing the schema.

schemaId

string

required

The unique identifier of the schema to retrieve. You can obtain this from the List Schemas endpoint.

Headers

Authorization

string

required

Your access token obtained from the /v1/oauth2/token endpoint. Pass the token directly without the “Bearer” prefix.

string

default:"application/json"

The response content type. Currently only application/json is supported.

Example Requests

curl -X GET "https://api.pretectum.io/v1/businessareas/20240115103000123a1b2c3d4e5f6789012345678901234/schemas/20240115103000456d1e2f3a4b5c6789012345678901234" \
  -H "Authorization: your_access_token" \
  -H "Accept: application/json"

Response

A successful request returns a schema object with its complete definition including field specifications.

schemaId

string

required

The unique identifier for the schema.

name

string

required

The display name of the schema.

description

string

A description of the schema explaining its purpose.

businessAreaId

string

required

The ID of the business area this schema belongs to.

businessAreaName

string

required

The name of the business area this schema belongs to.

version

integer

The version number of the schema.

createdBy

string

The email address of the user who created the schema.

updatedBy

string

The email address of the user who last modified the schema.

createdDate

string

required

The ISO 8601 timestamp when the schema was created.

updatedDate

string

The ISO 8601 timestamp when the schema was last modified.

fields

array

required

An array of field definitions that make up the schema structure. Fields are ordered by creation date (ascending).

Show Field object properties

fieldId

string

required

The unique identifier for the field.

name

string

required

The display name of the field. This is the attribute name used when searching data objects.

description

string

A description of the field and its purpose.

active

boolean

required

Whether the field is currently active.

dataType

string

required

The data type of the field. Possible values: integer, float, string, boolean, datetime, date, time, date-year, date-month, date-day, currency, picklist, email, url, phone, latlng, latitude, longitude, attachment, image, document, video.

isPrimaryKey

boolean

required

Whether the field is a primary key for the data object.

isSortKey

boolean

required

Whether the field is used as a sort key.

isRequired

boolean

required

Whether the field is required when creating or updating data objects.

isMultivalue

boolean

Whether the field can contain multiple values.

isPII

boolean

Whether the field contains Personally Identifiable Information (PII).

min

number | string

Minimum value constraint for the field (applies to numeric, string length, or date fields).

max

number | string

Maximum value constraint for the field (applies to numeric, string length, or date fields).

classifiers

array

Tags associated with the field for categorization.

Show Classifier properties

tagId

string

Tag identifier

tagName

string

Tag display name

validationRules

array

Array of validation rule strings applied to the field (e.g., “alphanumeric”).

allowedBooleanValues

string

Format for boolean values. Only applies when dataType is boolean. Possible values: y/n, Y/N, 1/0, t/f, T/F.

picklistType

string

Type of picklist. Only applies when dataType is picklist. Possible values: static, dynamic.

staticPicklist

array

List of allowed values for static picklists. Only present when picklistType is static.

Show Picklist option properties

code

string

The value code

description

string

The display description

dataDomainId

string

ID of the data domain for dynamic picklists. Only present when picklistType is dynamic.

dateFormat

string

Format for date values. Only applies when dataType is date or datetime. Possible values: DD$MM$YYYY, DD$MMM$YYYY, MM$DD$YYYY, MMM$DD$YYYY, MM$DD$YY, YYYY$MM$DD, YYYY$MMM$DD, YY$MM$DD, YYMMDD, YYYYMMDD.

dateSeparator

string

Separator for date components. Possible values: -, /, ., (space).

timeFormat

string

Format for time values. Possible values: hh:mm:ss a, hh:mm:ss A, hh:mm a, hh:mm A, HH:mm:ss, HH:mm.

maxWidth

number

Maximum width in pixels for image and attachment types.

maxHeight

number

Maximum height in pixels for image and attachment types.

maxSize

number

Maximum file size in bytes for attachment, image, document, and video types.

createdBy

string

Email of the user who created the field.

updatedBy

string

Email of the user who last updated the field.

createdDate

string

ISO 8601 timestamp when the field was created.

updatedDate

string

ISO 8601 timestamp when the field was last updated.

Example Response

{
  "schemaId": "20240115103000456d1e2f3a4b5c6789012345678901234",
  "name": "Customer Schema",
  "description": "Schema for customer data management",
  "businessAreaId": "20240115103000123a1b2c3d4e5f6789012345678901234",
  "businessAreaName": "Customer Management",
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdDate": "2025-01-15T10:30:00Z",
  "updatedDate": "2025-03-20T14:45:00Z",
  "version": 2,
  "fields": [
    {
      "fieldId": "20250115103500001a1b2c3d4e5f6789012345678901234",
      "name": "customer_id",
      "description": "Unique identifier for the customer",
      "active": true,
      "isPrimaryKey": true,
      "isSortKey": false,
      "dataType": "string",
      "max": 20,
      "min": 5,
      "isRequired": true,
      "isMultivalue": false,
      "isPII": false,
      "classifiers": [
        {
          "tagName": "Identifier",
          "tagId": "id-001"
        }
      ],
      "validationRules": ["alphanumeric"],
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdDate": "2025-01-15T10:35:00Z",
      "updatedDate": "2025-01-15T10:35:00Z"
    },
    {
      "fieldId": "20250115103700002b2c3d4e5f6a7890123456789012345",
      "name": "full_name",
      "description": "Customer's full name",
      "active": true,
      "isPrimaryKey": false,
      "isSortKey": true,
      "dataType": "string",
      "max": 100,
      "min": 2,
      "isRequired": true,
      "isMultivalue": false,
      "isPII": true,
      "classifiers": [
        {
          "tagName": "Personally Identifiable",
          "tagId": "pii-001"
        }
      ],
      "validationRules": [],
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdDate": "2025-01-15T10:37:00Z",
      "updatedDate": "2025-02-20T11:22:00Z"
    },
    {
      "fieldId": "20250115104000003c3d4e5f6a7b8901234567890123456",
      "name": "date_of_birth",
      "description": "Customer's date of birth",
      "active": true,
      "isPrimaryKey": false,
      "isSortKey": false,
      "dataType": "date",
      "max": "2010-12-31",
      "min": "1920-01-01",
      "isRequired": false,
      "isMultivalue": false,
      "isPII": true,
      "dateFormat": "YYYY$MM$DD",
      "dateSeparator": "-",
      "classifiers": [
        {
          "tagName": "Personally Identifiable",
          "tagId": "pii-001"
        }
      ],
      "validationRules": [],
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdDate": "2025-01-15T10:40:00Z",
      "updatedDate": "2025-01-15T10:40:00Z"
    },
    {
      "fieldId": "20250115104200004d4e5f6a7b8c9012345678901234567",
      "name": "customer_type",
      "description": "Type of customer",
      "active": true,
      "isPrimaryKey": false,
      "isSortKey": false,
      "dataType": "picklist",
      "isRequired": true,
      "isMultivalue": false,
      "isPII": false,
      "picklistType": "static",
      "staticPicklist": [
        {
          "code": "individual",
          "description": "Individual customer"
        },
        {
          "code": "corporate",
          "description": "Corporate customer"
        },
        {
          "code": "vip",
          "description": "VIP customer"
        }
      ],
      "classifiers": [],
      "validationRules": [],
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdDate": "2025-01-15T10:42:00Z",
      "updatedDate": "2025-03-10T09:15:00Z"
    },
    {
      "fieldId": "20250115104500005e5f6a7b8c9d0123456789012345678",
      "name": "is_active",
      "description": "Whether the customer account is active",
      "active": true,
      "isPrimaryKey": false,
      "isSortKey": false,
      "dataType": "boolean",
      "isRequired": true,
      "isMultivalue": false,
      "isPII": false,
      "allowedBooleanValues": "Y/N",
      "classifiers": [],
      "validationRules": [],
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdDate": "2025-01-15T10:45:00Z",
      "updatedDate": "2025-01-15T10:45:00Z"
    },
    {
      "fieldId": "20250210132000006f6a7b8c9d0e1234567890123456789",
      "name": "profile_picture",
      "description": "Customer's profile picture",
      "active": true,
      "isPrimaryKey": false,
      "isSortKey": false,
      "dataType": "image",
      "isRequired": false,
      "isMultivalue": false,
      "isPII": true,
      "maxWidth": 1024,
      "maxHeight": 1024,
      "maxSize": 5242880,
      "classifiers": [
        {
          "tagName": "Personally Identifiable",
          "tagId": "pii-001"
        }
      ],
      "validationRules": [],
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdDate": "2025-02-10T13:20:00Z",
      "updatedDate": "2025-02-10T13:20:00Z"
    }
  ]
}

Error Responses

Status Code	Description
`401 Unauthorized`	Invalid or expired access token. Obtain a new token and try again.
`403 Forbidden`	Your application client does not have permission to access this schema.
`404 Not Found`	The specified schema or business area does not exist, or you do not have access to it.
`500 Internal Server Error`	An unexpected error occurred on the server.

Use Cases

Understanding Data Structure

Use the schema details to understand what fields are available for searching:

const schema = await getSchema(businessAreaId, schemaId);

// Get searchable fields for building search queries
const searchableFields = schema.fields
  .filter(field => field.searchable)
  .map(field => field.name);

console.log('Searchable fields:', searchableFields);
// Output: ['First Name', 'Last Name', 'Email', 'Phone', 'Active']

Building Dynamic Forms

Use the field definitions to dynamically generate data entry forms:

const schema = await getSchema(businessAreaId, schemaId);

const formFields = schema.fields.map(field => ({
  name: field.name,
  type: mapDataTypeToInputType(field.dataType),
  required: field.required,
  placeholder: field.description
}));

Validating Data Before Search

Verify that a field exists and is searchable before including it in a query:

def is_field_searchable(schema, field_name):
    for field in schema['fields']:
        if field['name'] == field_name:
            return field.get('searchable', False)
    return False

schema = get_schema('20240115103000123a1b2c3d4e5f6789012345678901234', '20240115103000456d1e2f3a4b5c6789012345678901234')
if is_field_searchable(schema, 'Email'):
    # Safe to search by Email field
    results = search('email:*@example.com', schema='Individual Customer')

Best Practices

Cache schema definitions: Schema structures change infrequently. Cache them locally.
Check searchable flag: Only use fields marked as searchable: true in search queries.
Respect required fields: When building forms, ensure required fields are validated.
Use field names in queries: For field-specific searches, use the name property from field definitions.

List Schemas

Get all schemas in a business area

List Business Areas

Get business area IDs

Search Data Objects

Search using schema field names

Get Access Token

Obtain authentication token

Overview

Authentication

Business Areas

Schemas

Datasets

Data Objects

Prerequisites

Authentication

Request

Path Parameters

Headers

Example Requests

Response

Example Response

Error Responses

Use Cases

Understanding Data Structure

Building Dynamic Forms

Validating Data Before Search

Best Practices

List Schemas

List Business Areas

Search Data Objects

Get Access Token

Overview

Authentication

Business Areas

Schemas

Datasets

Data Objects

​Prerequisites

​Authentication

​Request

​Path Parameters

​Headers

​Example Requests

​Response

​Example Response

​Error Responses

​Use Cases

​Understanding Data Structure

​Building Dynamic Forms

​Validating Data Before Search

​Best Practices

​Related Endpoints

List Schemas

List Business Areas

Search Data Objects

Get Access Token

Prerequisites

Authentication

Request

Path Parameters

Headers

Example Requests

Response

Example Response

Error Responses

Use Cases

Understanding Data Structure

Building Dynamic Forms

Validating Data Before Search

Best Practices

Related Endpoints