# Schema for type definitions
<a name="schema-for-type-definitions"></a>

The following sections detail the schema used for type definitions.

## $id
<a name="definition-schema-id"></a>

The $id element identifies the schema definition. It must follow this structure:
+ Start with the `/schema-versions/` URI prefix
+ Include the `definition` schema type
+ Use a forward slash (`/`) as a URI path separator
+ Include the schema identity, with fragments separated by periods (`.`)
+ Use the `@` character to separate the schema ID and version
+ End with the semver version, using periods (`.`) to separate version fragments

The schema identity must start with a root namespace that is 3-12 characters long, followed by an optional sub-namespace and name.

The semver version includes a MAJOR version (up to 3 digits), a MINOR version (up to 3 digits), and an optional PATCH version (up to 4 digits).

**Note**  
You can't use the reserved namespaces `aws` or `matter`

**Example $id**  

```
/schema-version/capability/aws.Recording@1.0
```

## $ref
<a name="definition-schema-ref"></a>

The $ref`` element references an existing type definition within the system. It follows the same constraints as the `$id` element.

**Note**  
A type definition or capability must exist with the value provided in the `$ref` file.

**Example $ref**  

```
/schema-version/definition/aws.capability@1.0
```

## name
<a name="definition-schema-name"></a>

The name element is a string representing the entity name in the schema document. It often contains abbreviations and must follow these rules:
+ Contain only alphanumeric characters, periods (.), forward slashes (/), hyphens (-), and spaces
+ Start with a letter
+ Maximum of 192 characters

The name element is used in the Amazon Web Services console UI and documentation.

**Example names**  

```
Door Lock
On/Off
Wi-Fi Network Management
PM2.5 Concentration Measurement
RTCSessionController
Energy EVSE
```

## title
<a name="definition-schema-title"></a>

The title element is a descriptive string for the entity represented by the schema document. It can contain any characters and is used in documentation.

**Example titles**  

```
Real-time Communication (RTC) Session Controller
Energy EVSE Capability
```

## description
<a name="definition-schema-description"></a>

The `description` element provides a detailed explanation of the entity represented by the schema document. It can contain any characters and is used in documentation.

**Example description**  

```
Electric Vehicle Supply Equipment (EVSE) is equipment used to charge an Electric Vehicle (EV) or Plug-In Hybrid Electric Vehicle. 
            This capability provides an interface to the functionality of Electric Vehicle Supply Equipment (EVSE) management.
```

## extrinsicId
<a name="definition-schema-extrinsicid"></a>

The `extrinsicId` element represents an identifier managed outside of the Amazon Web Services IoT system. For Matter capabilities, it maps to `clusterId`, `attributeId`, `commandId`, `eventId`, or `fieldId`, depending on the context.

The `extrinsicId` can be either a stringified decimal integer (1-10 digits) or a stringified hexadecimal integer (0x or 0X prefix, followed by 1-8 hexadecimal digits).

**Note**  
For AWS, the Vendor ID (VID) is 0x1577, and for Matter, it is 0. The system ensures that custom schemas don't use these reserved VIDs for capabilities.

**Example extrinsicIds**  

```
0018
0x001A
0x15771002
```

## extrinsicProperties
<a name="definition-schema-extrinsicproperties"></a>

The `extrinsicProperties` element contains a set of properties defined in an external system but maintained within the data model. For Matter capabilities, it maps to different unmodeled or partially modeled elements within ZCL cluster, attribute, command, or event.

Extrinsic Properties must follow these constraints:
+ Property names must be alphanumeric without spaces or special characters
+ Property values can be any JSON schema values
+ Maximum of 20 properties

The system supports various `extrinsicProperties`, including `access`, `apiMaturity`, `cli`, `cliFunctionName`, and others. These properties facilitate ACL to AWS (and vice versa) data model transformations.

**Note**  
Extrinsic properties are supported for the `action`, `event`, `property`, and `struct` fields elements of a capability, but not for the capability or cluster itself.