ARTIFACT_ID：（可选）工件记录的 ID。如果未指定工件 ID，Vertex ML Metadata 会为此工件创建一个唯一标识符。
DISPLAY_NAME：（可选）用户定义的工件名称。
HTTP 方法和网址：
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-28。"],[],[],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)."]]
