Azure/azure-sdk-for-js @azure/ai-form-recognizer_4.0.0-beta.3

on GitHub

4.0.0-beta.3 (2022-02-10)

Features Added

• Updated the SDK to use the latest preview version of the Form Recognizer service: 2022-01-30-preview.
• A new prebuilt model, PrebuiltModels.TaxUsW2, is available. It supports extracting data from United States W2 tax forms such as employee and employer information, IRS control number, tax withholding information, etc.
• Added a new method, beginReadDocument to DocumentAnalysisClient. This method uses the "prebuilt-read" model to extract textual information from the document such as page text contents and language spans.
• Added a languages field to the AnalyzeResult type. This field contains information about regions of text in the document that were identified as being of a particular written language. A DocumentLanguage consists of the identified languageCode (ISO 639-1 or BCP 47 language code), a list of spans of text that are of that language, and a confidence value (between zero and one) that the assessment is correct.
• Added a tags field to BuildModelOptions, GetCopyAuthorizationOptions, and ModelSummary. Tags are user-specified key-value pairs that are immutably associated with the model. If tags are provided when a model is created, the Form Recognizer service will return the same tags as part of the model's summary. The OperationInfo and TrainingPollOperationState of a model creation operation also produce the tags if they were provided in the BuildModelOptions.
• Models now report the service API version used to create the model and that will be used for analysis in the apiVersion field.
• Documents may now contain a new field type DocumentCurrencyField, which has an object with amount and currencySymbol fields as its value. This field is identified by the value "currency" in the kind field. The amount field contains the amount of the currency value, and the currencySymbol field may contain a three-letter currency symbol if one was identified for the field. For example, the text $100.50 may have an amount of 100.5 and a currencySymbol of "USD".
• Added support for setting the buildMode of a model building operation and introduced the "neural" build mode. Previous versions of the service and SDK only supported a single build mode that is now known as the "template" mode. Template models only accept documents that have the same basic page structure (i.e. a uniform visual appearance, or the same relative positioning of elements within the document), hence a fixed document "template." Neural models support document classes that have the same information, but different page structures. Examples of these documents include United States W2 tax forms, which all share the same information, but may vary in appearance by the company that created the document. Neural models currently only support English text, and are more costly and time-consuming to train and use for analysis, but should yield higher-quality results for English documents that do not follow a "template."
• The DocTypeInfo type now has a buildMode field that contains the build mode originally used to create the document type.

Breaking Changes

• Renamed the beginAnalyzeDocuments method of DocumentAnalysisClient to beginAnalyzeDocument for accuracy (only one input document is supported, though the document may contain multiple pages in certain file formats) and for consistency with other Azure SDK packages.
  • Renamed the options bag type AnalyzeDocumentsOptions to AnalyzeDocumentOptions for consistency with the method name.
• The buildMode parameter of DocumentModelAdminsitrationClient#beginBuildModel is a required parameter. To retain the same behavior as in previous versions, explicitly use the template build mode (pass the value "template" to the method).
• The GeneratedDocument type (as well as related types like GeneratedDocumentField) was removed from the public API and its uses replaced with unknown, as it is only intended for internal use. These types represented raw REST API response types that are not exposed at runtime by the client methods.
• Removed the Preview variant from the FormRecognizerApiVersion object because it will never be different from the Latest version in beta packages, and stable packages will not support it.
• Renamed beginExtractGenericDocument and GenericDocumentResult to beginExtractGeneralDocument and GeneralDocumentResult for consistency with other Form Recognizer SDK packages.
• Several of the prebuilt model schemas and result types have changed:
  • The document type naming convention has changed. Instead of separation by colons (e.g. "prebuilt:receipt"), prebuilt model document type names are now separated by periods and are no longer prefixed with "prebuilt" ("prebuilt:idDocument:driverLicense" becomes "idDocument.driverLicense", "prebuilt:invoice" becomes just "invoice").
  • In the prebuilt-invoice model, several numeric fields that represented amounts of money have been changed to a designated "currency" type. These include the subTotal, totalTax, invoiceTotal, amountDue, and previousUnpaidBalance fields of invoices and the amount, tax, and unitPrice fields of invoice items (a subfield of invoices).

Bugs Fixed

• The LayoutResult and GeneralDocumentResult types were missing the apiVersion, modelId, and content fields that are common to all other analysis results. This version adds them through a new interface, AnalyzeResultCommon, that includes these fields. LayoutResult, GeneralDocumentResult, ReadResult, and AnalyzeResult all now extend the AnalyzeResultCommon interface.
• The DocumentSignatureField interface was missing a type for its value property. The property existed at runtime, but no type information was available for this field. The value property has been added to the interface.

Other Changes

• Changed FormRecognizerCommonClientOptions to extend CommonClientOptions from @azure/core-client instead of PipelineOptions. CommonClientOptions itself extends PipelineOptions, so no fields are removed, but CommonClientOptions also includes httpClient and allowInsecureConnection fields to allow overriding the default HTTP client and using insecure connections (without SSL/TLS) respectively.