[Form Recognizer] API consistency and naming (Azure#22482)

* DocumentModelPoller

* CreateModelOptions

* more feedback

* regenerate

* build failures

* API Report

* swagger

* documentModelId revert

* feedback

* API view

* GetOperationResponse

* ErrorModel,

* feedback

* build fixes

* format

Author: HarshaNalluru

sdk/formrecognizer/ai-form-recognizer/review/ai-form-recognizer.api.md

@@ -52,13 +52,13 @@ export interface AnalyzeDocumentOptions<Result = AnalyzeResult<AnalyzedDocument>
 
 // @public
 export interface AnalyzeResult<Document = AnalyzedDocument> extends AnalyzeResultCommon {
-    documents: Document[];
-    keyValuePairs: DocumentKeyValuePair[];
-    languages: DocumentLanguage[];
-    pages: DocumentPage[];
-    paragraphs: DocumentParagraph[];
-    styles: DocumentStyle[];
-    tables: DocumentTable[];
+    documents?: Document[];
+    keyValuePairs?: DocumentKeyValuePair[];
+    languages?: DocumentLanguage[];
+    pages?: DocumentPage[];
+    paragraphs?: DocumentParagraph[];
+    styles?: DocumentStyle[];
+    tables?: DocumentTable[];
 }
 
 // @public
@@ -80,12 +80,20 @@ export interface ArrayFieldSchema<Item extends Readonly<FieldSchema> = Readonly<
 export { AzureKeyCredential }
 
 // @public
-export interface BoundingRegion extends HasBoundingPolygon {
-    pageNumber: number;
+export interface BeginBuildModelOptions extends CreateModelOptions {
+}
+
+// @public
+export interface BeginComposeModelOptions extends CreateModelOptions {
 }
 
 // @public
-export interface BuildModelOptions extends OperationOptions, CommonModelCreationOptions, PollerOptions<TrainingPollOperationState> {
+export interface BeginCopyModelOptions extends OperationOptions, PollerOptions<TrainingPollOperationState> {
+}
+
+// @public
+export interface BoundingRegion extends HasBoundingPolygon {
+    pageNumber: number;
 }
 
 // @public
@@ -197,7 +205,7 @@ export interface CopyAuthorization {
 }
 
 // @public
-export interface CopyModelOptions extends OperationOptions, PollerOptions<TrainingPollOperationState> {
+export interface CreateModelOptions extends OperationOptions, CommonModelCreationOptions, PollerOptions<TrainingPollOperationState> {
 }
 
 // @public
@@ -377,16 +385,16 @@ export class DocumentModelAdministrationClient {
     constructor(endpoint: string, credential: TokenCredential, options?: DocumentModelAdministrationClientOptions);
     constructor(endpoint: string, credential: KeyCredential, options?: DocumentModelAdministrationClientOptions);
     constructor(endpoint: string, credential: KeyCredential | TokenCredential, options?: DocumentModelAdministrationClientOptions);
-    beginBuildModel(modelId: string, containerUrl: string, buildMode: DocumentModelBuildMode, options?: BuildModelOptions): Promise<TrainingPoller>;
-    beginComposeModel(modelId: string, componentModelIds: Iterable<string>, options?: BuildModelOptions): Promise<TrainingPoller>;
-    beginCopyModelTo(sourceModelId: string, authorization: CopyAuthorization, options?: CopyModelOptions): Promise<TrainingPoller>;
+    beginBuildModel(modelId: string, containerUrl: string, buildMode: DocumentModelBuildMode, options?: BeginBuildModelOptions): Promise<DocumentModelPoller>;
+    beginComposeModel(modelId: string, componentModelIds: Iterable<string>, options?: BeginComposeModelOptions): Promise<DocumentModelPoller>;
+    beginCopyModelTo(sourceModelId: string, authorization: CopyAuthorization, options?: BeginCopyModelOptions): Promise<DocumentModelPoller>;
     deleteModel(modelId: string, options?: DeleteModelOptions): Promise<void>;
     getCopyAuthorization(destinationModelId: string, options?: GetCopyAuthorizationOptions): Promise<CopyAuthorization>;
-    getInfo(options?: GetInfoOptions): Promise<GetInfoResponse>;
-    getModel(modelId: string, options?: GetModelOptions): Promise<ModelInfo>;
+    getModel(modelId: string, options?: GetModelOptions): Promise<DocumentModelInfo>;
     getOperation(operationId: string, options?: GetOperationOptions): Promise<OperationInfo>;
-    listModels(options?: ListModelsOptions): PagedAsyncIterableIterator<ModelSummary>;
-    listOperations(options?: ListOperationsOptions): PagedAsyncIterableIterator<OperationInfo>;
+    getResourceInfo(options?: GetResourceInfoOptions): Promise<ResourceInfo>;
+    listModels(options?: ListModelsOptions): PagedAsyncIterableIterator<DocumentModelSummary>;
+    listOperations(options?: ListOperationsOptions): PagedAsyncIterableIterator<OperationSummary>;
 }
 
 // @public
@@ -402,6 +410,27 @@ export const DocumentModelBuildMode: {
     readonly Neural: "neural";
 };
 
+// @public
+export interface DocumentModelInfo extends DocumentModelSummary {
+    docTypes?: {
+        [propertyName: string]: DocTypeInfo;
+    };
+}
+
+// @public
+export type DocumentModelPoller = PollerLike<TrainingPollOperationState, DocumentModelInfo>;
+
+// @public
+export interface DocumentModelSummary {
+    apiVersion?: string;
+    createdDateTime: Date;
+    description?: string;
+    modelId: string;
+    tags?: {
+        [propertyName: string]: string;
+    };
+}
+
 // @public
 export interface DocumentNumberField extends DocumentValueField<number> {
     kind: "number";
@@ -531,6 +560,15 @@ export interface DocumentWord extends HasBoundingPolygon {
 // @public
 export type EnglishCapitalLetter = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z";
 
+// @public
+export interface ErrorModel {
+    code: string;
+    details?: ErrorModel[];
+    innererror?: InnerError;
+    message: string;
+    target?: string;
+}
+
 // @public
 export type FieldSchema = StringLikeFieldSchema | NumberFieldSchema | DateFieldSchema | ArrayFieldSchema | ObjectFieldSchema | StructuredStringFieldSchema | WellKnownObjectFieldSchema;
 
@@ -552,28 +590,26 @@ export type FormRecognizerRequestBody = NodeJS.ReadableStream | Blob | ArrayBuff
 
 // @public
 export interface GeneralDocumentResult extends LayoutResult {
-    keyValuePairs: DocumentKeyValuePair[];
+    keyValuePairs?: DocumentKeyValuePair[];
 }
 
 // @public
 export interface GetCopyAuthorizationOptions extends OperationOptions, CommonModelCreationOptions {
 }
 
 // @public
-export interface GetInfoOptions extends OperationOptions {
+export interface GetModelOptions extends OperationOptions {
 }
 
 // @public
-export interface GetInfoResponse {
-    customDocumentModels: CustomDocumentModelsInfo;
+export interface GetOperationOptions extends OperationOptions {
 }
 
 // @public
-export interface GetModelOptions extends OperationOptions {
-}
+export type GetOperationResponse = OperationInfo;
 
 // @public
-export interface GetOperationOptions extends OperationOptions {
+export interface GetResourceInfoOptions extends OperationOptions {
 }
 
 // @public
@@ -669,6 +705,13 @@ export const IdentityDocumentSchema: {
     };
 };
 
+// @public
+export interface InnerError {
+    code: string;
+    innererror?: InnerError;
+    message?: string;
+}
+
 // @public
 export type Invoice = ReifyPrebuiltSchema<typeof InvoiceSchema>;
 
@@ -814,9 +857,9 @@ export const InvoiceSchema: {
 
 // @public
 export interface LayoutResult {
-    pages: DocumentPage[];
-    styles: DocumentStyle[];
-    tables: DocumentTable[];
+    pages?: DocumentPage[];
+    styles?: DocumentStyle[];
+    tables?: DocumentTable[];
 }
 
 // @public
@@ -830,13 +873,6 @@ export interface ListModelsOptions extends OperationOptions {
 export interface ListOperationsOptions extends OperationOptions {
 }
 
-// @public
-export interface ModelInfo extends ModelSummary {
-    docTypes?: {
-        [propertyName: string]: DocTypeInfo;
-    };
-}
-
 // @public
 export interface ModelSchema {
     docTypes: {
@@ -849,17 +885,6 @@ export interface ModelSchema {
     modelId: string;
 }
 
-// @public
-export interface ModelSummary {
-    apiVersion?: string;
-    createdDateTime: Date;
-    description?: string;
-    modelId: string;
-    tags?: {
-        [propertyName: string]: string;
-    };
-}
-
 // @public
 export interface NumberFieldSchema<Type extends "number" | "integer" = "number" | "integer"> {
     readonly type: Type;
@@ -876,7 +901,19 @@ export interface ObjectFieldSchema<Properties extends {
 }
 
 // @public
-export interface OperationInfo {
+export interface OperationInfo extends OperationSummary {
+    error?: ErrorModel;
+    result?: Record<string, unknown>;
+}
+
+// @public
+export type OperationKind = string;
+
+// @public
+export type OperationStatus = "notStarted" | "running" | "failed" | "succeeded" | "canceled";
+
+// @public
+export interface OperationSummary {
     apiVersion?: string;
     createdDateTime: Date;
     kind: OperationKind;
@@ -890,12 +927,6 @@ export interface OperationInfo {
     };
 }
 
-// @public
-export type OperationKind = string;
-
-// @public
-export type OperationStatus = "notStarted" | "running" | "failed" | "succeeded" | "canceled";
-
 // @public
 export type ParagraphRole = string;
 
@@ -1098,9 +1129,9 @@ export const PrebuiltModels: {
 
 // @public
 export interface ReadResult extends AnalyzeResultCommon {
-    languages: DocumentLanguage[];
-    pages: DocumentPage[];
-    styles: DocumentStyle[];
+    languages?: DocumentLanguage[];
+    pages?: DocumentPage[];
+    styles?: DocumentStyle[];
 }
 
 // @public
@@ -1472,6 +1503,11 @@ export type ReifyPrebuiltSchema<Schema extends Readonly<ModelSchema>> = {
     };
 }[keyof Schema["docTypes"]];
 
+// @public
+export interface ResourceInfo {
+    customDocumentModels: CustomDocumentModelsInfo;
+}
+
 // @public
 export type SelectionMarkState = string;
 
@@ -1650,10 +1686,7 @@ export const TaxUsW2Schema: {
 };
 
 // @public
-export type TrainingPoller = PollerLike<TrainingPollOperationState, ModelInfo>;
-
-// @public
-export interface TrainingPollOperationState extends PollOperationState<ModelInfo> {
+export interface TrainingPollOperationState extends PollOperationState<DocumentModelInfo> {
     apiVersion?: string;
     createdOn: Date;
     lastUpdatedOn: Date;

sdk/formrecognizer/ai-form-recognizer/samples-dev/analyzeBusinessCard.ts

@@ -34,13 +34,11 @@ async function main() {
     "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/businessCard/business-card-english.jpg"
   );
 
-  const {
-    documents: [result],
-  } = await poller.pollUntilDone();
+  const { documents } = await poller.pollUntilDone();
 
   // Use of PrebuiltModels.Receipt above (rather than the raw model ID), adds strong typing of the model's output
-  if (result) {
-    const businessCard = result.fields;
+  if (documents) {
+    const businessCard = documents[0].fields;
     console.log("=== Business Card Information ===");
 
     // There are more fields than just these few, and the model allows for multiple contact & company names as well as

sdk/formrecognizer/ai-form-recognizer/samples-dev/analyzeDocumentByModelId.ts

@@ -25,10 +25,8 @@ async function main() {
     "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/receipt/contoso-receipt.png"
   );
 
-  const {
-    documents: [document],
-  } = await poller.pollUntilDone();
-
+  const { documents } = await poller.pollUntilDone();
+  const document = documents && documents[0];
   if (!document) {
     throw new Error("Expected at least one document in the result.");
   }

sdk/formrecognizer/ai-form-recognizer/samples-dev/analyzeIdentityDocument.ts

@@ -34,10 +34,8 @@ async function main() {
     "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/identityDocument/license.png"
   );
 
-  const {
-    documents: [result],
-  } = await poller.pollUntilDone();
-
+  const { documents } = await poller.pollUntilDone();
+  const result = documents && documents[0];
   // Use of PrebuiltModels.Receipt above (rather than the raw model ID), adds strong typing of the model's output
   if (result) {
     // The identity document model has multiple document types, so we need to know which document type was actually

sdk/formrecognizer/ai-form-recognizer/samples-dev/analyzeInvoice.ts

@@ -33,10 +33,9 @@ async function main() {
     "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/invoice/sample_invoice.jpg"
   );
 
-  const {
-    documents: [result],
-  } = await poller.pollUntilDone();
+  const { documents } = await poller.pollUntilDone();
 
+  const result = documents && documents[0];
   // Use of PrebuiltModels.Receipt above (rather than the raw model ID), adds strong typing of the model's output
   if (result) {
     const {

sdk/formrecognizer/ai-form-recognizer/samples-dev/analyzeReceipt.ts

@@ -33,10 +33,9 @@ async function main() {
     "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/receipt/contoso-receipt.png"
   );
 
-  const {
-    documents: [result],
-  } = await poller.pollUntilDone();
+  const { documents } = await poller.pollUntilDone();
 
+  const result = documents && documents[0];
   // Use of PrebuiltModels.Receipt above (rather than the raw model ID), as it adds strong typing of the model's output
   if (result) {
     const { merchantName, items, total } = result.fields;

sdk/formrecognizer/ai-form-recognizer/samples-dev/analyzeReceiptByModelId.ts

@@ -38,10 +38,9 @@ async function main() {
   );
   poller.onProgress((state) => console.log("Operation:", state.modelId, state.status));
 
-  const {
-    documents: [result],
-  } = await poller.pollUntilDone();
+  const { documents } = await poller.pollUntilDone();
 
+  const result = documents && documents[0];
   if (result) {
     const receipt = result.fields;
     console.log("=== Receipt Information ===");

sdk/formrecognizer/ai-form-recognizer/samples-dev/analyzeW2TaxForm.ts

@@ -34,10 +34,9 @@ async function main() {
 
   const poller = await client.beginAnalyzeDocument(PrebuiltModels.TaxUsW2, file);
 
-  const {
-    documents: [result],
-  } = await poller.pollUntilDone();
+  const { documents } = await poller.pollUntilDone();
 
+  const result = documents && documents[0];
   if (result) {
     const { employee, employer, controlNumber, taxYear, additionalInfo } = result.fields;
 

sdk/formrecognizer/ai-form-recognizer/samples-dev/extractGeneralDocument.ts

@@ -28,7 +28,7 @@ async function main() {
   // (associations between elements, such as labeled elements), and document entities.
   const { keyValuePairs } = await poller.pollUntilDone();
 
-  if (keyValuePairs.length <= 0) {
+  if (!keyValuePairs || keyValuePairs.length <= 0) {
     console.log("No key-value pairs were extracted from the document.");
   } else {
     console.log("Key-Value Pairs:");