Edit an interface definition（编辑接口定义）

:::callout{theme="warning" title="Breaking" changes} Given that interfaces expose API names, any change to an interface definition has the potential to break downstream applications and will necessarily break existing object implementations. When adding a new required property, link type constraint, or action type constraint to an interface, all implementations for object types that use the interface must be made in the same update to your Ontology. We also recommend updating your interface definitions and consumers at the same time.

If your downstream applications cannot be updated at the same time as interface changes, you can alternatively create a new version of the interface (as an extension or a standalone interface) and migrate to the new interface definition as soon as possible. :::

Add new properties

From the Properties tab of the interface configuration, choose New property. This will open an interface property configuration side panel.

The available options for editing property metadata are clustered into four different tabs which give access to the following configurations:

1. Display name and description: Select into the existing display name or description to edit the text.
2. API name: Select into the existing API name to change its value.
3. Property base type: Select the property’s base type from the dropdown menu. The type of the property constrains the possible set of operations that can be done on the property’s values.
4. For example, a property with base type timestamp can be shown in a timeline widget in Object Explorer.
5. Primary key constraint: Indicate whether a property should be a primary key or cannot be a primary key.

:::callout{theme="warning"} If you make a change to the interface property types, you must also update all object types implementing this interface. :::

1. Type classes: Apply type classes as additional metadata that can be interpreted by applications.
2. Review the type classes documentation for a list of available type classes.
3. Render hints: Improve how a property value is rendered and indexed into Object Storage V1 (Phonograph) by selecting render hints from the checklist.
4. See the render hints documentation for descriptions of the available render hints.
5. Visibility: Select the existing visibility to open a dropdown menu of available visibilities. A prominent property will lead applications to show this property first to users. A hidden property will not appear in user applications.

Add shared properties

From the Properties tab of the interface configuration, select Add shared properties and choose a shared property to add to the interface.

Add a link type constraint

From the Link type constraints tab, select Create new link type constraint and add the necessary constraint metadata.

Add an action type constraint

From the Action type constraints tab, select Create new action type constraint and add the necessary constraint metadata and parameter constraints.

Remove properties

From the Properties tab, select ... next to the property you wish to remove from the interface. Alternatively, open the interface property side panel and select the trash icon in the upper right corner.

Remove or edit link type constraints

From the Link type constraint tab, select ... next to the link type constraint you wish to edit or remove from the interface.

If editing a constraint, you can update the metadata as you would if you were creating the link type constraint for the first time.

Remove or edit action type constraints

From the Action type constraints tab, select ... next to the action type constraint you wish to edit or remove from the interface.

If editing a constraint, you can update the metadata and parameter configuration as you would if you were creating the action type constraint for the first time.

---

中文翻译

编辑接口定义

:::callout{theme="warning" title="破坏性" 变更} 由于接口会暴露 API 名称（API names），对接口定义的任何更改都可能破坏下游应用程序，并且必然会破坏现有的对象实现。在向接口添加新的必需属性、链接类型约束（link type constraint）或操作类型约束（action type constraint）时，使用该接口的所有对象类型的实现必须在对本体（Ontology）的同一更新中完成。我们还建议同时更新接口定义及其消费者。

如果无法在接口变更的同时更新下游应用程序，您也可以创建接口的新版本（作为扩展或独立接口），并尽快迁移到新的接口定义。 :::

添加新属性

在接口配置的属性（Properties）选项卡中，选择新建属性（New property）。这将打开一个接口属性配置侧面板。

编辑属性元数据的可用选项分为四个不同的选项卡，可访问以下配置：

1. 显示名称和描述： 选择现有的显示名称或描述以编辑文本。
2. API 名称： 选择现有的 API 名称以更改其值。
3. 属性基础类型： 从下拉菜单中选择属性的基础类型。属性的类型限制了可对属性值执行的操作集。
4. 例如，基础类型为 timestamp 的属性可以在对象浏览器（Object Explorer）的时间轴小部件中显示。
5. 主键约束： 指示属性是否应作为主键或不能作为主键。

:::callout{theme="warning"} 如果更改了接口属性类型，还必须更新所有实现此接口的对象类型。 :::

1. 类型类： 应用类型类作为可由应用程序解释的附加元数据。
2. 请查阅类型类文档以获取可用类型类的列表。
3. 渲染提示： 通过从清单中选择渲染提示，改善属性值在对象存储 V1（Phonograph）中的渲染和索引方式。
4. 请参阅渲染提示文档以了解可用渲染提示的描述。
5. 可见性： 选择现有可见性以打开可用可见性的下拉菜单。prominent（突出）属性将引导应用程序优先向用户显示此属性。hidden（隐藏）属性将不会出现在用户应用程序中。

添加共享属性

在接口配置的属性选项卡中，选择添加共享属性（Add shared properties），然后选择要添加到接口的共享属性。

添加链接类型约束

在链接类型约束（Link type constraints）选项卡中，选择创建新的链接类型约束（Create new link type constraint），并添加必要的约束元数据。

添加操作类型约束

在操作类型约束（Action type constraints）选项卡中，选择创建新的操作类型约束（Create new action type constraint），并添加必要的约束元数据和参数约束。

移除属性

在属性选项卡中，选择要移除属性旁边的...。或者，打开接口属性侧面板，然后选择右上角的垃圾桶图标。

移除或编辑链接类型约束

在链接类型约束选项卡中，选择要编辑或移除的链接类型约束旁边的...。

如果编辑约束，您可以像首次创建链接类型约束时一样更新元数据。

移除或编辑操作类型约束

在操作类型约束选项卡中，选择要编辑或移除的操作类型约束旁边的...。

如果编辑约束，您可以像首次创建操作类型约束时一样更新元数据和参数配置。