diff --git a/google/cloud/documentai/v1beta3/document.proto b/google/cloud/documentai/v1beta3/document.proto index abba3ae19233a..760cd51153022 100644 --- a/google/cloud/documentai/v1beta3/document.proto +++ b/google/cloud/documentai/v1beta3/document.proto @@ -1,4 +1,4 @@ -// Copyright 2021 Google LLC +// Copyright 2022 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -16,6 +16,7 @@ syntax = "proto3"; package google.cloud.documentai.v1beta3; +import "google/api/annotations.proto"; import "google/api/field_behavior.proto"; import "google/cloud/documentai/v1beta3/geometry.proto"; import "google/protobuf/timestamp.proto"; @@ -25,7 +26,6 @@ import "google/type/date.proto"; import "google/type/datetime.proto"; import "google/type/money.proto"; import "google/type/postal_address.proto"; -import "google/api/annotations.proto"; option csharp_namespace = "Google.Cloud.DocumentAI.V1Beta3"; option go_package = "google.golang.org/genproto/googleapis/cloud/documentai/v1beta3;documentai"; @@ -51,8 +51,9 @@ message Document { // Total number of shards. int64 shard_count = 2; - // The index of the first character in [Document.text][google.cloud.documentai.v1beta3.Document.text] in the overall - // document global text. + // The index of the first character in + // [Document.text][google.cloud.documentai.v1beta3.Document.text] in the + // overall document global text. int64 text_offset = 3; } @@ -68,7 +69,8 @@ message Document { string unit = 2; } - // Text anchor indexing into the [Document.text][google.cloud.documentai.v1beta3.Document.text]. + // Text anchor indexing into the + // [Document.text][google.cloud.documentai.v1beta3.Document.text]. TextAnchor text_anchor = 1; // Text color. @@ -165,25 +167,31 @@ message Document { PAGE_LEFT = 4; } - // Text anchor indexing into the [Document.text][google.cloud.documentai.v1beta3.Document.text]. + // Text anchor indexing into the + // [Document.text][google.cloud.documentai.v1beta3.Document.text]. TextAnchor text_anchor = 1; - // Confidence of the current [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] within context of the object this - // layout is for. e.g. confidence can be for a single token, a table, - // a visual element, etc. depending on context. Range [0, 1]. + // Confidence of the current + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] within + // context of the object this layout is for. e.g. confidence can be for a + // single token, a table, a visual element, etc. depending on context. + // Range [0, 1]. float confidence = 2; - // The bounding polygon for the [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout]. + // The bounding polygon for the + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout]. BoundingPoly bounding_poly = 3; - // Detected orientation for the [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout]. + // Detected orientation for the + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout]. Orientation orientation = 4; } // A block has a set of lines (collected into paragraphs) that have a // common line-spacing and orientation. message Block { - // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for [Block][google.cloud.documentai.v1beta3.Document.Page.Block]. + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for + // [Block][google.cloud.documentai.v1beta3.Document.Page.Block]. Layout layout = 1; // A list of detected languages together with confidence. @@ -195,7 +203,8 @@ message Document { // A collection of lines that a human would perceive as a paragraph. message Paragraph { - // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for [Paragraph][google.cloud.documentai.v1beta3.Document.Page.Paragraph]. + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for + // [Paragraph][google.cloud.documentai.v1beta3.Document.Page.Paragraph]. Layout layout = 1; // A list of detected languages together with confidence. @@ -208,7 +217,8 @@ message Document { // A collection of tokens that a human would perceive as a line. // Does not cross column boundaries, can be horizontal, vertical, etc. message Line { - // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for [Line][google.cloud.documentai.v1beta3.Document.Page.Line]. + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for + // [Line][google.cloud.documentai.v1beta3.Document.Page.Line]. Layout layout = 1; // A list of detected languages together with confidence. @@ -220,7 +230,8 @@ message Document { // A detected token. message Token { - // Detected break at the end of a [Token][google.cloud.documentai.v1beta3.Document.Page.Token]. + // Detected break at the end of a + // [Token][google.cloud.documentai.v1beta3.Document.Page.Token]. message DetectedBreak { // Enum to denote the type of break found. enum Type { @@ -241,10 +252,12 @@ message Document { Type type = 1; } - // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for [Token][google.cloud.documentai.v1beta3.Document.Page.Token]. + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for + // [Token][google.cloud.documentai.v1beta3.Document.Page.Token]. Layout layout = 1; - // Detected break at the end of a [Token][google.cloud.documentai.v1beta3.Document.Page.Token]. + // Detected break at the end of a + // [Token][google.cloud.documentai.v1beta3.Document.Page.Token]. DetectedBreak detected_break = 2; // A list of detected languages together with confidence. @@ -254,13 +267,25 @@ message Document { Provenance provenance = 4; } + // A detected symbol. + message Symbol { + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for + // [Symbol][google.cloud.documentai.v1beta3.Document.Page.Symbol]. + Layout layout = 1; + + // A list of detected languages together with confidence. + repeated DetectedLanguage detected_languages = 2; + } + // Detected non-text visual elements e.g. checkbox, signature etc. on the // page. message VisualElement { - // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for [VisualElement][google.cloud.documentai.v1beta3.Document.Page.VisualElement]. + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for + // [VisualElement][google.cloud.documentai.v1beta3.Document.Page.VisualElement]. Layout layout = 1; - // Type of the [VisualElement][google.cloud.documentai.v1beta3.Document.Page.VisualElement]. + // Type of the + // [VisualElement][google.cloud.documentai.v1beta3.Document.Page.VisualElement]. string type = 2; // A list of detected languages together with confidence. @@ -277,7 +302,8 @@ message Document { // A cell representation inside the table. message TableCell { - // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for [TableCell][google.cloud.documentai.v1beta3.Document.Page.Table.TableCell]. + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for + // [TableCell][google.cloud.documentai.v1beta3.Document.Page.Table.TableCell]. Layout layout = 1; // How many rows this cell spans. @@ -290,7 +316,8 @@ message Document { repeated DetectedLanguage detected_languages = 4; } - // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for [Table][google.cloud.documentai.v1beta3.Document.Page.Table]. + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for + // [Table][google.cloud.documentai.v1beta3.Document.Page.Table]. Layout layout = 1; // Header rows of the table. @@ -305,11 +332,14 @@ message Document { // A form field detected on the page. message FormField { - // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for the [FormField][google.cloud.documentai.v1beta3.Document.Page.FormField] name. e.g. `Address`, `Email`, - // `Grand total`, `Phone number`, etc. + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for the + // [FormField][google.cloud.documentai.v1beta3.Document.Page.FormField] + // name. e.g. `Address`, `Email`, `Grand total`, `Phone number`, etc. Layout field_name = 1; - // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for the [FormField][google.cloud.documentai.v1beta3.Document.Page.FormField] value. + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for the + // [FormField][google.cloud.documentai.v1beta3.Document.Page.FormField] + // value. Layout field_value = 2; // A list of detected languages for name together with confidence. @@ -333,16 +363,18 @@ message Document { message DetectedLanguage { // The BCP-47 language code, such as "en-US" or "sr-Latn". For more // information, see - // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + // https://www.unicode.org/reports/tr35/#Unicode_locale_identifier. string language_code = 1; // Confidence of detected language. Range [0, 1]. float confidence = 2; } - // 1-based index for current [Page][google.cloud.documentai.v1beta3.Document.Page] in a parent [Document][google.cloud.documentai.v1beta3.Document]. - // Useful when a page is taken out of a [Document][google.cloud.documentai.v1beta3.Document] for individual - // processing. + // 1-based index for current + // [Page][google.cloud.documentai.v1beta3.Document.Page] in a parent + // [Document][google.cloud.documentai.v1beta3.Document]. Useful when a page + // is taken out of a [Document][google.cloud.documentai.v1beta3.Document] + // for individual processing. int32 page_number = 1; // Rendered image for this page. This image is preprocessed to remove any @@ -351,13 +383,15 @@ message Document { Image image = 13; // Transformation matrices that were applied to the original document image - // to produce [Page.image][google.cloud.documentai.v1beta3.Document.Page.image]. + // to produce + // [Page.image][google.cloud.documentai.v1beta3.Document.Page.image]. repeated Matrix transforms = 14; // Physical dimension of the page. Dimension dimension = 2; - // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for the page. + // [Layout][google.cloud.documentai.v1beta3.Document.Page.Layout] for the + // page. Layout layout = 3; // A list of detected languages together with confidence. @@ -389,17 +423,23 @@ message Document { // A list of visually detected form fields on the page. repeated FormField form_fields = 11; + // A list of visually detected symbols on the page. + repeated Symbol symbols = 12; + // The history of this page. Provenance provenance = 16; } - // A phrase in the text that is a known entity type, such as a person, an - // organization, or location. + // An entity that could be a phrase in the text or a property that belongs to + // the document. It is a known entity type, such as a person, an organization, + // or location. message Entity { // Parsed and normalized entity value. message NormalizedValue { - // Structured entity value. Must match entity type defined in schema if - // known. If this field is present, the 'text' field is still populated. + // An optional structured entity value. + // Must match entity type defined in schema if + // known. If this field is present, the `text` field could also be + // populated. oneof structured_value { // Money value. See also: // https://github.com/googleapis/googleapis/blob/master/google/type/money.proto @@ -422,24 +462,29 @@ message Document { bool boolean_value = 6; } - // Required. Normalized entity value stored as a string. This field is populated for - // supported document type (e.g. Invoice). For some entity types, one of - // respective 'structured_value' fields may also be populated. + // Optional. An optional field to store a normalized string. + // For some entity types, one of respective `structured_value` fields may + // also be populated. Also not all the types of `structured_value` will be + // normalized. For example, some processors may not generate float + // or int normalized text by default. // + // Below are sample formats mapped to structured values. // - Money/Currency type (`money_value`) is in the ISO 4217 text format. // - Date type (`date_value`) is in the ISO 8601 text format. // - Datetime type (`datetime_value`) is in the ISO 8601 text format. - string text = 1 [(google.api.field_behavior) = REQUIRED]; + string text = 1 [(google.api.field_behavior) = OPTIONAL]; } // Optional. Provenance of the entity. - // Text anchor indexing into the [Document.text][google.cloud.documentai.v1beta3.Document.text]. + // Text anchor indexing into the + // [Document.text][google.cloud.documentai.v1beta3.Document.text]. TextAnchor text_anchor = 1 [(google.api.field_behavior) = OPTIONAL]; // Entity type from a schema e.g. `Address`. string type = 2; - // Optional. Text value in the document e.g. `1600 Amphitheatre Pkwy`. + // Optional. Text value in the document e.g. `1600 Amphitheatre Pkwy`. If + // the entity is not present in the document, this field will be empty. string mention_text = 3 [(google.api.field_behavior) = OPTIONAL]; // Optional. Deprecated. Use `id` field instead. @@ -448,32 +493,35 @@ message Document { // Optional. Confidence of detected Schema entity. Range [0, 1]. float confidence = 5 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Represents the provenance of this entity wrt. the location on the - // page where it was found. + // Optional. Represents the provenance of this entity wrt. the location on + // the page where it was found. PageAnchor page_anchor = 6 [(google.api.field_behavior) = OPTIONAL]; // Optional. Canonical id. This will be a unique value in the entity list // for this document. string id = 7 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Normalized entity value. Absent if the extracted value could not be - // converted or the type (e.g. address) is not supported for certain + // Optional. Normalized entity value. Absent if the extracted value could + // not be converted or the type (e.g. address) is not supported for certain // parsers. This field is also only populated for certain supported document // types. - NormalizedValue normalized_value = 9 [(google.api.field_behavior) = OPTIONAL]; + NormalizedValue normalized_value = 9 + [(google.api.field_behavior) = OPTIONAL]; - // Optional. Entities can be nested to form a hierarchical data structure representing - // the content in the document. + // Optional. Entities can be nested to form a hierarchical data structure + // representing the content in the document. repeated Entity properties = 10 [(google.api.field_behavior) = OPTIONAL]; // Optional. The history of this annotation. Provenance provenance = 11 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Whether the entity will be redacted for de-identification purposes. + // Optional. Whether the entity will be redacted for de-identification + // purposes. bool redacted = 12 [(google.api.field_behavior) = OPTIONAL]; } - // Relationship between [Entities][google.cloud.documentai.v1beta3.Document.Entity]. + // Relationship between + // [Entities][google.cloud.documentai.v1beta3.Document.Entity]. message EntityRelation { // Subject entity id. string subject_id = 1; @@ -485,30 +533,39 @@ message Document { string relation = 3; } - // Text reference indexing into the [Document.text][google.cloud.documentai.v1beta3.Document.text]. + // Text reference indexing into the + // [Document.text][google.cloud.documentai.v1beta3.Document.text]. message TextAnchor { - // A text segment in the [Document.text][google.cloud.documentai.v1beta3.Document.text]. The indices may be out of bounds - // which indicate that the text extends into another document shard for - // large sharded documents. See [ShardInfo.text_offset][google.cloud.documentai.v1beta3.Document.ShardInfo.text_offset] + // A text segment in the + // [Document.text][google.cloud.documentai.v1beta3.Document.text]. The + // indices may be out of bounds which indicate that the text extends into + // another document shard for large sharded documents. See + // [ShardInfo.text_offset][google.cloud.documentai.v1beta3.Document.ShardInfo.text_offset] message TextSegment { - // [TextSegment][google.cloud.documentai.v1beta3.Document.TextAnchor.TextSegment] start UTF-8 char index in the [Document.text][google.cloud.documentai.v1beta3.Document.text]. + // [TextSegment][google.cloud.documentai.v1beta3.Document.TextAnchor.TextSegment] + // start UTF-8 char index in the + // [Document.text][google.cloud.documentai.v1beta3.Document.text]. int64 start_index = 1; - // [TextSegment][google.cloud.documentai.v1beta3.Document.TextAnchor.TextSegment] half open end UTF-8 char index in the + // [TextSegment][google.cloud.documentai.v1beta3.Document.TextAnchor.TextSegment] + // half open end UTF-8 char index in the // [Document.text][google.cloud.documentai.v1beta3.Document.text]. int64 end_index = 2; } - // The text segments from the [Document.text][google.cloud.documentai.v1beta3.Document.text]. + // The text segments from the + // [Document.text][google.cloud.documentai.v1beta3.Document.text]. repeated TextSegment text_segments = 1; // Contains the content of the text span so that users do - // not have to look it up in the text_segments. + // not have to look it up in the text_segments. It is always + // populated for formFields. string content = 2; } - // Referencing the visual context of the entity in the [Document.pages][google.cloud.documentai.v1beta3.Document.pages]. - // Page anchors can be cross-page, consist of multiple bounding polygons and + // Referencing the visual context of the entity in the + // [Document.pages][google.cloud.documentai.v1beta3.Document.pages]. Page + // anchors can be cross-page, consist of multiple bounding polygons and // optionally reference specific layout element types. message PageAnchor { // Represents a weak reference to a page element within a document. @@ -518,47 +575,66 @@ message Document { // Layout Unspecified. LAYOUT_TYPE_UNSPECIFIED = 0; - // References a [Page.blocks][google.cloud.documentai.v1beta3.Document.Page.blocks] element. + // References a + // [Page.blocks][google.cloud.documentai.v1beta3.Document.Page.blocks] + // element. BLOCK = 1; - // References a [Page.paragraphs][google.cloud.documentai.v1beta3.Document.Page.paragraphs] element. + // References a + // [Page.paragraphs][google.cloud.documentai.v1beta3.Document.Page.paragraphs] + // element. PARAGRAPH = 2; - // References a [Page.lines][google.cloud.documentai.v1beta3.Document.Page.lines] element. + // References a + // [Page.lines][google.cloud.documentai.v1beta3.Document.Page.lines] + // element. LINE = 3; - // References a [Page.tokens][google.cloud.documentai.v1beta3.Document.Page.tokens] element. + // References a + // [Page.tokens][google.cloud.documentai.v1beta3.Document.Page.tokens] + // element. TOKEN = 4; - // References a [Page.visual_elements][google.cloud.documentai.v1beta3.Document.Page.visual_elements] element. + // References a + // [Page.visual_elements][google.cloud.documentai.v1beta3.Document.Page.visual_elements] + // element. VISUAL_ELEMENT = 5; - // Refrrences a [Page.tables][google.cloud.documentai.v1beta3.Document.Page.tables] element. + // Refrrences a + // [Page.tables][google.cloud.documentai.v1beta3.Document.Page.tables] + // element. TABLE = 6; - // References a [Page.form_fields][google.cloud.documentai.v1beta3.Document.Page.form_fields] element. + // References a + // [Page.form_fields][google.cloud.documentai.v1beta3.Document.Page.form_fields] + // element. FORM_FIELD = 7; } - // Required. Index into the [Document.pages][google.cloud.documentai.v1beta3.Document.pages] element, for example using - // [Document.pages][page_refs.page] to locate the related page element. - // This field is skipped when its value is the default 0. See + // Required. Index into the + // [Document.pages][google.cloud.documentai.v1beta3.Document.pages] + // element, for example using [Document.pages][page_refs.page] to locate + // the related page element. This field is skipped when its value is the + // default 0. See // https://developers.google.com/protocol-buffers/docs/proto3#json. int64 page = 1 [(google.api.field_behavior) = REQUIRED]; - // Optional. The type of the layout element that is being referenced if any. + // Optional. The type of the layout element that is being referenced if + // any. LayoutType layout_type = 2 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Deprecated. Use [PageRef.bounding_poly][google.cloud.documentai.v1beta3.Document.PageAnchor.PageRef.bounding_poly] instead. - string layout_id = 3 [ - deprecated = true, - (google.api.field_behavior) = OPTIONAL - ]; + // Optional. Deprecated. Use + // [PageRef.bounding_poly][google.cloud.documentai.v1beta3.Document.PageAnchor.PageRef.bounding_poly] + // instead. + string layout_id = 3 + [deprecated = true, (google.api.field_behavior) = OPTIONAL]; - // Optional. Identifies the bounding polygon of a layout element on the page. + // Optional. Identifies the bounding polygon of a layout element on the + // page. BoundingPoly bounding_poly = 4 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Confidence of detected page element, if applicable. Range [0, 1]. + // Optional. Confidence of detected page element, if applicable. Range [0, + // 1]. float confidence = 5 [(google.api.field_behavior) = OPTIONAL]; } @@ -569,15 +645,14 @@ message Document { // Structure to identify provenance relationships between annotations in // different revisions. message Provenance { - // Structure for referencing parent provenances. When an element replaces - // one of more other elements parent references identify the elements that - // are replaced. + // The parent element the current element is based on. Used for + // referencing/aligning, removal and replacement operations. message Parent { - // The index of the [Document.revisions] identifying the parent revision. + // The index of the index into current revision's parent_ids list. int32 revision = 1; - // The index of the parent revisions corresponding collection of items - // (eg. list of entities, properties within entities, etc.) + // The index of the parent item in the corresponding item list (eg. list + // of entities, properties within entities, etc.) in the parent revision. int32 index = 3; // The id of the parent provenance. @@ -586,19 +661,20 @@ message Document { // If a processor or agent does an explicit operation on existing elements. enum OperationType { - // Operation type unspecified. + // Operation type unspecified. If no operation is specified a provenance + // entry is simply used to match against a `parent`. OPERATION_TYPE_UNSPECIFIED = 0; - // Add an element. Implicit if no `parents` are set for the provenance. + // Add an element. ADD = 1; - // The element is removed. No `parents` should be set. + // Remove an element identified by `parent`. REMOVE = 2; - // Explicitly replaces the element(s) identified by `parents`. + // Replace an element identified by `parent`. REPLACE = 3; - // Element is requested for human review. + // Request human review for the element identified by `parent`. EVAL_REQUESTED = 4; // Element is reviewed and approved at human review, confidence will be @@ -664,10 +740,11 @@ message Document { // This message is used for text changes aka. OCR corrections. message TextChange { // Provenance of the correction. - // Text anchor indexing into the [Document.text][google.cloud.documentai.v1beta3.Document.text]. There can only be a - // single `TextAnchor.text_segments` element. If the start and - // end index of the text segment are the same, the text change is inserted - // before that index. + // Text anchor indexing into the + // [Document.text][google.cloud.documentai.v1beta3.Document.text]. There + // can only be a single `TextAnchor.text_segments` element. If the start + // and end index of the text segment are the same, the text change is + // inserted before that index. TextAnchor text_anchor = 1; // The text that replaces the text identified in the `text_anchor`. @@ -700,22 +777,26 @@ message Document { // Optional. UTF-8 encoded text in reading order from the document. string text = 4 [(google.api.field_behavior) = OPTIONAL]; - // Styles for the [Document.text][google.cloud.documentai.v1beta3.Document.text]. + // Placeholder. Styles for the + // [Document.text][google.cloud.documentai.v1beta3.Document.text]. repeated Style text_styles = 5; - // Visual page layout for the [Document][google.cloud.documentai.v1beta3.Document]. + // Visual page layout for the + // [Document][google.cloud.documentai.v1beta3.Document]. repeated Page pages = 6; - // A list of entities detected on [Document.text][google.cloud.documentai.v1beta3.Document.text]. For document shards, - // entities in this list may cross shard boundaries. + // A list of entities detected on + // [Document.text][google.cloud.documentai.v1beta3.Document.text]. For + // document shards, entities in this list may cross shard boundaries. repeated Entity entities = 7; - // Relationship among [Document.entities][google.cloud.documentai.v1beta3.Document.entities]. + // Placeholder. Relationship among + // [Document.entities][google.cloud.documentai.v1beta3.Document.entities]. repeated EntityRelation entity_relations = 8; - // A list of text corrections made to [Document.text]. This is usually - // used for annotating corrections to OCR mistakes. Text changes for a given - // revision may not overlap with each other. + // Placeholder. A list of text corrections made to [Document.text]. This is + // usually used for annotating corrections to OCR mistakes. Text changes for + // a given revision may not overlap with each other. repeated TextChange text_changes = 14; // Information about the sharding if this document is sharded part of a larger @@ -725,6 +806,6 @@ message Document { // Any error that occurred while processing this document. google.rpc.Status error = 10; - // Revision history of this document. + // Placeholder. Revision history of this document. repeated Revision revisions = 13; }