Stay organized with collections
Save and categorize content based on your preferences.
In addition to the predefined system schemas, Vertex ML Metadata provides
an extensible data model through custom schemas. Custom schemas are user-defined
MetadataSchemas. Use custom schemas to type check metadata properties and to
query resources by schema, for example,
"list all Artifacts of type MyCustomModel.
To define a custom schema, you must create a MetadataSchema resource within a
specific MetadataStore that describes the expected schema. The schema format is
a subset of the OpenAPI 3.0 specification{class: external},
with the restriction that the top-level schema must be of type object. All
OpenAPI 3.0 supported data types
(for example, integer, number, string, boolean, array, object) are supported as
properties of this top-level schema object. A restriction is that each field
under the properties section can be assigned to only one data type. Mixed types
are not supported. Advanced data requirements such as Minimum,
Maximum, Multiples, and string formats are also not supported.
How to register your own custom schemas
The process to create a custom MetadataSchema is similar to creating new
metadata resources. The following instructions show how to create a sample
MetadataSchema. MetadataSchemas are scoped only to their associated
MetadataStore.
REST
Before using any of the request data,
make the following replacements:
METADATA_STORE: The metadata store ID where the MetadataSchema is created.
The default metadata store is named default. Unless a new MetadataStore is required,
you can use the default store.
METADATA_SCHEMA_ID: (Optional) The ID of the MetadataSchema record. If the ID
is not specified, Vertex ML Metadata creates a unique identifier for this MetadataSchema
.
METADATA_SCHEMA_TITLE: The title of the schema that describes the metadata field. The title
of the schema must meet the format `.`. The namespace must start with a
lowercase letter, can contain lowercase characters and numbers, and can be two to twenty characters
long. The schema name must start with an uppercase letter, can include letters and numbers, and
can be two to fortynice characters long.
METADATA_SCHEMA_VERSION: (Optional) The version of the schema that describes the
metadata field. schema_version must be a string of three numbers separated by periods,
for example, 1.0.0, 1.0.1. This format helps order and compare versions..
METADATA_SCHEMA_TYPE: The type of metadata resource to which the created schema applies.
Types are: ARTIFACT_TYPE, EXECUTION_TYPE, or CONTEXT_TYPE.
METADATA_SCHEMA: The detailed schema to create.
DESCRIPTION: (Optional) A human readable string, that describes the purpose of the execution to be created..
ARTIFACT_ID: (Optional) The ID of the artifact record. If the artifact ID is not specified, Vertex ML Metadata creates a unique identifier for this artifact..
DISPLAY_NAME: (Optional) The user-defined name of the artifact..
HTTP method and URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
Save the request body in a file named request.json.
Run the following command in the terminal to create or overwrite
this file in the current directory:
Save the request body in a file named request.json.
Run the following command in the terminal to create or overwrite
this file in the current directory:
Subsequent calls to create, get, or list Artifacts can then refer to this schema
by specifying the name (demo.Artifact) in the schema_title field and version
(0.0.1) in the schema_version of the Artifact resource. For more information about
how to create, get, or list metadata resources, see
Track Vertex ML Metadata.
Version your schemas
All MetadataSchema resources are versioned. A user can create a schema that
uses the same schema_title as another schema but a different schema_version.
To create a metadataSchema resource with a different version, a user can
provide a different version number and modified schema content.
The following example creates a 0.0.2 version of the demo.Artifact schema:
sample_schema_versioned=aip.MetadataSchema()sample_schema_versioned.schema_type=aip.MetadataSchema.MetadataSchemaType.ARTIFACT_TYPEsample_schema_versioned.schema="title: demo.Artifact\ntype: object\nproperties:\n framework:\n type: string\n description: \"The framework type\"\n model_version:\n type: integer\n description: \"The version of the model\""sample_schema_versioned.schema_version="0.0.2"sample_schema_versioned.description="sample schema 2"store_client.create_metadata_schema(parent=metadata_store.name,metadata_schema=sample_schema_versioned)
Fields in the schema are always considered optional, so there is
no backward or forward compatibility between versions of the same
schema_title. Users can still use the schema_title to filter and group
resources for analysis. For more information about
how to use filter functions, see
Analyzing Vertex ML Metadata.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[],[],null,["# Create and use custom schemas\n\nIn addition to the predefined system schemas, Vertex ML Metadata provides\nan extensible data model through custom schemas. Custom schemas are user-defined\nMetadataSchemas. Use custom schemas to type check metadata properties and to\nquery resources by schema, for example,\n\"list all Artifacts of type `MyCustomModel`.\n\nTo define a custom schema, you must create a MetadataSchema resource within a\nspecific MetadataStore that describes the expected schema. The schema format is\na subset of the [OpenAPI 3.0 specification](https://swagger.io/specification/#schema-object){class: external},\nwith the restriction that the top-level schema must be of type `object`. All\nOpenAPI 3.0 supported [data types](https://swagger.io/docs/specification/data-models/data-types/)\n(for example, integer, number, string, boolean, array, object) are supported as\nproperties of this top-level schema object. A restriction is that each field\nunder the properties section can be assigned to only one data type. Mixed types\nare not supported. Advanced data requirements such as Minimum,\nMaximum, Multiples, and string formats are also not supported.\n| **Note:** Fields in the schema are always considered optional when the system performs type checking. When you create new metadata resources, you can still include fields that are not defined in the schema.\n\nHow to register your own custom schemas\n---------------------------------------\n\nThe process to create a custom MetadataSchema is similar to creating new\nmetadata resources. The following instructions show how to create a sample\nMetadataSchema. MetadataSchemas are scoped only to their associated\nMetadataStore. \n\n### REST\n\n\nBefore using any of the request data,\nmake the following replacements:\n\n- \u003cvar translate=\"no\"\u003eLOCATION_ID\u003c/var\u003e: The region of your MetadataStore.\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: Your [project ID](/resource-manager/docs/creating-managing-projects#identifiers) or number.\n- \u003cvar translate=\"no\"\u003eMETADATA_STORE\u003c/var\u003e: The metadata store ID where the MetadataSchema is created. The default metadata store is named `default`. Unless a new MetadataStore is required, you can use the default store.\n- \u003cvar translate=\"no\"\u003eMETADATA_SCHEMA_ID\u003c/var\u003e: (Optional) The ID of the MetadataSchema record. If the ID is not specified, Vertex ML Metadata creates a unique identifier for this MetadataSchema .\n- \u003cvar translate=\"no\"\u003eMETADATA_SCHEMA_TITLE\u003c/var\u003e: The title of the schema that describes the metadata field. The title of the schema must meet the format \\`.\\`. The namespace must start with a lowercase letter, can contain lowercase characters and numbers, and can be two to twenty characters long. The schema name must start with an uppercase letter, can include letters and numbers, and can be two to fortynice characters long.\n- \u003cvar translate=\"no\"\u003eMETADATA_SCHEMA_VERSION\u003c/var\u003e: (Optional) The version of the schema that describes the metadata field. `schema_version` must be a string of three numbers separated by periods, for example, 1.0.0, 1.0.1. This format helps order and compare versions..\n- \u003cvar translate=\"no\"\u003eMETADATA_SCHEMA_TYPE\u003c/var\u003e: The type of metadata resource to which the created schema applies. Types are: `ARTIFACT_TYPE`, `EXECUTION_TYPE`, or `CONTEXT_TYPE`.\n- \u003cvar translate=\"no\"\u003eMETADATA_SCHEMA\u003c/var\u003e: The detailed schema to create.\n- \u003cvar translate=\"no\"\u003eDESCRIPTION\u003c/var\u003e: (Optional) A human readable string, that describes the purpose of the execution to be created..\n- \u003cvar translate=\"no\"\u003eARTIFACT_ID\u003c/var\u003e: (Optional) The ID of the artifact record. If the artifact ID is not specified, Vertex ML Metadata creates a unique identifier for this artifact..\n- \u003cvar translate=\"no\"\u003eDISPLAY_NAME\u003c/var\u003e: (Optional) The user-defined name of the artifact..\n\n\nHTTP method and URL:\n\n```\nPOST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID\n```\n\n\nRequest JSON body:\n\n```\n{\n \"schemaVersion\": \"0.0.1\",\n \"schema\": \"title: test.Experiment\\ntype: object\",\n \"schemaType\": \"CONTEXT_TYPE\",\n}\n```\n\nTo send your request, expand one of these options:\n\n#### curl (Linux, macOS, or Cloud Shell)\n\n| **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) , or by using [Cloud Shell](/shell/docs), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\nSave the request body in a file named `request.json`.\nRun the following command in the terminal to create or overwrite\nthis file in the current directory: \n\n```\ncat \u003e request.json \u003c\u003c 'EOF'\n{\n \"schemaVersion\": \"0.0.1\",\n \"schema\": \"title: test.Experiment\\ntype: object\",\n \"schemaType\": \"CONTEXT_TYPE\",\n}\nEOF\n```\n\n\nThen execute the following command to send your REST request:\n\n```\ncurl -X POST \\\n -H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n -d @request.json \\\n \"https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID\"\n```\n\n#### PowerShell (Windows)\n\n| **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\nSave the request body in a file named `request.json`.\nRun the following command in the terminal to create or overwrite\nthis file in the current directory: \n\n```\n@'\n{\n \"schemaVersion\": \"0.0.1\",\n \"schema\": \"title: test.Experiment\\ntype: object\",\n \"schemaType\": \"CONTEXT_TYPE\",\n}\n'@ | Out-File -FilePath request.json -Encoding utf8\n```\n\n\nThen execute the following command to send your REST request:\n\n```\n$cred = gcloud auth print-access-token\n$headers = @{ \"Authorization\" = \"Bearer $cred\" }\n\nInvoke-WebRequest `\n -Method POST `\n -Headers $headers `\n -ContentType: \"application/json; charset=utf-8\" `\n -InFile request.json `\n -Uri \"https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID\" | Select-Object -Expand Content\n```\n\nYou should see output similar to the following. You can use the\n\u003cvar translate=\"no\"\u003eMETADATA_SCHEMA_ID\u003c/var\u003e is the ID of the MetadataSchema record.\n\n```\n{\n \"name\": \"projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas/METADATA_SCHEMA_ID\",\n \"schemaVersion\": \"0.0.1\",\n \"schema\": \"title: test.Experiment\\ntype: object\",\n \"schemaType\": \"CONTEXT_TYPE\",\n \"createTime\": \"2021-04-06T05:24:04.575481815Z\"\n}\n\n```\n\nSubsequent calls to create, get, or list Artifacts can then refer to this schema\nby specifying the name (demo.Artifact) in the schema_title field and version\n(0.0.1) in the schema_version of the Artifact resource. For more information about\nhow to create, get, or list metadata resources, see\n[Track Vertex ML Metadata](/vertex-ai/docs/ml-metadata/tracking).\n\nVersion your schemas\n--------------------\n\nAll MetadataSchema resources are versioned. A user can create a schema that\nuses the same schema_title as another schema but a different schema_version.\nTo create a metadataSchema resource with a different version, a user can\nprovide a different version number and modified schema content.\n\nThe following example creates a 0.0.2 version of the demo.Artifact schema: \n\n sample_schema_versioned = aip.MetadataSchema()\n sample_schema_versioned.schema_type = aip.MetadataSchema.MetadataSchemaType.ARTIFACT_TYPE\n sample_schema_versioned.schema =\"title: demo.Artifact\\ntype: object\\nproperties:\\n framework:\\n type: string\\n description: \\\"The framework type\\\"\\n model_version:\\n type: integer\\n description: \\\"The version of the model\\\"\"\n sample_schema_versioned.schema_version = \"0.0.2\"\n sample_schema_versioned.description = \"sample schema 2\"\n\n store_client.create_metadata_schema(parent=metadata_store.name, metadata_schema=sample_schema_versioned)\n\nFields in the schema are always considered optional, so there is\nno backward or forward compatibility between versions of the same\nschema_title. Users can still use the schema_title to filter and group\nresources for analysis. For more information about\nhow to use filter functions, see\n[Analyzing Vertex ML Metadata](/vertex-ai/docs/ml-metadata/analyzing).\n\nWhat's next\n-----------\n\n- [Get started tracking your Vertex ML Metadata](/vertex-ai/docs/ml-metadata/tracking)."]]
