Primitive Typdefinitionen Typdefinitionen mit Namespaces

Erstellung und Verwendung von Typdefinitionen in Capability-Schema-Dokumenten

Alle Elemente in den Schemas werden in Typdefinitionen aufgelöst. Bei diesen Typdefinitionen handelt es sich entweder um primitive Typdefinitionen (wie Boolesche Werte, Zeichenketten, Zahlen) oder um Typdefinitionen mit Namensräumen (Typdefinitionen, die der Einfachheit halber aus primitiven Typdefinitionen erstellt wurden).

Wenn Sie ein benutzerdefiniertes Schema definieren, können Sie sowohl primitive Definitionen als auch Namespace-Typdefinitionen verwenden.

Inhalt

Primitive Typdefinitionen

Primitive Typdefinitionen sind die Bausteine für alle Typdefinitionen, die in verwalteten Integrationen definiert sind. Alle Namespace-Definitionen, einschließlich benutzerdefinierter Typdefinitionen, werden entweder über das $ref Schlüsselwort oder das Schlüsselwort zu einer primitiven Typdefinition aufgelöst. type

Alle primitiven Typen können mithilfe des nullable Schlüsselworts auf Null gesetzt werden, und Sie können alle primitiven Typen mithilfe des Schlüsselworts identifizieren. type

Boolesche Werte

Boolesche Typen unterstützen Standardwerte.

Beispieldefinition:


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

Unterstützung für Integer-Typen

Integer-Typen unterstützen Folgendes:

default-Werte
maximum-Werte
minimum-Werte
exclusiveMaximum-Werte
exclusiveMinimum-Werte
multipleOf-Werte

Wenn x der Wert validiert wird, muss Folgendes zutreffen:

x ≥ minimum
x > exclusiveMinimum
x < exclusiveMaximum

Anmerkung

Zahlen mit einem Bruchteil von Null werden als ganze Zahlen betrachtet, Fließkommazahlen werden jedoch zurückgewiesen.


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

Sie können zwar sowohl als auch exclusiveMinimum oder beide minimum maximum und angebenexclusiveMaximum, wir empfehlen jedoch nicht, beide gleichzeitig zu verwenden.

Beispieldefinitionen:


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

Alternative Definition:


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

Zahlen

Verwenden Sie den Zahlentyp für jeden numerischen Typ, einschließlich Ganzzahlen und Fließkommazahlen.

Zahlentypen unterstützen Folgendes:

default-Werte
maximum-Werte
minimum-Werte
exclusiveMaximum-Werte
exclusiveMinimum-Werte
multipleOfWerte. Das Vielfache kann eine Fließkommazahl sein.

Wenn x der Wert validiert wird, muss Folgendes zutreffen:

x ≥ minimum
x > exclusiveMinimum
x < exclusiveMaximum

Sie können zwar sowohl als auch minimum exclusiveMinimum oder beide maximum und angebenexclusiveMaximum, wir empfehlen jedoch nicht, beide gleichzeitig zu verwenden.

Beispieldefinitionen:


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

Alternative Definition:


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

Zeichenfolgen

String-Typen unterstützen Folgendes:

default-Werte
Längenbeschränkungen (müssen nicht negative Zahlen sein), einschließlich Werte für maxLength und minLength
patternWerte für reguläre Ausdrücke

Wenn Sie reguläre Ausdrücke definieren, ist die Zeichenfolge gültig, wenn der Ausdruck mit einer beliebigen Stelle in der Zeichenfolge übereinstimmt. Der reguläre Ausdruck p entspricht beispielsweise jeder Zeichenfolge, die ein p enthält, z. B. „apple“, und nicht nur der Zeichenfolge „p“. Aus Gründen der Übersichtlichkeit empfehlen wir, reguläre Ausdrücke mit ^...$ (z. B.^p$) zu umgeben, es sei denn, Sie haben einen bestimmten Grund, dies nicht zu tun.

Beispieldefinition:


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

Null-Werte

Nulltypen akzeptieren nur einen einzigen Wert:null.

Beispieldefinition:


{ "type": "null" }

Arrays

Array-Typen unterstützen Folgendes:

default— eine Liste, die als Standardwert verwendet wird.
items— Die JSON-Typdefinition, die allen Array-Elementen auferlegt wird.
Längenbeschränkungen (muss eine nicht negative Zahl sein)
- minItems
- maxItems
patternWerte für Regex
uniqueItems— ein boolescher Wert, der angibt, ob die Elemente im Array eindeutig sein müssen
prefixItems— ein Array, bei dem jedes Element ein Schema ist, das jedem Index des Arrays des Dokuments entspricht. Das heißt, ein Array, bei dem das erste Element das erste Element des Eingabe-Arrays validiert, das zweite Element das zweite Element des Eingabe-Arrays und so weiter.

Beispieldefinition:


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

Beispiele für die Array-Validierung:


//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.

Alternative Definition mit Tupelvalidierung:


{
    "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

Objekte

Objekttypen unterstützen Folgendes:

Eigentumsbeschränkungen
- properties— Definieren Sie die Eigenschaften (Schlüssel-Wert-Paare) eines Objekts mithilfe des Schlüsselwortsproperties. Der Wert von properties ist ein Objekt, wobei jeder Schlüssel der Name einer Eigenschaft ist und jeder Wert ein Schema ist, das zur Validierung dieser Eigenschaft verwendet wird. Jede Eigenschaft, die mit keinem der Eigenschaftsnamen im properties Schlüsselwort übereinstimmt, wird von diesem Schlüsselwort ignoriert.
- required— Standardmäßig sind die durch das properties Schlüsselwort definierten Eigenschaften nicht erforderlich. Sie können jedoch mithilfe des required Schlüsselworts eine Liste der erforderlichen Eigenschaften bereitstellen. Das required Schlüsselwort benötigt ein Array von null oder mehr Zeichenketten. Jede dieser Zeichenketten muss einzigartig sein.
- propertyNames— Dieses Schlüsselwort ermöglicht die Kontrolle über das RegEx Muster für Eigenschaftsnamen. Sie könnten beispielsweise erzwingen, dass alle Eigenschaften eines Objekts Namen haben, die einer bestimmten Konvention folgen.
- patternProperties— Dadurch werden reguläre Ausdrücke Schemas zugeordnet. Wenn ein Eigenschaftsname mit dem angegebenen regulären Ausdruck übereinstimmt, muss der Eigenschaftswert anhand des entsprechenden Schemas validiert werden. Verwenden Sie dies beispielsweise, patternProperties um anzugeben, dass ein Wert einem bestimmten Schema entsprechen soll, wenn ein bestimmter Eigenschaftsname gegeben ist.
- additionalProperties— Dieses Schlüsselwort steuert, wie zusätzliche Eigenschaften behandelt werden. Zusätzliche Eigenschaften sind Eigenschaften, deren Namen nicht im Schlüsselwort properties aufgeführt sind oder die mit einem der regulären Ausdrücke in übereinstimmenpatternProperties. Standardmäßig sind zusätzliche Eigenschaften zulässig. Wenn Sie dieses Feld auf setzen, false bedeutet dies, dass keine zusätzlichen Eigenschaften zulässig sind.
- unevaluatedProperties— Dieses Schlüsselwort ist ähnlich, additionalProperties außer dass es Eigenschaften erkennen kann, die in Unterschemas deklariert sind. unevaluatedPropertiessammelt alle Eigenschaften, die bei der Verarbeitung der Schemas erfolgreich validiert wurden, und verwendet diese als zulässige Eigenschaftsliste. Auf diese Weise können Sie komplexere Aufgaben ausführen, z. B. das bedingte Hinzufügen von Eigenschaften. Weitere Informationen finden Sie im folgenden Beispiel.
anyOf— Der Wert dieses Schlüsselworts MUSS ein nicht leeres Array sein. Jedes Element des Arrays MUSS ein gültiges JSON-Schema sein. Eine Instanz validiert erfolgreich anhand dieses Schlüsselworts, wenn sie erfolgreich anhand mindestens eines Schemas validiert wird, das durch den Wert dieses Schlüsselworts definiert ist.
oneOf— Der Wert dieses Schlüsselworts MUSS ein nicht leeres Array sein. Jedes Element des Arrays MUSS ein gültiges JSON-Schema sein. Eine Instanz validiert erfolgreich anhand dieses Schlüsselworts, wenn sie erfolgreich anhand genau eines Schemas validiert wird, das durch den Wert dieses Schlüsselworts definiert ist.

Beispiel für erforderlich:


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

// Schema Compliant
{
  "test": 4
}

// NOT Schema Compliant
{}

PropertyNames Beispiel:


{
  "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 Beispiel:


{
  "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 Beispiel:


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

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

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

UnevaluatedProperties Beispiel:


{
  "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 Beispiel:


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

// Schema Compliant
"short"
12

// NOT Schema Compliant
"too long"
-5

OneOf Beispiel:


{
  "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.

Typdefinitionen mit Namespaces

Typdefinitionen mit Namespaces sind Typen, die aus primitiven Typen aufgebaut sind. Diese Typen müssen dem Format folgen. namespace.typename. Managed Integrations stellt vordefinierte Typen unter den Namespaces und zur Verfügung. aws matter Sie können jeden Namespace für benutzerdefinierte Typen verwenden, mit Ausnahme der reservierten Namespaces und der Namespaces. aws matter

Um nach verfügbaren Typdefinitionen mit Namespaces zu suchen, verwenden Sie die API, bei der der ListSchemaVersionsFilter auf eingestellt ist. Type definition

`matter`-Typen

Suchen Sie mithilfe der ListSchemaVersionsAPI nach Datentypen im matter Namespace, wobei der Filter auf matter und der Namespace Type Filter auf eingestellt ist. definition

`aws`-Typen

Suchen Sie mithilfe der ListSchemaVersionsAPI nach Datentypen im aws Namespace, wobei der Namespace Filter auf aws und der Type Filter auf eingestellt ist. definition

Definition des Bitmap-Typs

Bitmaps haben zwei erforderliche Eigenschaften:

typemuss ein Objekt sein
propertiesmuss ein Objekt sein, das jede Bitdefinition enthält. Jedes Bit ist ein Objekt mit Eigenschaften extrinsicId undvalue. Der Wert jedes Bits muss eine Ganzzahl mit einem Mindestwert von 0 und einem Höchstwert von mindestens 1 sein.

Beispiel für eine Bitmap-Definition:


{
    "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
}

Definition des Aufzählungstyps

Aufzählungen benötigen drei Eigenschaften:

typemuss ein Objekt sein
enummuss ein Array von eindeutigen Zeichenketten mit mindestens einem Element sein
extrinsicIdMapist ein Objekt mit Eigenschaften, bei denen es sich um Enum-Werte handelt. Der Wert jeder der Eigenschaften sollte der extrinsische Bezeichner sein, der dem Enum-Wert entspricht.

Beispiel für eine Enum-Definition:


{
    "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"

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Schema für Typdefinitionen

Gerätebefehle und Ereignisse

Erstellung und Verwendung von Typdefinitionen in Capability-Schema-Dokumenten

Inhalt

Primitive Typdefinitionen

Boolesche Werte

Unterstützung für Integer-Typen

Anmerkung

Zahlen

Zeichenfolgen

Null-Werte

Arrays

Objekte

Typdefinitionen mit Namespaces

matter-Typen

aws-Typen

Definition des Bitmap-Typs

Definition des Aufzählungstyps

`matter`-Typen

`aws`-Typen