Définitions de types primitifs Définitions de types avec espace de noms

Création et utilisation de définitions de type dans les documents de schéma de capacités

Tous les éléments des schémas sont convertis en définitions de type. Ces définitions de type sont soit des définitions de type primitives (telles que des booléens, des chaînes, des nombres), soit des définitions de type avec espace de noms (définitions de type créées à partir de définitions de types primitives pour des raisons de commodité).

Lorsque vous définissez un schéma personnalisé, vous pouvez utiliser à la fois des définitions primitives et des définitions de type d'espace de noms.

Table des matières

Définitions de types primitifs

Les définitions de types primitives sont les éléments de base de toutes les définitions de type définies dans les intégrations gérées. Toutes les définitions d'espaces de noms, y compris les définitions de type personnalisées, sont converties en une définition de type primitive via le $ref mot-clé ou le type mot-clé.

Tous les types primitifs sont nullables à l'aide du nullable mot-clé, et vous pouvez identifier tous les types primitifs à l'aide du type mot-clé.

Booléens

Les types booléens prennent en charge les valeurs par défaut.

Définition de l'exemple :


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

Support de type entier

Les types entiers prennent en charge les éléments suivants :

default values
maximum values
minimum values
exclusiveMaximum values
exclusiveMinimum values
multipleOf values

Si la valeur x est en cours de validation, les conditions suivantes doivent être vraies :

x ≥ minimum
x > exclusiveMinimum
x < exclusiveMaximum

Note

Les nombres dont la partie fractionnaire est nulle sont considérés comme des entiers, mais les nombres à virgule flottante sont rejetés.


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

Bien que vous puissiez spécifier minimum les deux exclusiveMinimum et/ou maximum les deuxexclusiveMaximum, nous vous déconseillons d'utiliser les deux simultanément.

Exemples de définitions :


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

Définition alternative :


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

Nombres

Utilisez le type numérique pour tous les types numériques, y compris les entiers et les nombres à virgule flottante.

Les types de numéros prennent en charge les éléments suivants :

default values
maximum values
minimum values
exclusiveMaximum values
exclusiveMinimum values
multipleOfvaleurs. Le multiple peut être un nombre à virgule flottante.

Si la valeur x est en cours de validation, les conditions suivantes doivent être vraies :

x ≥ minimum
x > exclusiveMinimum
x < exclusiveMaximum

Bien que vous puissiez spécifier minimum les deux exclusiveMinimum et/ou maximum les deuxexclusiveMaximum, nous vous déconseillons d'utiliser les deux simultanément.

Exemples de définitions :


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

Définition alternative :


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

Chaînes

Les types de chaînes prennent en charge les éléments suivants :

default values
les contraintes de longueur (doivent être des nombres non négatifs), y compris les valeurs maxLength et minLength
patternvaleurs pour les expressions régulières

Lorsque vous définissez des expressions régulières, la chaîne est valide si l'expression correspond à un point quelconque de la chaîne. Par exemple, l'expression régulière p correspond à n'importe quelle chaîne contenant un p, telle que « apple », et pas seulement à la chaîne « p ». Pour plus de clarté, nous vous recommandons d'entourer les expressions régulières de ^...$ (par exemple,^p$), sauf si vous avez une raison spécifique de ne pas le faire.

Définition de l'exemple :


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

Valeurs null

Les types nuls n'acceptent qu'une seule valeur :null.

Définition de l'exemple :


{ "type": "null" }

Arrays (tableaux)

Les types de tableaux prennent en charge les éléments suivants :

default— une liste qui sera utilisée comme valeur par défaut.
items— Définition du type JSON imposée à tous les éléments du tableau.
Contraintes de longueur (doit être un nombre non négatif)
- minItems
- maxItems
patternvaleurs pour Regex
uniqueItems— un booléen indiquant si les éléments du tableau doivent être uniques
prefixItems— un tableau dans lequel chaque élément est un schéma correspondant à chaque index du tableau du document. C'est-à-dire un tableau où le premier élément valide le premier élément du tableau d'entrée, le deuxième élément valide le deuxième élément du tableau d'entrée, et ainsi de suite.

Définition de l'exemple :


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

Exemples de validation de tableaux :


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

Définition alternative utilisant la validation des tuples :


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

Objets

Les types d'objets prennent en charge les éléments suivants :

Contraintes immobilières
- properties— Définissez les propriétés (paires clé-valeur) d'un objet à l'aide du properties mot-clé. La valeur de properties est un objet, où chaque clé est le nom d'une propriété et chaque valeur est un schéma utilisé pour valider cette propriété. Toute propriété qui ne correspond à aucun des noms de propriété du properties mot clé est ignorée par ce mot clé.
- required— Par défaut, les propriétés définies par le properties mot clé ne sont pas obligatoires. Vous pouvez toutefois fournir une liste des propriétés requises à l'aide du required mot clé. Le required mot clé prend un tableau de zéro ou plusieurs chaînes. Chacune de ces chaînes doit être unique.
- propertyNames— Ce mot clé permet de contrôler le RegEx modèle des noms de propriétés. Par exemple, vous souhaiterez peut-être faire en sorte que toutes les propriétés d'un objet portent des noms conformes à une convention spécifique.
- patternProperties— Cela fait correspondre les expressions régulières aux schémas. Si le nom d'une propriété correspond à l'expression régulière donnée, la valeur de la propriété doit être validée par rapport au schéma correspondant. Par exemple, utilisez patternProperties pour spécifier qu'une valeur doit correspondre à un schéma particulier, en fonction d'un type particulier de nom de propriété.
- additionalProperties— Ce mot clé contrôle la façon dont les propriétés supplémentaires sont gérées. Les propriétés supplémentaires sont des propriétés dont les noms ne figurent pas dans le mot clé properties ou qui correspondent à l'une des expressions régulières depatternProperties. Par défaut, les propriétés supplémentaires sont autorisées. La définition de ce champ sur false signifie qu'aucune propriété supplémentaire n'est autorisée.
- unevaluatedProperties— Ce mot clé est similaire à, additionalProperties sauf qu'il peut reconnaître les propriétés déclarées dans les sous-schémas. unevaluatedPropertiesfonctionne en collectant toutes les propriétés validées avec succès lors du traitement des schémas et en les utilisant comme liste de propriétés autorisées. Cela vous permet d'effectuer des tâches plus complexes, telles que l'ajout conditionnel de propriétés. Reportez-vous à l'exemple ci-dessous pour plus de détails.
anyOf— La valeur de ce mot clé DOIT être un tableau non vide. Chaque élément du tableau DOIT être un schéma JSON valide. Une instance est validée avec succès par rapport à ce mot clé si elle est validée avec succès par rapport à au moins un schéma défini par la valeur de ce mot clé.
oneOf— La valeur de ce mot clé DOIT être un tableau non vide. Chaque élément du tableau DOIT être un schéma JSON valide. Une instance est validée avec succès par rapport à ce mot clé si elle est validée avec succès par rapport à exactement un schéma défini par la valeur de ce mot clé.

Exemple de obligatoire :


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

// Schema Compliant
{
  "test": 4
}

// NOT Schema Compliant
{}

PropertyNames exemple :


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


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


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

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

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

UnevaluatedProperties exemple :


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


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

// Schema Compliant
"short"
12

// NOT Schema Compliant
"too long"
-5

OneOf exemple :


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

Définitions de types avec espace de noms

Les définitions de types avec espace de noms sont des types créés à partir de types primitifs. Ces types doivent suivre le format namespace.typename. Managed integrations fournit des types prédéfinis sous les espaces de matter noms aws et. Vous pouvez utiliser n'importe quel espace de noms pour les types personnalisés, à l'exception des espaces réservés aws et des espaces de matter noms.

Pour trouver les définitions de type avec espace de noms disponibles, utilisez l'ListSchemaVersionsAPI avec le Type filtre défini sur. definition

Types `matter`

Recherchez les types de données dans l'matterespace de noms à l'aide de l'ListSchemaVersionsAPI avec le Namespace filtre défini sur matter et le Type filtre défini sur. definition

Types `aws`

Recherchez les types de données dans l'awsespace de noms à l'aide de l'ListSchemaVersionsAPI avec le Namespace filtre défini sur aws et le Type filtre défini sur. definition

Définition du type de bitmap

Les bitmaps ont deux propriétés obligatoires :

typedoit être un objet
propertiesdoit être un objet contenant chaque définition de bit. Chaque bit est un objet avec des propriétés extrinsicId etvalue. La valeur de chaque bit doit être un entier avec une valeur minimale de 0 et une valeur maximale d'au moins 1.

Exemple de définition d'un bitmap :


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

Définition du type Enum

Les énumérations nécessitent trois propriétés :

typedoit être un objet
enumdoit être un tableau de chaînes uniques, avec au moins un élément
extrinsicIdMapest un objet dont les propriétés sont les valeurs d'énumération. La valeur de chacune des propriétés doit être l'identifiant extrinsèque correspondant à la valeur d'énumération.

Exemple de définition de l'énumération :


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

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Schéma pour les définitions de type

Commandes et événements de l'appareil

Création et utilisation de définitions de type dans les documents de schéma de capacités

Table des matières

Définitions de types primitifs

Booléens

Support de type entier

Note

Nombres

Chaînes

Valeurs null

Arrays (tableaux)

Objets

Définitions de types avec espace de noms

Types matter

Types aws

Définition du type de bitmap

Définition du type Enum

Types `matter`

Types `aws`