기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 기능 스키마 문서에서 유형 정의 빌드 및 사용
<a name="type-definitions"></a>

스키마의 모든 요소는 유형 정의로 확인됩니다. 이러한 유형 정의는 *기본 유형 정의*(예: 부울, 문자열, 숫자) 또는 *네임스페이스 유형 정의*(편의를 위해 기본 유형 정의로 구축된 유형 정의)입니다.

사용자 지정 스키마를 정의할 때 기본 정의와 네임스페이스 유형 정의를 모두 사용할 수 있습니다.

**Contents**
+ [기본 유형 정의](#primitive-type-definitions)
  + [부울](#boolean-types)
  + [정수 유형 지원](#integers-support)
  + [숫자](#numbers)
  + [문자열](#strings)
  + [NULL](#nulls)
  + [배열](#arrays)
  + [Objects](#objects)
+ [네임스페이스 형식 정의](#namespaced-type-definitions)
  + [`matter` 유형](#matter-types)
  + [`aws` 유형](#aws-types)
    + [비트맵 유형 정의](#bitmap-type-definition)
    + [열거형 유형 정의](#enum-type-definition)

## 기본 유형 정의
<a name="primitive-type-definitions"></a>

기본 유형 정의는 관리형 통합에 정의된 모든 유형 정의의 구성 요소입니다. 사용자 지정 유형 정의를 포함한 모든 네임스페이스 정의는 `$ref` 키워드 또는 `type` 키워드를 통해 기본 유형 정의로 해석됩니다.

모든 프리미티브 유형은 `nullable` 키워드를 사용하여 null이 가능하며 키워드를 사용하여 모든 프리미티브 유형을 식별할 수 있습니다`type`.

### 부울
<a name="boolean-types"></a>

부울 유형은 기본값을 지원합니다.

샘플 정의:

```
{
    "type" : "boolean",
    "default" : "false",
    "nullable" : true
}
```

### 정수 유형 지원
<a name="integers-support"></a>



정수 유형은 다음을 지원합니다.
+ `default` 값
+ `maximum` 값
+ `minimum` 값
+ `exclusiveMaximum` 값
+ `exclusiveMinimum` 값
+ `multipleOf` 값

`x`가 검증 중인 값인 경우 다음이 true여야 합니다.
+ `x` ≥ `minimum`
+ `x` > `exclusiveMinimum`
+ `x` < `exclusiveMaximum`

**참고**  
소수 부분이 0인 숫자는 정수로 간주되지만 부동 소수점 숫자는 거부됩니다.  

```
1.0 // Schema-Compliant
3.1415926 // NOT Schema-Compliant
```

`minimum` 및를 둘 다 지정`exclusiveMinimum`하거나 `maximum` 및를 둘 다 지정할 수 있지만 둘 다 동시에 사용하지 않는 `exclusiveMaximum`것이 좋습니다.

샘플 정의:

```
{
    "type" : "integer",
    "default" : 2,
    "nullable" : true,
    "maximum" : 10,
    "minimum" : 0,
    "multipleOf": 2
}
```

대체 정의:

```
{
    "type" : "integer",
    "default" : 2,
    "nullable" : true,
    "exclusiveMaximum" : 11,
    "exclusiveMinimum" : -1,
    "multipleOf": 2
}
```

### 숫자
<a name="numbers"></a>

정수 및 부동 소수점 숫자를 포함하여 모든 숫자 유형에 숫자 유형을 사용합니다.

숫자 유형은 다음을 지원합니다.
+ `default` 값
+ `maximum` 값
+ `minimum` 값
+ `exclusiveMaximum` 값
+ `exclusiveMinimum` 값
+ `multipleOf` 값입니다. 배수는 부동 소수점 숫자일 수 있습니다.

`x`가 검증 중인 값인 경우 다음이 true여야 합니다.
+ `x` ≥ `minimum`
+ `x` > `exclusiveMinimum`
+ `x` < `exclusiveMaximum`

`minimum` 및를 둘 다 지정`exclusiveMinimum`하거나 `maximum` 및를 둘 다 지정할 수 있지만 둘 다 동시에 사용하지 않는 `exclusiveMaximum`것이 좋습니다.

샘플 정의:

```
{
    "type" : "number",
    "default" : 0.4,
    "nullable" : true,
    "maximum" : 10.2,
    "minimum" : 0.2,
    "multipleOf": 0.2
}
```

대체 정의:

```
{
    "type" : "number",
    "default" : 0.4,
    "nullable" : true,
    "exclusiveMaximum" : 10.2,
    "exclusiveMinimum" : 0.2,
    "multipleOf": 0.2
}
```

### 문자열
<a name="strings"></a>

문자열 유형은 다음을 지원합니다.
+ `default` 값
+ `maxLength` 및 `minLength` 값을 포함한 길이 제약 조건(음수가 아닌 숫자여야 함)
+ `pattern` 정규식 값

정규식을 정의하면 표현식이 문자열 내 어느 곳에서든 일치하는 경우 문자열이 유효합니다. 예를 들어 정규식은 문자열 "p"뿐만 아니라 "apple"과 같은 p를 포함하는 모든 문자열과 `p` 일치합니다. 명확성을 위해 특정 이유가 없는 한 `^...$` (예: `^p$`)를 사용하여 정규 표현식을 둘러싸는 것이 좋습니다.

샘플 정의:

```
{
    "type" : "string",
    "default" : "defaultString",
    "nullable" : true,
    "maxLength": 10,
    "minLength": 1,
    "pattern" : "^([0-9a-fA-F]{2})+$"
}
```

### NULL
<a name="nulls"></a>

Null 유형은 단일 값 만 허용합니다`null`.

샘플 정의:

```
{ "type": "null" }
```

### 배열
<a name="arrays"></a>

배열 유형은 다음을 지원합니다.
+ `default` - 기본값으로 사용할 목록입니다.
+ `items` - 모든 배열 요소에 적용되는 JSON 유형 정의입니다.
+ 길이 제약 조건(음수가 아닌 숫자여야 함)
  + `minItems`
  + `maxItems`
+ `pattern` 정규식 값
+ `uniqueItems` - 배열의 요소가 고유해야 하는지 여부를 나타내는 부울입니다.
+ `prefixItems` - 각 항목이 문서 배열의 각 인덱스에 해당하는 스키마인 배열입니다. 즉, 첫 번째 요소가 입력 배열의 첫 번째 요소를 검증하고 두 번째 요소가 입력 배열의 두 번째 요소를 검증하는 배열입니다.

샘플 정의:

```
{
   "type": "array",
   "default": ["1", "2"],
   "items" : {
        "type": "string",
        "pattern": "^([a-zA-Z0-9_ -/]+)$"
    },
    "minItems" : 1,
    "maxItems": 4,
    "uniqueItems" : true,
}
```

배열 검증의 예:

```
//Examples:
["1", "2", "3", "4"] // Schema-Compliant
[]                   // NOT Schema-Compliant: minItems=1
["1", "1"]           // NOT Schema-Compliant: uniqueItems=true
["{"]                // NOT Schema-Compliant: Does not match the RegEx pattern.
```

튜플 검증을 사용한 대체 정의:

```
{
    "type": "array",
    "prefixItems": [
        { "type": "number" },
        { "type": "string" },
        { "enum": ["Street", "Avenue", "Boulevard"] },
        { "enum": ["NW", "NE", "SW", "SE"] }
    ]
}
          
//Examples:
[1600, "Pennsylvania", "Avenue", "NW"]               // Schema-Compliant

// And, by default, it's also okay to add additional items to end:
[1600, "Pennsylvania", "Avenue", "NW", "Washington"] // Schema-Compliant
```

### Objects
<a name="objects"></a>

객체 유형은 다음을 지원합니다.
+ 속성 제약 조건
  + `properties` - `properties`키워드를 사용하여 객체의 속성(키-값 페어)을 정의합니다. 의 값은 객체`properties`입니다. 여기서 각 키는 속성의 이름이고 각 값은 해당 속성을 검증하는 데 사용되는 스키마입니다. `properties` 키워드의 속성 이름과 일치하지 않는 속성은이 키워드에서 무시됩니다.
  + `required` - 기본적으로 `properties` 키워드로 정의된 속성은 필요하지 않습니다. 그러나 `required` 키워드를 사용하여 필요한 속성 목록을 제공할 수 있습니다. `required` 키워드는 0개 이상의 문자열 배열을 사용합니다. 이러한 각 문자열은 고유해야 합니다.
  + `propertyNames` -이 키워드를 사용하면 속성 이름에 대한 RegEx 패턴을 제어할 수 있습니다. 예를 들어 객체의 모든 속성이 특정 규칙에 따라 이름을 갖도록 적용할 수 있습니다.
  + `patternProperties` - 정규식을 스키마에 매핑합니다. 속성 이름이 지정된 정규식과 일치하는 경우 속성 값은 해당 스키마에 대해 검증되어야 합니다. 예를 들어, `patternProperties`를 사용하여 특정 종류의 속성 이름을 지정하면 값이 특정 스키마와 일치해야 합니다.
  + `additionalProperties` -이 키워드는 추가 속성이 처리되는 방식을 제어합니다. 추가 속성은 속성 키워드에 이름이 나열되지 않거나의 정규식과 일치하는 속성입니다`patternProperties`. 기본적으로 추가 속성이 허용됩니다. 이 필드를 로 설정`false`하면 추가 속성이 허용되지 않습니다.
  + `unevaluatedProperties` -이 키워드는 하위 스키마에 선언된 속성을 인식할 수 있다는 점을 `additionalProperties` 제외하면와 유사합니다.는 스키마를 처리할 때 성공적으로 검증되고 허용된 속성 목록으로 사용하는 속성을 수집하여 `unevaluatedProperties` 작동합니다. 이렇게 하면 조건부로 속성을 추가하는 등 더 복잡한 작업을 수행할 수 있습니다. 자세한 내용은 아래 예제를 참조하세요.
+ `anyOf` -이 키워드의 값은 비어 있지 않은 배열이어야 합니다. 배열의 각 항목은 유효한 JSON 스키마여야 합니다. 인스턴스는이 키워드의 값으로 정의된 *하나 이상의* 스키마에 대해 성공적으로 검증되는 경우이 키워드에 대해 성공적으로 검증됩니다.
+ `oneOf` -이 키워드의 값은 비어 있지 않은 배열이어야 합니다. 배열의 각 항목은 유효한 JSON 스키마여야 합니다. 인스턴스는이 키워드의 값으로 정의된 *정확히* 하나의 스키마에 대해 성공적으로 검증되는 경우이 키워드에 대해 성공적으로 검증됩니다.

필수 예:

```
{
  "type": "object",
  "required": ["test"]
}

// Schema Compliant
{
  "test": 4
}

// NOT Schema Compliant
{}
```

PropertyNames 예제:

```
{
  "type": "object",
  "propertyNames": {
    "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
  }
}

// Schema Compliant
{
  "_a_valid_property_name_001": "value"
}

// NOT Schema Compliant
{
  "001 invalid": "value"
}
```

PatternProperties 예제:

```
{
  "type": "object",
  "patternProperties": {
    "^S_": { "type": "string" },
    "^I_": { "type": "integer" }
  }
}

// Schema Compliant
{ "S_25": "This is a string" }
{ "I_0": 42 }

// NOT Schema Compliant
{ "S_0": 42 } // Value must be a string
{ "I_42": "This is a string" } // Value must be an integer
```

AdditionalProperties 예제:

```
{
  "type": "object",
  "properties": {
    "test": {
        "type": "string"
    }
  },
  "additionalProperties": false
}

// Schema Compliant
{
  "test": "value"
}
OR
{}

// NOT Schema Compliant
{
    "notAllowed": false
}
```

UnevaluatedProperties 예제:

```
{
  "type": "object",
  "properties": {
    "standard_field": { "type": "string" }
  },
  "patternProperties": {
    "^@": { "type": "integer" } // Allows properties starting with '@'
  },
  "unevaluatedProperties": false // No other properties allowed
}

// Schema Compliant
{
  "standard_field": "some value",
  "@id": 123,
  "@timestamp": 1678886400
}
// This passes because "standard_field" is evaluated by properties, 
// "@id" and "@timestamp" are evaluated by patternProperties, 
// and no other properties remain unevaluated.

// NOT Schema Compliant
{
  "standard_field": "some value",
  "another_field": "unallowed"
}
// This fails because "another_field" is unevaluated and doesn't match 
// the @ pattern, leading to a violation of unevaluatedProperties: false
```

AnyOf 예제:

```
{
  "anyOf": [
    { "type": "string", "maxLength": 5 },
    { "type": "number", "minimum": 0 }
  ]
}

// Schema Compliant
"short"
12

// NOT Schema Compliant
"too long"
-5
```

OneOf 예제:

```
{
  "oneOf": [
    { "type": "number", "multipleOf": 5 },
    { "type": "number", "multipleOf": 3 }
  ]
}

// Schema Compliant
10
9

// NOT Schema compliant
2  // Not a multiple of either 5 or 3
15 // Multiple of both 5 and 3 is rejected.
```

## 네임스페이스 형식 정의
<a name="namespaced-type-definitions"></a>

네임스페이스 유형 정의는 기본 유형으로 빌드된 유형입니다. 이러한 유형은 `{{namespace}}.{{typename}}.` 관리형 통합이 `aws` 및 `matter` 네임스페이스 아래에 사전 정의된 유형을 제공하는 형식을 따라야 합니다. 예약 및 네임스페이스를 제외한 모든 `aws` `matter` 네임스페이스를 사용자 지정 유형에 사용할 수 있습니다.

사용 가능한 네임스페이스 유형 정의를 찾으려면 `Type` 필터가 로 설정된 [ListSchemaVersions](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListSchemaVersions.html) API를 사용합니다`definition`.

### `matter` 유형
<a name="matter-types"></a>

필터가 로 설정`matter`되고 `Namespace` 필터가 `Type` 로 설정된 [ListSchemaVersions](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListSchemaVersions.html) API를 사용하여 `matter` 네임스페이스에서 데이터 유형을 찾습니다`definition`.

### `aws` 유형
<a name="aws-types"></a>

필터가 로 설정`aws`되고 `Namespace` 필터가 `Type` 로 설정된 [ListSchemaVersions](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListSchemaVersions.html) API를 사용하여 `aws` 네임스페이스에서 데이터 유형을 찾습니다`definition`.

#### 비트맵 유형 정의
<a name="bitmap-type-definition"></a>

비트맵에는 두 가지 필수 속성이 있습니다.
+ `type` 객체여야 합니다.
+ `properties`는 각 비트 정의를 포함하는 객체여야 합니다. 각 비트는 속성`extrinsicId`이 및 인 객체입니다`value`. 각 비트의 값은 최소값이 0이고 최대값이 1 이상인 정수여야 합니다.

샘플 비트맵 정의:

```
{
    "title" : "Sample Bitmap Type",
    "description" : "Type definition for SampleBitmap.",
    "$ref" : "/schema-versions/definition/aws.bitmap@1.0 ",
    "type" : "object",
    "additionalProperties" : false,
    "properties" : {
        "Bit1" : {
            "extrinsicId" : "0x0000",
            "value" : {
                "type" : "integer",
                "maximum" : 1,
                "minimum" : 0
            }
        },
        "Bit2" : {
            "extrinsicId" : "0x0001",
            "value" : {
                "type" : "integer",
                "maximum" : 1,
                "minimum" : 0
            }
        }
    }
}
   
// Schema Compliant
{
    "Bit1": 1,
    "Bit1": 0
}

// NOT Schema Compliant
{
    "Bit1": -1,
    "Bit1": 0
}
```

#### 열거형 유형 정의
<a name="enum-type-definition"></a>

열거형에는 세 가지 속성이 필요합니다.
+ `type` 객체여야 합니다.
+ `enum`는 최소 하나의 항목이 있는 고유한 문자열의 배열이어야 합니다.
+ `extrinsicIdMap`는 열거형 값인 속성이 있는 객체입니다. 각 속성의 값은 열거형 값에 해당하는 외부 식별자여야 합니다.

샘플 열거형 정의:

```
{
    "title" : "SampleEnum Type",
    "description" : "Type definition for SampleEnum.",
    "$ref" : "/schema-versions/definition/aws.enum@1.0",
    "type" : "string",
    "enum" : [
        "EnumValue0",
        "EnumValue1",
        "EnumValue2"
    ],
    "extrinsicIdMap" : {
        "EnumValue0" : "0",
        "EnumValue1" : "1",
        "EnumValue2" : "2"
    }
}
              
// Schema Compliant
"EnumValue0"
"EnumValue1"
"EnumValue2"

// NOT Schema Compliant
"NotAnEnumValue"
```