The signature is a JSON-based parameter supported by the Aggregated Context API (Beta) that you can use to tailor the API response to your specific use case. It allows you to precisely define:

• Which object types the API should search (for example: tables, columns, or documentation objects)
• Which fields should be included in the results
• What filters should be applied to define the catalog objects that are in scope
• What fields to include for child columns in tables

In this guide:

• Why Use a Signature?
• Signature Structure
• Fields
• Search Filters
• Child Objects
• Full Signature Template
• Signature Examples
• Construct an Effective Signature Step by Step

Why Use a Signature?

Without a signature, the API searches across the entire catalog and can return matches from any supported object type, including content that may not be relevant, such as uncertified or organization-wide assets.

Using a signature allows you to narrow the scope to specific object types, departments, or trusted assets, such as certified or gold standard tables, which helps improve the precision and relevance of the results.

A well-crafted signature can enable:

• Domain-specific results (for example: Only the information in the HR domain)
• Performance optimization of the API request
• Granular control over the context down to the field level
• Support for downstream LLM integrations by reducing response size

If no signature is provided, the API falls back to its default scope, which includes all supported object types. The default required fields will be used as required_fields, while all other available fields will be included as optional fields.

Signature Structure

The top-level keys of a signature JSON object are object types. You can include any combination of the following top-level keys:

• schema
• table
• column
• documentation
• query

Configuration Options for Object Types

Each object type further accepts the following configuration options:

Additional Configuration for Table Object Types

The table object type additionally supports column child objects:

Fields

Each object type supports its own specific fields, detailed below. These fields can be listed in the fields_required, fields_optional, and child_objects keys of the signature.

Schema Fields

Default required fields: name, title, description,url

Table Fields

Default required fields: name, title, description, url

Column Fields

Default required fields: name, title, data_type, url

Documentation Object Fields

Default required fields: title, content, url

Query Fields

Default required fields: title, description, content, url

Search Filters

Use search_filters to narrow the scope of returned objects. Supported filters can include these keys:

domain_ids

Filter by IDs for domains:

{
    "search_filters":{
       "domain_ids": [ID_1, ID_2]
       }
}

• domain_ids = the key to use for domains
• [ID_1, ID_2]= list of specific domain IDs you're filtering with

fields

Filter on custom field values:

{
    "search_filters":{
       "fields": {
          "cf[ID]":["value_1", "value_2"]
        }
     }
}

• cf[ID] = the system ID of the custom field
• ["value_1", "value_2"] = the field values you're filtering on

tag_ids

Filter by tags. Tags are referenced inside the fields key:

{
   "search_filters":{
      "fields": {
         "tag_ids": [ID_1, ID_2]
      }
    }
}

• tag_ids = the key to use for the tags filter
• [ID_1, ID_2] = list of specific tag IDs you’re filtering on

flags

Filter by trust flags:

{
    "search_filters": {
       "flags":["Endorsement","Deprecation","Warning"]
       }
}

• flags = the key to use for the flags filter
• ["Endorsement","Deprecation","Warning"] = list of the flag values you're filtering on

Example Signature

Let's assume you'd like to construct a signature like the following:

Limit the context to the table object type within the HR domain (has the ID of 10), with the custom field of Picker type Confidentiality (has the ID of 10559) set to Public or Internal (other confidentiality values of Restricted and Confidential are not included), with the Gold tag (has the ID of 1), and the Endorsed flag:

{
  "table": {
     "search_filters": {
        "domain_ids": [10],
        "fields": {
           "tag_ids": [1],
           "cf[10559]": ["Public", "Internal"]
         },
        "flags": ["Endorsement"]
     }
  }
}

Child Objects

Use the child_objects key to customize which fields are returned for nested (child) objects.

As of version 2025.1.3, we support the child_objects key for the table and query object types.

📘

Maximum Child Objects Returned

A maximum of 50 child objects are returned per parent. Child objects with popularity data are ranked first. The rest are added afterward in the order they were retrieved or are selected randomly.

You may have noticed that object types can function in two ways within a signature: as higher-level object type keys and as lower-level specifiers for nested objects:

• Object types keys: When an object type (schema, table, etc.) is used as the object type key in the signature, it limits the overall scope of the request to objects of that type. It acts as the main container, and any other filters included within its definition apply only to matching objects.

• Object types as child objects keys: When an object type is specified for the child_objects key, it specifies which related child objects and their fields should be included. This allows you to further refine the data retrieved for these specific child objects by specifying which of their fields you need.

Supported Child Objects

Table Object Type

columns

To customize the response for columns within tables, use the columns key inside the child_objects key for the table object type.

Include this key only if you’ve also included columns in either the fields_required or fields_optional keys of your query signature for the table object.

The columns key within child_objects allows you to define exactly which column fields to return for each column within the returned tables.

In summary:

• If columns is included in either fields_required or fields_optional and in child_objects, you will receive the columns for each table, with the fields specified in the nested structure.
• If columns is included only in fields_required or fields_optional, but not in child_objects, the response will include columns with the default set of column fields.
• If columns is included only in child_objects, but not in fields_required or fields_optional, the response will not include columns, as they were not explicitly requested in any of the fields_ keys. This is not a valid format.

Use the following format:

{ 
"table": {
 
    // List of fields that must be included in the response for tables:
    
    "fields_required": ["name", "title", "description", "url", "columns"],
       
    // Only use context from these specific fields for the child columns: 

    "child_objects": {
        "columns": {
           "fields": ["name", "data_type", "description"]
            }
         }
  }
}

This structure translates to:

Retrieve information primarily about table objects. For each table retrieved, also include information about its child column objects, but only return the name, data_type, and description fields for those columns.

common_queries

To customize the list of the query fields to return for each common query associated with a table, use the common_queries key within the child_objects section of the table object.

This key should only be used if common_queries is also listed in either the fields_required or fields_optional sections of your signature for the table object.

📘

Note

The child_objects key is not supported within common_queries. Only the fields key is allowed.

In summary:

• If common_queries is included in either fields_required or fields_optional and in child_objects, you will receive the associated common queries for each table, with the fields specified in the nested structure.
• If common_queries is included only in fields_required or fields_optional, but not in child_objects, the response will include common queries with a default set of fields.
• If common_queries is included only in child_objects, but not in fields_required or fields_optional, common queries will not be returned, as they were not explicitly requested in any of the fields_ keys. This is not a valid format.

Use the following format:

{
"table": {
 
    // List of fields that must be included in the response for tables:
    
    "fields_required": ["name", "title", "description", "url", "columns", "common_queries"],
       
    // For each table, also use context from common queries and these fields of the queries: 

    "child_objects": {
         "common_queries": {
             "fields": ['title', 'description', 'content', 'url']
              }
          }
  }
}

This structure translates to:

Retrieve information primarily about table objects. For each table retrieved, also include information about its common queries, returning the title, description, content, and the URL fields for those queries.

Query object type

mentioned_tables

To further specify the table fields returned in the response for mentioned tables, use the mentioned_tables key within the child_objects key of the query object.

Include this key only if you’ve also specified mentioned_tables in either the fields_required or fields_optional keys of your signature for the query object.

For even more detailed control, you can nest another child_objects key under mentioned_tables and specify columns as a child object. The structure of the mentioned_tables object mirrors that of the table object, allowing you to define which fields to include for columns within mentioned tables.

📘

Note

The common_queries key is not supported under mentioned_tables and cannot be used at this level of nesting.

In summary:

• If mentioned_tables is included in either fields_required or fields_optional and in child_objects, you will receive the mentioned tables in the response, with the specified fields as defined in the nested structure.
• If mentioned_tables is included only in fields_required or fields_optional, but not in child_objects, the response will include mentioned tables with the default set of table fields.
• If mentioned_tables is included only in child_objects, but not in fields_required or fields_optional, the response will not include mentioned tables, as they were not explicitly requested in any of the fields_ keys. This is considered an invalid query format.

Use the following format:

{
"query": {
    "fields_required": ["title", "description", "content", "mentioned_tables"],
    "child_objects": {
         "mentioned_tables": {
             "fields": ["name", "title", "columns"],
             "child_objects": {
                "columns": {
                     "fields": ["name", "data_type", "sample_values"]
                      }
                  }
              }
     }
  }
}

This structure translates to:

Retrieve information about query objects. For each query retrieved, return the required fields, also including information about the tables mentioned in the query, returning the name, title, and child columns. For the child columns of mentioned queries, return the fields name, data type, and sample values.

Full Signature Template

Here's a full template you can use for constructing your own signature objects:

{
    "schema": {
        "fields_required": ["name", "title", "description", "url"],
        "fields_optional": [],
        "search_filters": {},         
    },
    "table": {
        "fields_required": ["name", "title", "description", "url"],
        "fields_optional": ["common_joins", "common_filters", "columns"],
        "child_objects": {},
        "search_filters": {}
    },
    "column": {
        "fields_required": ["name", "title", "data_type", "url"],
        "fields_optional": ["sample_values"],
        "search_filters": {}
    },
    "documentation": {
        "fields_required": ["title", "content", "url"],
        "fields_optional": [],
        "search_filters": {}
    },
    "query": {
        "fields_required": ["title", "description", "content", "url"],
        "fields_optional": [],
        "child_objects": {},
        "search_filters": {}
    }
}

Signature Examples

Tables Only

{
  "table": {
    "fields_required": ["name", "title", "description", "url"]
  }
}

This signature:

• Returns only table objects.
• Includes name, title, description, and url in every response as they're required fields.
• The fields_optional field isn't included, so every response will only include the required fields.
• Searches the entire catalog, as no search filters are included.

Tables with Dynamic Field Selection

{
  "table": {
    "fields_required": ["name", "title", "description", "url"],
    "fields_optional": ["common_joins", "common_filters"]
  }
}

This signature:

• Returns only table objects.
• Includes name, title, description, and url in every response as they're required fields.
• Intelligently includes common_joins and/or common_filters only when relevant to the user's question (for example, if a user asks What tables can be joined with the sales table?, the response will include the common_joins data).
• Searches the entire catalog, as no search filters are included.

Data Analyst Agent

{
  "table": {
    "fields_required": ["name", "title", "description", "url", "common_joins", "common_filters", "columns"],
    "search_filters": {
        "flags": ["Endorsement"],
        "fields": {
            "tag_ids": [123],
            "cf[10568]":["Certified"] 
          }
    },
    "child_objects": {
    "columns": {
        "fields": ["name", "data_type", "description", "sample_values"]
      }
    }
  },
  "query": {
    "fields_required": ["title", "description", "content", "url"],
    "search_filters": {
       "fields": {
         "tag_ids": [123]
       }
    }
  },
  "documentation": {
    "fields_required": ["title", "content", "url"],
    "search_filters": {
      "fields": {
        "tag_ids": [123] 
      }
    }
  }
}

This signature is optimized for analytical work by focusing on high-quality assets (endorsed and tagged) with complete metadata:

• Returns table, query, and documentation objects relevant to the question.

• For tables:

  • Includes comprehensive information like common_joins, common_filters and columns details.
  • Filters for only trusted (endorsed) tables with the specific tag ID =123 and the value Certified in the custom field with ID =10568.
  • For each table, includes detailed column information with sample_values.

• For queries and documentation objects:

  • Includes the complete content to provide analysis context.
  • Filters to only include objects with tag ID =123 .

Question and Answer Agent

{
  "schema": {
    "fields_required": ["name", "title", "description", "url"],
    "search_filters": {
      "domain_ids": [123]
    }
  },
  "table": {
    "fields_required": ["name", "title", "description", "url"],
    "fields_optional": ["common_joins", "common_filters", "columns"],
    "search_filters": {
      "domain_ids": [123]
    },
    "child_objects": {
      "columns": {
        "fields": ["name", "data_type", "description", "sample_values"]
      }
    }
  },
  "column": {
    "fields_required": ["name", "title", "data_type", "url"],
    "fields_optional": ["description", "sample_values"]
  },
  "documentation": {
    "fields_required": ["title", "content", "url"],
     "search_filters": {
      "domain_ids": [123]
    }
  },
  "query": {
    "fields_required": ["title", "description", "content", "url"],
    "search_filters": {
      "domain_ids": [123]
    }
  }
}

This signature:

• Is designed for building a Question & Answer system focused on a specific business domain (domain ID =123), ensuring all responses remain relevant to that particular subject area.
• Supports comprehensive questions and answers by including all major object types (schema, table, column, documentation, and query). It's important to note that the Alation API will return only the relevant object types for each question, not all types in every response. This means that the search will look across schemas, tables, columns, documentation, and queries. But or any given question, it will only return the types that are relevant to that specific context.
• Uses optional fields for tables and columns to provide dynamic responses based on the context of the question.

Construct an Effective Signature Step by Step

• Step 1: Identify the Object Types you Need
• Step 2: Define Required and Optional Fields for Each Object
• Step 3: Add Search Filters (Optional)
• Step 4: Add Child Objects (Optional)
• Step 5: Combine into a Signature Object
• Step 6: Validate and Test
• Step 7: Iterate to Optimize

Step 1: Identify the Object Types you Need

Start by deciding which types of supported catalog objects your application or agent needs to process.

Step 2: Define Required and Optional Fields for Each Object

Each object type in the Aggregated Context API supports a defined set of fields. For each object type:

• Use fields_required to specify fields that must always be included in the response (for example, name and description). This provides a predictable and repeatable structure of the response, which can be important in AI application development where consistent output is the goal.

• Use fields_optional for fields that are helpful but not essential (for example, sample_values, common_joins). These fields can enrich responses, but since their availability varies, they may appear inconsistently or more frequently than expected.

If both fields_required and fields_optional are left empty, the API falls back to default fields. This is acceptable in exploratory or low-stakes scenarios, but including at least fields_required is strongly recommended for more controlled and stable behavior.

📘

Best practice

Use fields_required for the core fields your application depends on. Add only a small number of carefully selected fields to fields_optional if you need additional context.

Example:

{
"table":{
    "fields_required": ["name", "title", "description", "url"],
    "fields_optional": ["common_joins", "columns"]
}
}

Step 3: Add Search Filters (Optional)

Use search_filters to scope your context query to specific slices of the catalog.

You can filter by:

• Domains: For example, restrict the context to catalog metadata from a particular domain only
• Custom fields: For example, filter on specific custom field with specific values only
• Tags: For example, restrict the context to objects with a specific tag only
• Flags: For example, restrict to “Endorsed” objects only

Constructing search filters within the signature requires that you know the system IDs of the entities that you include into the search filters.

You can find out the domain IDs, custom field IDs, and tag IDs from your Alation catalog user interface. Flag values are fixed system values.

• Find out the Domain ID
• Find out the Custom Field ID
• Find out the Tag ID
• Flag Values to Use
• Example of a Search Filter

Find out the Domain ID

1. Log in to Alation.

2. Use the left-side navigation to select the domain you need. The catalog page of the domain will open. (Do not use the drop down at the top of the page where you can select My domains Only.)

3. Look at the URL. It includes the domain ID. For example, in the URL https://my_catalog.com/app/domain/36/overview, 36 is the domain ID.

4. Make a note of this ID value, along with the domain name. For example:

   Domain name: Alation Discovery Series
   ID = 36

5 Repeat the search for each domain you want to include into the signature.

📘

Alternatively:

You can use the Get Domains API to retrieve a list of all domains and their IDs. This endpoint is accessible to users with the Catalog Admin and Server Admin roles.

Find out the Custom Field ID

1. Log in to Alation.

2. Click into the Search bar and hit return. The full-page Search page will open.

3. Under Filters in the left-side filter panel, locate or add the custom field you need.

4. Select a field value. For example, in the screenshot below, the Bank Details value of the Categories of Personal Data custom field is selected.

   

5. After you select a value, the Search results page will update, only displaying matching objects.

6. Look at the URL field. The field ID will be included in the encoded URL. For example, in the URL like: https://my_catalog.com/app/full_search?limit=25&row_num=0&results_view=list&filters=%7B%22fields%22%3A%7B%22cf%5B10578%5D%22%3A%5B%22Bank+Details%22%5D%7D%7D, the encoded custom field ID is %22cf%5B10578%5D%22%3A%5B%22.

7. Use URL decoder software of your choice to retrieve the field ID. In the example above, it's 10578.

8. Make a note of the ID value, along with the field name. For example:

   Custom field: Categories of Personal Data
   ID = 10578
   Available values: Bank Details, Contact Details, Employment History

9. Repeat the search for each custom field you want to include into the signature.

📘

Alternatively:

If you are a Server or Catalog Admin, you can use the GET endpoint of the Custom Fields API to see which fields are available and what the field IDs are: <base_instance_URL>/integration/v2/custom_field/?values=id,name_singular&limit=1000.

Find out the Tag ID

1. Log in to Alation.

2. In the Search bar, type the keyword for the tag you're interested in and hit return. The Search results page will open.

3. Under Filters in the left-side filter panel, expand the Object Types filter.

4. Select the Tag object type. The Search results page will update to only display tag objects.

   

5. Click the tag you want the ID for. The catalog page of this object will open.

6. Look at the URL. The number after /tag/ is the tag ID. For example, in the URL https://my_catalog.com/app/tag/1/overview, 1 is the ID of this tag.

7. Make a note of this ID, with the tag name for reference. For example:

   Tag: healthcare
   ID = 1

8. Repeat the search for other tags you need.

📘

Alternatively:

In your Alation catalog, locate a catalog object that has the desired tag applied. Click the tag name to open its detail page. The URL will include the tag's unique ID.

Flag Values to Use

To create a search filter by flags, use these values:

• "Endorsement" for the endorsement flag
• "Deprecation" for the deprecation flag
• "Warning" for the warning flag in the Classic User Experience or the Important Info flag in the New User Experience.

The values are case-sensitive as should be used as shown below. You can include one or multiple values into the filter:

One flag:

{
   "search_filters":{
     "flags":["Endorsement"]
     }
}

Multiple flags:

{
   "search_filters":{
     "flags":["Endorsement","Deprecation","Warning"]
     }
}

📘

Alternatively:

Listing all three flag types ("Endorsement","Deprecation","Warning") will not return all objects. It will only return objects that have one or more of these flags applied. Any object without a flag will be excluded from the results.

Example of a Search Filter

The example below shows multiple keys and values used in the search_filters key. (This example is intended as an illustration to demonstrate format and structure. It's not meant to reflect a typical or recommended use case. In practice, most configurations will use a smaller, more focused set of options.)

{
   "search_filters":{
      "domain_ids":[10, 11, 12],        
      "fields": {
        "tag_ids":[1, 10, 20],
        "cf[10559]":["Candidate", "Done"],
        "cf[10558]":["In review", "Approved"],
        "cf[10557]":["Yes"]
        },
      "flags":["Endorsement","Warning"]
    }
}

Step 4: Add Child Objects (Optional)

If the responses can potentially include a lot of nested (child) objects, you can specify which fields to return for those child objects using child_objects. Use the child_objects key to potentially reduce token usage and improve response precision.

{
  "table": {
    "fields_required": ["name", "columns"],
    "child_objects": {
    "columns": {
      "fields": ["name", "data_type", "sample_values"]
    }
    }
  }
}

Step 5: Combine into a Signature Object

Structure your final signature as a top-level JSON object with each configured object type as a key.

Example: Full Signature

{
  "schema": {
    "fields_required": ["name", "title", "description", "url"]
  },
  "table": {
    "fields_required": ["name", "title", "description", "url"],
    "fields_optional": ["common_joins", "columns"],
    "search_filters":{
      "fields":{
        "tag_ids": [1]
        }
      },
    "child_objects": {
      "columns": {
        "fields": ["name", "data_type"]
      }
    }
  },
  "column": {
    "fields_required": ["name", "title", "data_type", "url"]
  }
}

Step 6: Validate and Test

Before deploying, validate your signature by:

• Checking if all required fields are present
• Running a test call against the Aggregated Context API
• Reviewing if filtering behaves as expected
• Monitoring response size and performance

Step 7: Iterate to Optimize

Once you've finalized your signature:

• Save reusable templates for different use cases
• Tune filters as your catalog grows
• Revisit fields periodically as new metadata types or fields are added to Alation