Catalog schemas

A catalog schema is a JSON schema for the extra metadata that deployments of one type carry in the Catalog, such as a provider, a license, or a pricing table. A model, application, toolset, or interceptor that names a catalog schema must provide metadata that conforms to it; DIAL Core validates the metadata, stores it with the deployment, and returns it in its API responses. This reference is for platform engineers who register catalog schemas; it assumes you know how DIAL Core is configured.

To create catalog schemas and fill in metadata in the UI, see Catalog schemas in DIAL Admin.

Where catalog schemas are defined

Source	Location
Config file	catalogSchemas, an array of schemas
Configuration API	/v1/catalog_schemas/platform/<name>

Catalog schemas are matched by $id, like application type schemas: a blob replaces the file schema with the same $id, a PUT requires a unique $id that does not change, and a migrated file schema is named after the last path segment of its $id.

How a deployment uses a catalog schema

Field on the deployment	Description
catalog_schema_id	The $id of the catalog schema the deployment uses.
catalog_properties	The metadata values. They must conform to the schema.

A configuration in which a deployment's metadata does not conform to its catalog schema is rejected. A Configuration API write that breaks this rule answers 422.

DIAL schema properties

Every catalog schema conforms to Core's catalog meta-schema, https://dial.epam.com/catalog_schemas/schema#.

Property	Description
dial:catalogEntityType	The catalog entity type the schema applies to. DIAL Admin uses model, agent, toolset, and interceptor; applications use agent.
dial:catalogDisplayName	The human-readable name of the entity type.
dial:defaultLocale	The BCP-47 locale used as the fallback for every localized field. Optional; default en.

Annotations on each property:

Annotation	Description
dial:file	The value is a DIAL file, copied when the deployment is published or shared.
dial:meta.dial:tab	The tab the field renders in, for example Summary, About, Overview, Pricing, or API.
dial:meta.dial:section	The section within the tab, for example Capabilities or Specification.
dial:meta.dial:propertyOrder	The order of the field within its section.
dial:meta.dial:widget	A rendering hint for a generic catalog client.
dial:meta.dial:localized	The value is a map from BCP-47 locales to values.

The DIAL Chat catalog shows only some fields and ignores the layout hints; see Catalog schemas in DIAL Admin.

Endpoints

Endpoint	Returns
GET /v1/catalog_schemas/meta_schema	The catalog meta-schema
GET /v1/catalog_schemas/schemas	The registered catalog schemas
GET /v1/catalog_schemas/schema	One catalog schema, by its ID

Example

{
  "catalogSchemas": [
    {
      "$schema": "https://dial.epam.com/catalog_schemas/schema#",
      "$id": "https://mydial.example.com/catalog_schemas/model_metadata",
      "dial:catalogEntityType": "model",
      "dial:catalogDisplayName": "Model",
      "type": "object",
      "properties": {
        "provider": {
          "type": "string",
          "dial:meta": { "dial:tab": "Overview", "dial:propertyOrder": 1 }
        },
        "license": {
          "type": "string",
          "dial:meta": { "dial:tab": "Overview", "dial:propertyOrder": 2 }
        }
      }
    }
  ],
  "models": {
    "gpt-4o": {
      "type": "chat",
      "endpoint": "http://model-provider:5000/compat/openai/openai/deployments/gpt-4o/chat/completions",
      "catalog_schema_id": "https://mydial.example.com/catalog_schemas/model_metadata",
      "catalog_properties": { "provider": "OpenAI", "license": "Proprietary" }
    }
  }
}

Further reading

• Catalog schemas in DIAL Admin — create schemas and fill in metadata
• Application type schemas — the other kind of schema Core stores
• Configuration API — write schemas to the platform bucket