> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pretectum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Schema

> Retrieve detailed information about a specific schema

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

## Prerequisites

* A Pretectum API key (see [API Keys](/api-reference/authentication/api-keys))
* Permission to access schemas in your tenant
* Valid business area ID and schema ID

## Authentication

Include your API key in the `Authorization` header.

```bash theme={null}
Authorization: pre_your_api_key
```

## Request

### Path Parameters

<ParamField path="businessAreaId" type="string" required>
  The unique identifier of the business area containing the schema.
</ParamField>

<ParamField path="schemaId" type="string" required>
  The unique identifier of the schema to retrieve. You can obtain this from the [List Schemas](/api-reference/schemas/list) endpoint.
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required initialValue="pre_your_api_key">
  Your Pretectum API key. Create one in the Pretectum app under **Configuration → API Keys**.
</ParamField>

<ParamField header="Accept" type="string" default="application/json">
  The response content type. Currently only `application/json` is supported.
</ParamField>

### Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.pretectum.io/v1/businessareas/20240115103000123a1b2c3d4e5f6789012345678901234/schemas/20240115103000456d1e2f3a4b5c6789012345678901234" \
    -H "Authorization: pre_your_api_key" \
    -H "Accept: application/json"
  ```

  ```javascript JavaScript theme={null}
  const apiKey = 'pre_your_api_key';

  async function getSchema(businessAreaId, schemaId) {
    const response = await fetch(
      `https://api.pretectum.io/v1/businessareas/${businessAreaId}/schemas/${schemaId}`,
      {
        headers: {
          'Authorization': apiKey,
          'Accept': 'application/json'
        }
      }
    );

    if (!response.ok) {
      if (response.status === 404) {
        return null;
      }
      throw new Error(`Failed to fetch schema: ${response.statusText}`);
    }

    return response.json();
  }

  const schema = await getSchema('20240115103000123a1b2c3d4e5f6789012345678901234', '20240115103000456d1e2f3a4b5c6789012345678901234');
  if (schema) {
    console.log(`Schema: ${schema.name}`);
    console.log(`Fields: ${schema.fields.length}`);
  }
  ```

  ```python Python theme={null}
  import requests

  api_key = 'pre_your_api_key'

  def get_schema(business_area_id, schema_id):
      response = requests.get(
          f'https://api.pretectum.io/v1/businessareas/{business_area_id}/schemas/{schema_id}',
          headers={
              'Authorization': api_key,
              'Accept': 'application/json'
          }
      )

      if response.status_code == 404:
          return None

      response.raise_for_status()
      return response.json()

  schema = get_schema('20240115103000123a1b2c3d4e5f6789012345678901234', '20240115103000456d1e2f3a4b5c6789012345678901234')
  if schema:
      print(f"Schema: {schema['name']}")
      print(f"Fields: {len(schema['fields'])}")
  ```
</CodeGroup>

## Response

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

<ResponseField name="schemaId" type="string" required>
  The unique identifier for the schema.
</ResponseField>

<ResponseField name="name" type="string" required>
  The display name of the schema.
</ResponseField>

<ResponseField name="description" type="string">
  A description of the schema explaining its purpose.
</ResponseField>

<ResponseField name="businessAreaId" type="string" required>
  The ID of the business area this schema belongs to.
</ResponseField>

<ResponseField name="businessAreaName" type="string" required>
  The name of the business area this schema belongs to.
</ResponseField>

<ResponseField name="version" type="integer">
  The version number of the schema.
</ResponseField>

<ResponseField name="createdBy" type="string">
  The email address of the user who created the schema.
</ResponseField>

<ResponseField name="updatedBy" type="string">
  The email address of the user who last modified the schema.
</ResponseField>

<ResponseField name="createdDate" type="string" required>
  The ISO 8601 timestamp when the schema was created.
</ResponseField>

<ResponseField name="updatedDate" type="string">
  The ISO 8601 timestamp when the schema was last modified.
</ResponseField>

<ResponseField name="fields" type="array" required>
  An array of field definitions that make up the schema structure. Fields are ordered by creation date (ascending).

  <Expandable title="Field object properties">
    <ResponseField name="fieldId" type="string" required>
      The unique identifier for the field.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      The display name of the field. This is the attribute name used when searching data objects.
    </ResponseField>

    <ResponseField name="description" type="string">
      A description of the field and its purpose.
    </ResponseField>

    <ResponseField name="active" type="boolean" required>
      Whether the field is currently active.
    </ResponseField>

    <ResponseField name="dataType" type="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`.
    </ResponseField>

    <ResponseField name="isPrimaryKey" type="boolean" required>
      Whether the field is a primary key for the data object.
    </ResponseField>

    <ResponseField name="isSortKey" type="boolean" required>
      Whether the field is used as a sort key.
    </ResponseField>

    <ResponseField name="isRequired" type="boolean" required>
      Whether the field is required when creating or updating data objects.
    </ResponseField>

    <ResponseField name="isMultivalue" type="boolean">
      Whether the field can contain multiple values.
    </ResponseField>

    <ResponseField name="isPII" type="boolean">
      Whether the field contains Personally Identifiable Information (PII).
    </ResponseField>

    <ResponseField name="min" type="number | string">
      Minimum value constraint for the field (applies to numeric, string length, or date fields).
    </ResponseField>

    <ResponseField name="max" type="number | string">
      Maximum value constraint for the field (applies to numeric, string length, or date fields).
    </ResponseField>

    <ResponseField name="classifiers" type="array">
      Tags associated with the field for categorization.

      <Expandable title="Classifier properties">
        <ResponseField name="tagId" type="string">Tag identifier</ResponseField>
        <ResponseField name="tagName" type="string">Tag display name</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="validationRules" type="array">
      Array of validation rule strings applied to the field (e.g., "alphanumeric").
    </ResponseField>

    <ResponseField name="allowedBooleanValues" type="string">
      Format for boolean values. Only applies when `dataType` is `boolean`. Possible values: `y/n`, `Y/N`, `1/0`, `t/f`, `T/F`.
    </ResponseField>

    <ResponseField name="picklistType" type="string">
      Type of picklist. Only applies when `dataType` is `picklist`. Possible values: `static`, `dynamic`.
    </ResponseField>

    <ResponseField name="staticPicklist" type="array">
      List of allowed values for static picklists. Only present when `picklistType` is `static`.

      <Expandable title="Picklist option properties">
        <ResponseField name="code" type="string">The value code</ResponseField>
        <ResponseField name="description" type="string">The display description</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="dataDomainId" type="string">
      ID of the data domain for dynamic picklists. Only present when `picklistType` is `dynamic`.
    </ResponseField>

    <ResponseField name="dateFormat" type="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`.
    </ResponseField>

    <ResponseField name="dateSeparator" type="string">
      Separator for date components. Possible values: `-`, `/`, `.`, ` ` (space).
    </ResponseField>

    <ResponseField name="timeFormat" type="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`.
    </ResponseField>

    <ResponseField name="maxWidth" type="number">
      Maximum width in pixels for image and attachment types.
    </ResponseField>

    <ResponseField name="maxHeight" type="number">
      Maximum height in pixels for image and attachment types.
    </ResponseField>

    <ResponseField name="maxSize" type="number">
      Maximum file size in bytes for attachment, image, document, and video types.
    </ResponseField>

    <ResponseField name="createdBy" type="string">
      Email of the user who created the field.
    </ResponseField>

    <ResponseField name="updatedBy" type="string">
      Email of the user who last updated the field.
    </ResponseField>

    <ResponseField name="createdDate" type="string">
      ISO 8601 timestamp when the field was created.
    </ResponseField>

    <ResponseField name="updatedDate" type="string">
      ISO 8601 timestamp when the field was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "schemaId": "20240115103000456d1e2f3a4b5c6789012345678901234",
  "name": "Customer Schema",
  "description": "Schema for customer data management",
  "businessAreaId": "20240115103000123a1b2c3d4e5f6789012345678901234",
  "businessAreaName": "Customer Management",
  "createdBy": "john.doe@example.com",
  "updatedBy": "jane.smith@example.com",
  "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": "john.doe@example.com",
      "updatedBy": "john.doe@example.com",
      "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": "john.doe@example.com",
      "updatedBy": "jane.smith@example.com",
      "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": "john.doe@example.com",
      "updatedBy": "john.doe@example.com",
      "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": "john.doe@example.com",
      "updatedBy": "jane.smith@example.com",
      "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": "john.doe@example.com",
      "updatedBy": "john.doe@example.com",
      "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": "jane.smith@example.com",
      "updatedBy": "jane.smith@example.com",
      "createdDate": "2025-02-10T13:20:00Z",
      "updatedDate": "2025-02-10T13:20:00Z"
    }
  ]
}
```

## Error Responses

| Status Code | Description |
| - | - |
| `401 Unauthorized` | The API key is missing, malformed, unknown, inactive, expired or deleted. Check the key in **Configuration → API Keys**. |
| `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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```python theme={null}
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

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

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Schemas" icon="list" href="/api-reference/schemas/list">
    Get all schemas in a business area
  </Card>

  <Card title="List Business Areas" icon="building" href="/api-reference/business-areas/list">
    Get business area IDs
  </Card>

  <Card title="Search Data Objects" icon="magnifying-glass" href="/api-reference/dataobjects/search">
    Search using schema field names
  </Card>

  <Card title="API Keys" icon="key" href="/api-reference/authentication/api-keys">
    Obtain authentication token
  </Card>
</CardGroup>