Dialecte CEL pour la validation des documents

La validation et la correction Document AI s'appuient sur le Common Expression Language (CEL) pour permettre une validation et une manipulation flexibles des données dans vos workflows de traitement de documents. Document AI propose un ensemble de fonctions, de macros et de modifications comportementales personnalisées pour les données d'entités de document.

Accéder aux entités dans une expression CEL

Toutes les expressions sont évaluées par rapport à une variable racine nommée doc, qui se compose d'entités qui sont des expressions ou des propriétés appartenant au document. Ces entités suivent de près la structure des entités de votre document extrait.

Bien qu'une entité extraite contienne de nombreuses propriétés, seules trois d'entre elles sont disponibles pour l'évaluation CEL.

• mention_text : texte brut extrait tel qu'il figure dans une entité extraite. La valeur par défaut est une chaîne vide.
• normalized_value : texte de mention normalisé tel qu'il figure dans une entité extraite. La valeur par défaut est "null". En savoir plus sur la normalisation
• bounding_poly : objet spécial contenant une représentation de l'emplacement de l'entité extraite dans le document et utilisé pour les vérifications d'alignement. Sa valeur par défaut est "null".

Modèle de données

La structure exacte d'une entité extraite dans la carte doc dépend de deux facteurs. La première concerne la structure : s'agit-il d'une valeur concrète, comme un nombre ou du texte brut, ou d'un objet complexe ? Le deuxième facteur est de savoir si son type d'occurrence est unique ou multiple. Pour en savoir plus, consultez la page sur la méthode OccurrenceType.

Une fonctionnalité clé du modèle de données de validation est que toute entité définie dans le schéma, mais non extraite du document, est automatiquement renseignée avec des valeurs par défaut. Cette conception vous permet d'ignorer la plupart des vérifications de valeurs nulles explicites dans vos expressions CEL, ce qui simplifie considérablement vos expressions de validation. Vous n'avez besoin d'écrire explicitement des vérifications de valeurs nulles que pour vous assurer qu'une entité sélectionnée a bien été extraite.

Exemples de cas d'entités feuilles

Les sections suivantes décrivent comment accéder aux entités d'une entité feuille, c'est-à-dire une entité sans entités enfants imbriquées. Les entités feuilles contiennent directement une valeur.

Entité feuille avec une seule occurrence

Il s'agit du cas le plus élémentaire, qui utilise OccurrenceType de OPTIONAL_ONCE ou REQUIRED_ONCE. L'entité est représentée sous la forme d'un objet contenant les trois propriétés standards.

doc.invoice_date.normalized_value est un exemple de la façon d'accéder à ces valeurs.

Il présente la structure suivante :

  "invoice_date": {
    "mention_text": "1",
    "normalized_value": 1.0,
    "bounding_poly": bounding_poly_object
  }

Valeur par défaut :

  "invoice_date": {
    "mention_text": "",
    "normalized_value": null,
    "bounding_poly": null
  }

Entité feuille avec plusieurs occurrences

Ce cas s'applique aux entités feuilles qui peuvent se produire plusieurs fois et dont le OccurrenceType est OPTIONAL_MULTIPLE ou REQUIRED_MULTIPLE. Par exemple, dans une liste de dates d'échéance de paiement, elle est représentée sous la forme d'un objet où chaque propriété contient une liste des valeurs correspondantes de toutes les occurrences. Ainsi, des propriétés telles que mention_text, normalized_value et bounding_poly peuvent comporter plusieurs entités.

doc.payment_due_dates.normalized_value[0] est un exemple de la façon d'accéder à ces valeurs.

Il présente la structure suivante :

  "payment_due_dates": {
    "mention_text": ["Mar 1, 2024", "Apr 1, 2024"],
    "normalized_value": [null, proto.timestamp(2024-04-01)],
    // Note: If a value is not normalized, it is stored as a null.
    "bounding_poly": [bounding_poly_object,bounding_poly_object]
  }

Valeur par défaut :

  "payment_due_dates": {
    "mention_text": [],
    "normalized_value": []
    "bounding_poly": []
  }

Entités imbriquées

Une entité imbriquée est un conteneur pour d'autres entités, qui sont ses "enfants".

Entité imbriquée avec une occurrence

Si une entité imbriquée ne se produit qu'une seule fois, par exemple un seul receiver_address, elle est représentée sous la forme d'un objet dont les clés sont les noms de ses entités enfants.

doc.receiver_address.city.mention_text est un exemple de la façon d'accéder à ces valeurs.

Il présente la structure suivante :

  "receiver_address": {
    "street": {
      "mention_text": "123 Main St",
      "normalized_value": "123 Main St",
      "bounding_poly": bounding_poly_object
    }
    }

Valeur par défaut :

  "receiver_address": {
    "street": {
      "mention_text": "",
      "normalized_value": null,
      "bounding_poly": null
    }
    }

Entité imbriquée avec plusieurs occurrences

Lorsqu'une entité imbriquée peut se produire plusieurs fois, elle est représentée sous la forme d'une liste d'objets. Chaque objet de la liste représente une instance complète de l'entité imbriquée et contient ses enfants.

doc.line_items[1].description.normalized_value est un exemple de la façon d'accéder à ces valeurs.

Il présente la structure suivante :

  "line_items": [
    {
      "description": { "mention_text": "Product A", ... },
      "quantity": { "mention_text": "2", ...