From c30a385209a7cd37b3259995b1190dd7e554058f Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Wed, 17 Apr 2019 12:39:11 -0700 Subject: [PATCH 01/33] Initial commit. --- .../data-plane/Form/readme.go.md | 26 + .../data-plane/Form/readme.md | 72 ++ .../data-plane/Form/readme.nodejs.md | 14 + .../data-plane/Form/readme.python.md | 26 + .../data-plane/Form/readme.ruby.md | 27 + .../data-plane/Form/readme.typescript.md | 12 + .../data-plane/Form/stable/v1.0/Form.json | 731 ++++++++++++++++++ 7 files changed, 908 insertions(+) create mode 100644 specification/cognitiveservices/data-plane/Form/readme.go.md create mode 100644 specification/cognitiveservices/data-plane/Form/readme.md create mode 100644 specification/cognitiveservices/data-plane/Form/readme.nodejs.md create mode 100644 specification/cognitiveservices/data-plane/Form/readme.python.md create mode 100644 specification/cognitiveservices/data-plane/Form/readme.ruby.md create mode 100644 specification/cognitiveservices/data-plane/Form/readme.typescript.md create mode 100644 specification/cognitiveservices/data-plane/Form/stable/v1.0/Form.json diff --git a/specification/cognitiveservices/data-plane/Form/readme.go.md b/specification/cognitiveservices/data-plane/Form/readme.go.md new file mode 100644 index 000000000000..41c3e5a3d90d --- /dev/null +++ b/specification/cognitiveservices/data-plane/Form/readme.go.md @@ -0,0 +1,26 @@ +## Go + +These settings apply only when `--go` is specified on the command line. + +``` yaml $(go) +go: + license-header: MICROSOFT_APACHE_NO_VERSION + namespace: form + clear-output-folder: true +``` + +### Go multi-api + +``` yaml $(go) && $(multiapi) +batch: + - tag: release_1_0 +``` + +### Tag: release_1_0 and go + +These settings apply only when `--tag=release_1_0 --go` is specified on the command line. +Please also specify `--go-sdk-folder=`. + +``` yaml $(tag) == 'release_1_0' && $(go) +output-folder: $(go-sdk-folder)/services/cognitiveservices/v1.0/$(namespace) +``` \ No newline at end of file diff --git a/specification/cognitiveservices/data-plane/Form/readme.md b/specification/cognitiveservices/data-plane/Form/readme.md new file mode 100644 index 000000000000..1a36d7271c48 --- /dev/null +++ b/specification/cognitiveservices/data-plane/Form/readme.md @@ -0,0 +1,72 @@ +# Cognitive Services Form SDK + +> see https://aka.ms/autorest + +Configuration for generating Form SDK. + +The current release is `release_1_0`. + +``` yaml + +tag: release_1_0 +add-credentials: true +openapi-type: data-plane +``` +# Releases + +### Release 1.0 +These settings apply only when `--tag=release_1_0` is specified on the command line. + +``` yaml $(tag) == 'release_1_0' +input-file: stable/v1.0/Form.json +``` + +## Swagger to SDK + +This section describes what SDK should be generated by the automatic system. +This is not used by Autorest itself. + +``` yaml $(swagger-to-sdk) +swagger-to-sdk: + - repo: azure-sdk-for-python + - repo: azure-sdk-for-java + - repo: azure-sdk-for-go + - repo: azure-sdk-for-js + - repo: azure-sdk-for-node + - repo: azure-sdk-for-ruby + after_scripts: + - bundle install && rake arm:regen_all_profiles['azure_cognitiveservices_form'] +``` + + +## CSharp Settings +These settings apply only when `--csharp` is specified on the command line. +``` yaml $(csharp) +csharp: + sync-methods: None + license-header: MICROSOFT_MIT_NO_VERSION + azure-arm: false + namespace: Microsoft.Azure.CognitiveServices.Vision.Form + output-folder: $(csharp-sdks-folder)/CognitiveServices/dataPlane/Vision/Form/Form/Generated + clear-output-folder: true +``` + +## Go + +See configuration in [readme.go.md](./readme.go.md) + +## Java + +These settings apply only when `--java` is specified on the command line. +Please also specify `--azure-libraries-for-java-folder=`. + +``` yaml $(java) +java: + azure-arm: true + namespace: com.microsoft.azure.cognitiveservices.vision.formapi + license-header: MICROSOFT_MIT_NO_CODEGEN + payload-flattening-threshold: 1 + output-folder: $(azure-libraries-for-java-folder)/cognitiveservices/data-plane/vision/formapi + with-optional-parameters: true + with-single-async-method: true +``` diff --git a/specification/cognitiveservices/data-plane/Form/readme.nodejs.md b/specification/cognitiveservices/data-plane/Form/readme.nodejs.md new file mode 100644 index 000000000000..0b0af7f29835 --- /dev/null +++ b/specification/cognitiveservices/data-plane/Form/readme.nodejs.md @@ -0,0 +1,14 @@ +## Node.js + +These settings apply only when `--nodejs` is specified on the command line. +Please also specify `--node-sdks-folder=`. + +``` yaml $(nodejs) +nodejs: + package-name: azure-cognitiveservices-form + output-folder: $(node-sdks-folder)/lib/services/cognitiveServicesForm + azure-arm: false + generate-license-txt: true + generate-package-json: true + generate-readme-md: true +``` diff --git a/specification/cognitiveservices/data-plane/Form/readme.python.md b/specification/cognitiveservices/data-plane/Form/readme.python.md new file mode 100644 index 000000000000..050ec3a6e9ca --- /dev/null +++ b/specification/cognitiveservices/data-plane/Form/readme.python.md @@ -0,0 +1,26 @@ +## Python + +These settings apply only when `--python` is specified on the command line. +Please also specify `--python-sdks-folder=`. +Use `--python-mode=update` if you already have a setup.py and just want to update the code itself. + +``` yaml $(python) +python-mode: create +python: + license-header: MICROSOFT_MIT_NO_VERSION + add-credentials: true + payload-flattening-threshold: 2 + namespace: azure.cognitiveservices.vision.form + package-name: azure-cognitiveservices-vision-form + clear-output-folder: true +``` +``` yaml $(python) && $(python-mode) == 'update' +python: + no-namespace-folders: true + output-folder: $(python-sdks-folder)/azure-cognitiveservices-vision-form/azure/cognitiveservices/vision/form +``` +``` yaml $(python) && $(python-mode) == 'create' +python: + basic-setup-py: true + output-folder: $(python-sdks-folder)/azure-cognitiveservices-vision-form +``` diff --git a/specification/cognitiveservices/data-plane/Form/readme.ruby.md b/specification/cognitiveservices/data-plane/Form/readme.ruby.md new file mode 100644 index 000000000000..4d17040036c3 --- /dev/null +++ b/specification/cognitiveservices/data-plane/Form/readme.ruby.md @@ -0,0 +1,27 @@ +## Ruby + +These settings apply only when `--ruby` is specified on the command line. + +``` yaml +package-name: azure_cognitiveservices_form +package-version: "0.16.0" +azure-arm: true +``` + +### Ruby multi-api + +``` yaml $(ruby) && $(multiapi) +batch: + - tag: release_1_0 +``` + +### Tag: release_1_0 and ruby + +These settings apply only when `--tag=release_1_0 --ruby` is specified on the command line. +Please also specify `--ruby-sdks-folder=`. + +``` yaml $(tag) == 'release_1_0' && $(ruby) +namespace: "Azure::CognitiveServices::Form::V1_0" +output-folder: $(ruby-sdks-folder)/data/azure_cognitiveservices_form/lib +title: "FormClient" +``` diff --git a/specification/cognitiveservices/data-plane/Form/readme.typescript.md b/specification/cognitiveservices/data-plane/Form/readme.typescript.md new file mode 100644 index 000000000000..f66280e9cedf --- /dev/null +++ b/specification/cognitiveservices/data-plane/Form/readme.typescript.md @@ -0,0 +1,12 @@ +## TypeScript + +These settings apply only when `--typescript` is specified on the command line. +Please also specify `--typescript-sdks-folder=`. + +``` yaml $(typescript) +typescript: + package-name: "@azure/cognitiveservices-form" + output-folder: "$(typescript-sdks-folder)/sdk/cognitiveservices/cognitiveservices-form" + azure-arm: false + generate-metadata: true +``` diff --git a/specification/cognitiveservices/data-plane/Form/stable/v1.0/Form.json b/specification/cognitiveservices/data-plane/Form/stable/v1.0/Form.json new file mode 100644 index 000000000000..1a1d394d76cd --- /dev/null +++ b/specification/cognitiveservices/data-plane/Form/stable/v1.0/Form.json @@ -0,0 +1,731 @@ +{ + "swagger": "2.0", + "info": { + "version": "v1", + "title": "Cognitive Service Form Recognizer API V1 (Preview)", + "description": "Extracts information from forms and images into structured data based on a model created by a set of representative training forms." + }, + "securityDefinitions": { + "apim_key": { + "type": "apiKey", + "name": "Ocp-Apim-Subscription-Key", + "in": "header" + } + }, + "security": [ + { + "apim_key": [] + } + ], + "x-ms-parameterized-host": { + "hostTemplate": "{Endpoint}/form/v1.0", + "useSchemePrefix": false, + "parameters": [ + { + "$ref": "#/parameters/Endpoint" + } + ] + }, + "paths": { + "/formrecognizer/v1.0/custom/train": { + "post": { + "tags": [ + "Form" + ], + "summary": "Train a model to analyze using a set of documents of supported types.", + "description": "The train request must include a 'Source' parameter that is either a Azure Storage Blob Container SAS Uri or a path to a locally mounted drive. When local paths are specified, they must always follow the Linux/Unix style absolute path convention and be rooted to the {Mounts:Input} configuration setting value.", + "operationId": "FormrecognizerV1.0CustomTrainPost", + "consumes": [ + "application/json-patch+json", + "application/json", + "text/json", + "application/*+json" + ], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [ + { + "name": "trainRequest", + "in": "body", + "description": "Request object for training.", + "required": false, + "schema": { + "$ref": "#/definitions/TrainRequest" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/TrainResponse" + }, + "examples": { + "application/json": { + "modelId": "e390d2c0-0d6a-4a65-8277-597c0e863997", + "trainingDocuments": [ + { + "pages": 1, + "errors": [], + "status": "success" + } + ], + "errors": [ + { + "errorMessage": "Could not use 0.pdf for training." + } + ] + } + } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "examples": { + "application/json": { + "error": { + "code": "BadArgument", + "innerError": { + "requestId": "00000000-0000-0000-0000-000000000000" + }, + "message": "Request body is invalid." + } + } + } + } + } + } + }, + "/formrecognizer/v1.0/custom/model/{id}/keys": { + "get": { + "tags": [ + "Form" + ], + "summary": "Get keys of a model.", + "description": "Use the API to retrieve the keys that were\r\n extracted by the specified model.", + "operationId": "FormrecognizerV1.0CustomModelByIdKeysGet", + "consumes": [], + "produces": [], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Model identifier.", + "required": true, + "type": "string" + } + ], + "responses": { + "200": { + "description": "Success", + "examples": { + "application/json": { + "clusters": { + "0": [ + "Invoice", + "123112313" + ], + "1": [ + "Please remit payment to:", + "Microsoft" + ] + } + } + } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "examples": { + "application/json": { + "error": { + "code": "BadArgument", + "innerError": { + "requestId": "00000000-0000-0000-0000-000000000000" + }, + "message": "Request body is invalid." + } + } + } + } + } + } + }, + "/formrecognizer/v1.0/custom/model/{id}": { + "get": { + "tags": [ + "Form" + ], + "summary": "Get information about a model.", + "operationId": "FormrecognizerV1.0CustomModelByIdGet", + "consumes": [], + "produces": [], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Model identifier.", + "required": true, + "type": "string" + } + ], + "responses": { + "200": { + "description": "Success", + "examples": { + "application/json": { + "modelId": "708846bd-1fb2-49e1-a12f-9306e97bd473", + "version": "1", + "status": "ready", + "createdDateTime": "2019-04-17T16:04:35.4859654Z", + "lastUpdatedDateTime": "0001-01-01T00:00:00" + } + } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "examples": { + "application/json": { + "error": { + "code": "BadArgument", + "innerError": { + "requestId": "00000000-0000-0000-0000-000000000000" + }, + "message": "Request body is invalid." + } + } + } + } + } + }, + "delete": { + "tags": [ + "Form" + ], + "summary": "Delete a model and all associated pre-processing data.", + "operationId": "FormrecognizerV1.0CustomModelByIdDelete", + "consumes": [], + "produces": [], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "The identifier of the model to delete.", + "required": true, + "type": "string" + } + ], + "responses": { + "204": { + "description": "Success" + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "examples": { + "application/json": { + "error": { + "code": "BadArgument", + "innerError": { + "requestId": "00000000-0000-0000-0000-000000000000" + }, + "message": "Request body is invalid." + } + } + } + } + } + } + }, + "/formrecognizer/v1.0/custom/model/{id}/analyze": { + "post": { + "tags": [ + "Form" + ], + "summary": "Analyze a document to extract key-value pairs and table\r\ninformation.", + "description": "The document to analyze must be must be of expected\r\n media type - currently supported types are application/pdf, image/jpg or image/png.", + "operationId": "FormrecognizerV1.0CustomModelByIdAnalyzePost", + "consumes": [ + "multipart/form-data" + ], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Identifier of the model to analyze the document with.", + "required": true, + "type": "string" + }, + { + "name": "keys", + "in": "query", + "description": "An optional list of known keys to extract the values for.", + "required": false, + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "uniqueItems": false + }, + { + "name": "form", + "in": "formData", + "description": "Upload image or pdf content for processing.", + "required": false, + "type": "file" + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/AnalyzeResponse" + }, + "examples": { + "application/json": { + "status": "success", + "pages": [ + { + "number": 1, + "height": 800, + "width": 600, + "clusterId": 0, + "keyValuePairs": [ + { + "key": [ + { + "text": "Address:", + "boundingBox": [ + 57.4, + 683.1, + 100.5, + 683.1, + 100.5, + 673.7, + 57.4, + 673.7 + ] + } + ], + "value": [ + { + "text": "1 Microsoft Way", + "boundingBox": [ + 57.4, + 672.2, + 126.6, + 672.2, + 126.6, + 658.9, + 57.4, + 658.9 + ], + "confidence": 0.9 + } + ] + } + ], + "tables": [ + { + "id": "table_0", + "columns": [ + { + "header": [ + { + "text": "InvoiceNumber", + "boundingBox": [ + 38.5, + 585.2, + 113.4, + 585.2, + 113.4, + 575.8, + 38.5, + 575.8 + ] + } + ], + "entries": [ + [ + { + "text": "38772349", + "boundingBox": [ + 305.6, + 692.1, + 403.5, + 692.1, + 403.5, + 684.2, + 305.6, + 684.2 + ], + "confidence": 0.9 + } + ] + ] + } + ] + } + ] + } + ], + "errors": [ + { + "errorMessage": "Page1: Field not extracted" + } + ] + } + } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "examples": { + "application/json": { + "error": { + "code": "BadArgument", + "innerError": { + "requestId": "00000000-0000-0000-0000-000000000000" + }, + "message": "Request body is invalid." + } + } + } + } + } + } + }, + "/status": { + "get": { + "tags": [ + "Status" + ], + "operationId": "StatusGet", + "consumes": [], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/ContainerStatus" + } + } + } + } + } + }, + "definitions": { + "TrainRequest": { + "description": "Contract to initiate a train request.", + "required": [ + "source" + ], + "type": "object", + "properties": { + "source": { + "description": "Get or set source path.", + "maxLength": 2048, + "minLength": 0, + "type": "string" + } + } + }, + "TrainResponse": { + "description": "Response of the Train API call.", + "type": "object", + "properties": { + "modelId": { + "description": "Identifier of the model.", + "type": "string" + }, + "trainingDocuments": { + "description": "List of documents used to train the model and the\r\ntrain operation error reported by each.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/FormDocumentReport" + } + }, + "errors": { + "description": "Errors returned during the training operation.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/FormOperationError" + } + } + } + }, + "FormDocumentReport": { + "type": "object", + "properties": { + "documentName": { + "description": "Reference to the data that the report is for.", + "type": "string" + }, + "pages": { + "format": "int32", + "description": "Total number of pages trained on.", + "type": "integer" + }, + "errors": { + "description": "List of errors per page.", + "uniqueItems": false, + "type": "array", + "items": { + "type": "string" + } + }, + "status": { + "description": "Status of the training operation.", + "enum": [ + "success", + "partialSuccess", + "failure" + ], + "type": "string" + } + } + }, + "FormOperationError": { + "description": "Error reported during an operation.", + "type": "object", + "properties": { + "errorMessage": { + "description": "Message reported during the train operation.", + "type": "string" + } + } + }, + "ErrorResponse": { + "type": "object", + "properties": { + "error": { + "$ref": "#/definitions/ErrorInformation" + } + } + }, + "ErrorInformation": { + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "innerError": { + "$ref": "#/definitions/InnerError" + }, + "message": { + "type": "string" + } + } + }, + "InnerError": { + "type": "object", + "properties": { + "requestId": { + "type": "string" + } + } + }, + "AnalyzeResponse": { + "description": "Analyze API response.", + "type": "object", + "properties": { + "status": { + "description": "Status of the analyze operation.", + "enum": [ + "success", + "partialSuccess", + "failure" + ], + "type": "string" + }, + "pages": { + "description": "Page level information extracted in the analyzed\r\ndocument.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/Page" + } + }, + "errors": { + "description": "List of errors reported during the analyze\r\noperation.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/FormOperationError" + } + } + } + }, + "Page": { + "description": "Extraction information of a single page in a\r\nwith a document.", + "type": "object", + "properties": { + "number": { + "format": "int32", + "description": "Page number.", + "type": "integer" + }, + "height": { + "format": "int32", + "description": "Height of the page (in pixels).", + "type": "integer" + }, + "width": { + "format": "int32", + "description": "Width of the page (in pixels).", + "type": "integer" + }, + "clusterId": { + "format": "int32", + "description": "Cluster identifier.", + "type": "integer" + }, + "keyValuePairs": { + "description": "List of Key-Value pairs extracted from the page.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/KeyValuePair" + } + }, + "tables": { + "description": "List of Tables and their information extracted from the page.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/Table" + } + } + } + }, + "KeyValuePair": { + "description": "Representation of a key-value pair as a list\r\nof key and value tokens.", + "type": "object", + "properties": { + "key": { + "description": "List of tokens for the extracted key in a key-value pair.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/Token" + } + }, + "value": { + "description": "List of tokens for the extracted value in a key-value pair.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/Token" + } + } + } + }, + "Table": { + "description": "Extraction information about a table\r\ncontained in a page.", + "type": "object", + "properties": { + "id": { + "description": "Table identifier.", + "type": "string" + }, + "columns": { + "description": "List of columns contained in the table.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/TableColumn" + } + } + } + }, + "Token": { + "description": "Canonical representation of single extracted text.", + "type": "object", + "properties": { + "text": { + "description": "String value of the extracted text.", + "type": "string" + }, + "boundingBox": { + "description": "Bounding box of the extracted text. Represents the\r\nlocation of the extracted text as a pair of\r\ncartesian co-ordinates. The co-ordinate pairs are arranged by\r\ntop-left, top-right, bottom-right and bottom-left endpoints box\r\nwith origin reference from the bottom-left of the page.", + "uniqueItems": false, + "type": "array", + "items": { + "format": "double", + "type": "number" + } + }, + "confidence": { + "format": "double", + "description": "A measure of accuracy of the extracted text.", + "type": "number" + } + } + }, + "TableColumn": { + "description": "Extraction information of a column in\r\na table.", + "type": "object", + "properties": { + "header": { + "description": "List of extracted tokens for the column header.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/Token" + } + }, + "entries": { + "description": "Extracted text for each cell of a column. Each cell\r\nin the column can have a list of one or more tokens.", + "uniqueItems": false, + "type": "array", + "items": { + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/Token" + } + } + } + } + }, + "ContainerStatus": { + "type": "object", + "properties": { + "service": { + "type": "string" + }, + "apiStatus": { + "type": "string" + }, + "apiStatusMessage": { + "type": "string" + } + } + } + }, + "tags": [] +} \ No newline at end of file From 00e4cf31faed7e55077cf580c8614e64c97fd990 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Wed, 17 Apr 2019 17:20:50 -0700 Subject: [PATCH 02/33] Incorporating PR feedback --- .../data-plane/FormRecognizer/readme.go.md | 26 + .../data-plane/FormRecognizer/readme.md | 72 ++ .../FormRecognizer/readme.nodejs.md | 14 + .../FormRecognizer/readme.python.md | 26 + .../data-plane/FormRecognizer/readme.ruby.md | 27 + .../FormRecognizer/readme.typescript.md | 12 + .../stable/v1.0/FormRecognizer.json | 723 ++++++++++++++++++ 7 files changed, 900 insertions(+) create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/readme.go.md create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/readme.md create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/readme.nodejs.md create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/readme.python.md create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/readme.ruby.md create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/readme.typescript.md create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/readme.go.md b/specification/cognitiveservices/data-plane/FormRecognizer/readme.go.md new file mode 100644 index 000000000000..f27d16b9f5f3 --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/readme.go.md @@ -0,0 +1,26 @@ +## Go + +These settings apply only when `--go` is specified on the command line. + +``` yaml $(go) +go: + license-header: MICROSOFT_APACHE_NO_VERSION + namespace: formrecognizer + clear-output-folder: true +``` + +### Go multi-api + +``` yaml $(go) && $(multiapi) +batch: + - tag: release_1_0 +``` + +### Tag: release_1_0 and go + +These settings apply only when `--tag=release_1_0 --go` is specified on the command line. +Please also specify `--go-sdk-folder=`. + +``` yaml $(tag) == 'release_1_0' && $(go) +output-folder: $(go-sdk-folder)/services/cognitiveservices/v1.0/$(namespace) +``` \ No newline at end of file diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md new file mode 100644 index 000000000000..aab5be30eaf9 --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md @@ -0,0 +1,72 @@ +# Cognitive Services Form Recognizer SDK + +> see https://aka.ms/autorest + +Configuration for generating Form Recognizer SDK. + +The current release is `release_1_0`. + +``` yaml + +tag: release_1_0 +add-credentials: true +openapi-type: data-plane +``` +# Releases + +### Release 1.0 +These settings apply only when `--tag=release_1_0` is specified on the command line. + +``` yaml $(tag) == 'release_1_0' +input-file: stable/v1.0/formrecognizer.json +``` + +## Swagger to SDK + +This section describes what SDK should be generated by the automatic system. +This is not used by Autorest itself. + +``` yaml $(swagger-to-sdk) +swagger-to-sdk: + - repo: azure-sdk-for-python + - repo: azure-sdk-for-java + - repo: azure-sdk-for-go + - repo: azure-sdk-for-js + - repo: azure-sdk-for-node + - repo: azure-sdk-for-ruby + after_scripts: + - bundle install && rake arm:regen_all_profiles['azure_cognitiveservices_formrecognizer'] +``` + + +## CSharp Settings +These settings apply only when `--csharp` is specified on the command line. +``` yaml $(csharp) +csharp: + sync-methods: None + license-header: MICROSOFT_MIT_NO_VERSION + azure-arm: false + namespace: Microsoft.Azure.CognitiveServices.Vision.formrecognizer + output-folder: $(csharp-sdks-folder)/CognitiveServices/dataPlane/Vision/FormRecognizer/Generated + clear-output-folder: true +``` + +## Go + +See configuration in [readme.go.md](./readme.go.md) + +## Java + +These settings apply only when `--java` is specified on the command line. +Please also specify `--azure-libraries-for-java-folder=`. + +``` yaml $(java) +java: + azure-arm: true + namespace: com.microsoft.azure.cognitiveservices.vision.formrecognizer + license-header: MICROSOFT_MIT_NO_CODEGEN + payload-flattening-threshold: 1 + output-folder: $(azure-libraries-for-java-folder)/cognitiveservices/data-plane/vision/formrecognizer + with-optional-parameters: true + with-single-async-method: true +``` diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/readme.nodejs.md b/specification/cognitiveservices/data-plane/FormRecognizer/readme.nodejs.md new file mode 100644 index 000000000000..dfd76a33e82f --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/readme.nodejs.md @@ -0,0 +1,14 @@ +## Node.js + +These settings apply only when `--nodejs` is specified on the command line. +Please also specify `--node-sdks-folder=`. + +``` yaml $(nodejs) +nodejs: + package-name: azure-cognitiveservices-formrecognizer + output-folder: $(node-sdks-folder)/lib/services/cognitiveServicesFormRecognizer + azure-arm: false + generate-license-txt: true + generate-package-json: true + generate-readme-md: true +``` diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/readme.python.md b/specification/cognitiveservices/data-plane/FormRecognizer/readme.python.md new file mode 100644 index 000000000000..f92f5959c18b --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/readme.python.md @@ -0,0 +1,26 @@ +## Python + +These settings apply only when `--python` is specified on the command line. +Please also specify `--python-sdks-folder=`. +Use `--python-mode=update` if you already have a setup.py and just want to update the code itself. + +``` yaml $(python) +python-mode: create +python: + license-header: MICROSOFT_MIT_NO_VERSION + add-credentials: true + payload-flattening-threshold: 2 + namespace: azure.cognitiveservices.vision.formrecognizer + package-name: azure-cognitiveservices-vision-formrecognizer + clear-output-folder: true +``` +``` yaml $(python) && $(python-mode) == 'update' +python: + no-namespace-folders: true + output-folder: $(python-sdks-folder)/azure-cognitiveservices-vision-formrecognizer/azure/cognitiveservices/vision/formrecognizer +``` +``` yaml $(python) && $(python-mode) == 'create' +python: + basic-setup-py: true + output-folder: $(python-sdks-folder)/azure-cognitiveservices-vision-formrecognizer +``` diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/readme.ruby.md b/specification/cognitiveservices/data-plane/FormRecognizer/readme.ruby.md new file mode 100644 index 000000000000..b1212ecca1ab --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/readme.ruby.md @@ -0,0 +1,27 @@ +## Ruby + +These settings apply only when `--ruby` is specified on the command line. + +``` yaml +package-name: azure_cognitiveservices_formrecognizer +package-version: "0.16.0" +azure-arm: true +``` + +### Ruby multi-api + +``` yaml $(ruby) && $(multiapi) +batch: + - tag: release_1_0 +``` + +### Tag: release_1_0 and ruby + +These settings apply only when `--tag=release_1_0 --ruby` is specified on the command line. +Please also specify `--ruby-sdks-folder=`. + +``` yaml $(tag) == 'release_1_0' && $(ruby) +namespace: "Azure::CognitiveServices::FormReognizer::V1_0" +output-folder: $(ruby-sdks-folder)/data/azure_cognitiveservices_formrecognizer/lib +title: "FormClient" +``` diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/readme.typescript.md b/specification/cognitiveservices/data-plane/FormRecognizer/readme.typescript.md new file mode 100644 index 000000000000..eb00a054ac7c --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/readme.typescript.md @@ -0,0 +1,12 @@ +## TypeScript + +These settings apply only when `--typescript` is specified on the command line. +Please also specify `--typescript-sdks-folder=`. + +``` yaml $(typescript) +typescript: + package-name: "@azure/cognitiveservices-formrecognizer" + output-folder: "$(typescript-sdks-folder)/sdk/cognitiveservices/cognitiveservices-formrecognizer" + azure-arm: false + generate-metadata: true +``` diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json new file mode 100644 index 000000000000..9ed79c6b76f0 --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json @@ -0,0 +1,723 @@ +{ + "swagger": "2.0", + "info": { + "version": "v1", + "title": "Cognitive Service Form Recognizer API V1 (Preview)", + "description": "Extracts information from forms and images into structured data based on a model created by a set of representative training forms." + }, + "securityDefinitions": { + "apim_key": { + "type": "apiKey", + "name": "Ocp-Apim-Subscription-Key", + "in": "header" + } + }, + "security": [ + { + "apim_key": [] + } + ], + "x-ms-parameterized-host": { + "hostTemplate": "{Endpoint}/FormRecognizer/v1.0", + "useSchemePrefix": false, + "parameters": [ + { + "$ref": "#/parameters/Endpoint" + } + ] + }, + "paths": { + "/train": { + "post": { + "summary": "Train a model to analyze using a set of documents of supported types.", + "description": "The train request must include a 'Source' parameter that is\r\n either a Azure Storage Blob Container SAS Uri or a path to a locally mounted\r\n drive. When local paths are specified, they must always follow the Linux/Unix style\r\n absolute path convention and be rooted to the {Mounts:Input}\r\n configuration setting value.", + "operationId": "Formrecognizer_Train", + "consumes": [ + "application/json-patch+json", + "application/json", + "text/json", + "application/*+json" + ], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [ + { + "name": "trainRequest", + "in": "body", + "description": "Request object for training.", + "required": false, + "schema": { + "$ref": "#/definitions/TrainRequest" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/TrainResponse" + }, + "examples": { + "application/json": { + "modelId": "e390d2c0-0d6a-4a65-8277-597c0e863997", + "trainingDocuments": [ + { + "pages": 1, + "errors": [], + "status": "success" + } + ], + "errors": [ + { + "errorMessage": "Could not use 0.pdf for training." + } + ] + } + } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "examples": { + "application/json": { + "error": { + "code": "BadArgument", + "innerError": { + "requestId": "00000000-0000-0000-0000-000000000000" + }, + "message": "Request body is invalid." + } + } + } + } + } + } + }, + "/model/{id}/keys": { + "get": { + "summary": "Get keys of a model.", + "description": "Use the API to retrieve the keys that were\r\n extracted by the specified model.", + "operationId": "Formrecognizer_GetKeysByModelId", + "consumes": [], + "produces": [], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Model identifier.", + "required": true, + "type": "string" + } + ], + "responses": { + "200": { + "description": "Success", + "examples": { + "application/json": { + "clusters": { + "0": [ + "Invoice", + "123112313" + ], + "1": [ + "Please remit payment to:", + "Microsoft" + ] + } + } + } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "examples": { + "application/json": { + "error": { + "code": "BadArgument", + "innerError": { + "requestId": "00000000-0000-0000-0000-000000000000" + }, + "message": "Request body is invalid." + } + } + } + } + } + } + }, + "/model/{id}": { + "get": { + "summary": "Get information about a model.", + "operationId": "Formrecognizer_GetModelById", + "consumes": [], + "produces": [], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Model identifier.", + "required": true, + "type": "string" + } + ], + "responses": { + "200": { + "description": "Success", + "examples": { + "application/json": { + "modelId": "708846bd-1fb2-49e1-a12f-9306e97bd473", + "version": "1", + "status": "ready", + "createdDateTime": "2019-04-17T16:04:35.4859654Z", + "lastUpdatedDateTime": "0001-01-01T00:00:00" + } + } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "examples": { + "application/json": { + "error": { + "code": "BadArgument", + "innerError": { + "requestId": "00000000-0000-0000-0000-000000000000" + }, + "message": "Request body is invalid." + } + } + } + } + } + }, + "delete": { + "summary": "Delete a model and all associated pre-processing data.", + "operationId": "Formrecognizer_DeleteModelById", + "consumes": [], + "produces": [], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "The identifier of the model to delete.", + "required": true, + "type": "string" + } + ], + "responses": { + "204": { + "description": "Success" + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "examples": { + "application/json": { + "error": { + "code": "BadArgument", + "innerError": { + "requestId": "00000000-0000-0000-0000-000000000000" + }, + "message": "Request body is invalid." + } + } + } + } + } + } + }, + "/model/{id}/analyze": { + "post": { + "summary": "Analyze a document to extract key-value pairs and table\r\ninformation.", + "description": "The document to analyze must be must be of expected\r\n media type - currently supported types are application/pdf, image/jpg or image/png.", + "operationId": "Formrecognizer_Analyze", + "consumes": [ + "multipart/form-data" + ], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Identifier of the model to analyze the document with.", + "required": true, + "type": "string" + }, + { + "name": "keys", + "in": "query", + "description": "An optional list of known keys to extract the values for.", + "required": false, + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "uniqueItems": false + }, + { + "name": "form", + "in": "formData", + "description": "Upload image or pdf content for processing.", + "required": false, + "type": "file" + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/AnalyzeResponse" + }, + "examples": { + "application/json": { + "status": "success", + "pages": [ + { + "number": 1, + "height": 800, + "width": 600, + "clusterId": 0, + "keyValuePairs": [ + { + "key": [ + { + "text": "Address:", + "boundingBox": [ + 57.4, + 683.1, + 100.5, + 683.1, + 100.5, + 673.7, + 57.4, + 673.7 + ] + } + ], + "value": [ + { + "text": "1 Microsoft Way", + "boundingBox": [ + 57.4, + 672.2, + 126.6, + 672.2, + 126.6, + 658.9, + 57.4, + 658.9 + ], + "confidence": 0.9 + } + ] + } + ], + "tables": [ + { + "id": "table_0", + "columns": [ + { + "header": [ + { + "text": "InvoiceNumber", + "boundingBox": [ + 38.5, + 585.2, + 113.4, + 585.2, + 113.4, + 575.8, + 38.5, + 575.8 + ] + } + ], + "entries": [ + [ + { + "text": "38772349", + "boundingBox": [ + 305.6, + 692.1, + 403.5, + 692.1, + 403.5, + 684.2, + 305.6, + 684.2 + ], + "confidence": 0.9 + } + ] + ] + } + ] + } + ] + } + ], + "errors": [ + { + "errorMessage": "Page1: Field not extracted" + } + ] + } + } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "examples": { + "application/json": { + "error": { + "code": "BadArgument", + "innerError": { + "requestId": "00000000-0000-0000-0000-000000000000" + }, + "message": "Request body is invalid." + } + } + } + } + } + } + }, + "/status": { + "get": { + "operationId": "StatusGet", + "consumes": [], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/ContainerStatus" + } + } + } + } + } + }, + "definitions": { + "TrainRequest": { + "description": "Contract to initiate a train request.", + "required": [ + "source" + ], + "type": "object", + "properties": { + "source": { + "description": "Get or set source path.", + "maxLength": 2048, + "minLength": 0, + "type": "string" + } + } + }, + "TrainResponse": { + "description": "Response of the Train API call.", + "type": "object", + "properties": { + "modelId": { + "description": "Identifier of the model.", + "type": "string" + }, + "trainingDocuments": { + "description": "List of documents used to train the model and the\r\ntrain operation error reported by each.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/FormDocumentReport" + } + }, + "errors": { + "description": "Errors returned during the training operation.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/FormOperationError" + } + } + } + }, + "FormDocumentReport": { + "type": "object", + "properties": { + "documentName": { + "description": "Reference to the data that the report is for.", + "type": "string" + }, + "pages": { + "format": "int32", + "description": "Total number of pages trained on.", + "type": "integer" + }, + "errors": { + "description": "List of errors per page.", + "uniqueItems": false, + "type": "array", + "items": { + "type": "string" + } + }, + "status": { + "description": "Status of the training operation.", + "enum": [ + "success", + "partialSuccess", + "failure" + ], + "type": "string" + } + } + }, + "FormOperationError": { + "description": "Error reported during an operation.", + "type": "object", + "properties": { + "errorMessage": { + "description": "Message reported during the train operation.", + "type": "string" + } + } + }, + "ErrorResponse": { + "type": "object", + "properties": { + "error": { + "$ref": "#/definitions/ErrorInformation" + } + } + }, + "ErrorInformation": { + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "innerError": { + "$ref": "#/definitions/InnerError" + }, + "message": { + "type": "string" + } + } + }, + "InnerError": { + "type": "object", + "properties": { + "requestId": { + "type": "string" + } + } + }, + "AnalyzeResponse": { + "description": "Analyze API response.", + "type": "object", + "properties": { + "status": { + "description": "Status of the analyze operation.", + "enum": [ + "success", + "partialSuccess", + "failure" + ], + "type": "string" + }, + "pages": { + "description": "Page level information extracted in the analyzed\r\ndocument.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/Page" + } + }, + "errors": { + "description": "List of errors reported during the analyze\r\noperation.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/FormOperationError" + } + } + } + }, + "Page": { + "description": "Extraction information of a single page in a\r\nwith a document.", + "type": "object", + "properties": { + "number": { + "format": "int32", + "description": "Page number.", + "type": "integer" + }, + "height": { + "format": "int32", + "description": "Height of the page (in pixels).", + "type": "integer" + }, + "width": { + "format": "int32", + "description": "Width of the page (in pixels).", + "type": "integer" + }, + "clusterId": { + "format": "int32", + "description": "Cluster identifier.", + "type": "integer" + }, + "keyValuePairs": { + "description": "List of Key-Value pairs extracted from the page.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/KeyValuePair" + } + }, + "tables": { + "description": "List of Tables and their information extracted from the page.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/Table" + } + } + } + }, + "KeyValuePair": { + "description": "Representation of a key-value pair as a list\r\nof key and value tokens.", + "type": "object", + "properties": { + "key": { + "description": "List of tokens for the extracted key in a key-value pair.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/Token" + } + }, + "value": { + "description": "List of tokens for the extracted value in a key-value pair.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/Token" + } + } + } + }, + "Table": { + "description": "Extraction information about a table\r\ncontained in a page.", + "type": "object", + "properties": { + "id": { + "description": "Table identifier.", + "type": "string" + }, + "columns": { + "description": "List of columns contained in the table.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/TableColumn" + } + } + } + }, + "Token": { + "description": "Canonical representation of single extracted text.", + "type": "object", + "properties": { + "text": { + "description": "String value of the extracted text.", + "type": "string" + }, + "boundingBox": { + "description": "Bounding box of the extracted text. Represents the\r\nlocation of the extracted text as a pair of\r\ncartesian co-ordinates. The co-ordinate pairs are arranged by\r\ntop-left, top-right, bottom-right and bottom-left endpoints box\r\nwith origin reference from the bottom-left of the page.", + "uniqueItems": false, + "type": "array", + "items": { + "format": "double", + "type": "number" + } + }, + "confidence": { + "format": "double", + "description": "A measure of accuracy of the extracted text.", + "type": "number" + } + } + }, + "TableColumn": { + "description": "Extraction information of a column in\r\na table.", + "type": "object", + "properties": { + "header": { + "description": "List of extracted tokens for the column header.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/Token" + } + }, + "entries": { + "description": "Extracted text for each cell of a column. Each cell\r\nin the column can have a list of one or more tokens.", + "uniqueItems": false, + "type": "array", + "items": { + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/Token" + } + } + } + } + }, + "ContainerStatus": { + "type": "object", + "properties": { + "service": { + "type": "string" + }, + "apiStatus": { + "type": "string" + }, + "apiStatusMessage": { + "type": "string" + } + } + } + }, + "parameters": { + "Endpoint": { + "name": "Endpoint", + "description": "Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).", + "x-ms-parameter-location": "client", + "required": true, + "type": "string", + "in": "path", + "x-ms-skip-url-encoding": true + } + } +} \ No newline at end of file From 8dbcee713d472e1f9a8096507bc4ce4203b86eae Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Thu, 18 Apr 2019 07:48:03 -0700 Subject: [PATCH 03/33] Adding examples, cleanup. --- .../data-plane/Face/stable/v1.0/Face.json | 13 +- .../data-plane/Form/readme.go.md | 26 - .../data-plane/Form/readme.md | 72 -- .../data-plane/Form/readme.nodejs.md | 14 - .../data-plane/Form/readme.python.md | 26 - .../data-plane/Form/readme.ruby.md | 27 - .../data-plane/Form/readme.typescript.md | 12 - .../data-plane/Form/stable/v1.0/Form.json | 731 ------------------ .../data-plane/FormRecognizer/readme.md | 1 - .../stable/v1.0/FormRecognizer.json | 26 + .../stable/v1.0/examples/Analyze.json | 110 +++ .../stable/v1.0/examples/DeleteModelById.json | 16 + .../stable/v1.0/examples/GetKeys.json | 28 + .../stable/v1.0/examples/GetModelById.json | 24 + .../stable/v1.0/examples/GetStatus.json | 21 + .../stable/v1.0/examples/Train.json | 31 + 16 files changed, 258 insertions(+), 920 deletions(-) delete mode 100644 specification/cognitiveservices/data-plane/Form/readme.go.md delete mode 100644 specification/cognitiveservices/data-plane/Form/readme.md delete mode 100644 specification/cognitiveservices/data-plane/Form/readme.nodejs.md delete mode 100644 specification/cognitiveservices/data-plane/Form/readme.python.md delete mode 100644 specification/cognitiveservices/data-plane/Form/readme.ruby.md delete mode 100644 specification/cognitiveservices/data-plane/Form/readme.typescript.md delete mode 100644 specification/cognitiveservices/data-plane/Form/stable/v1.0/Form.json create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Analyze.json create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/DeleteModelById.json create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetKeys.json create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetModelById.json create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetStatus.json create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Train.json diff --git a/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json b/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json index 5ccdf42ae6d6..d0aa9bbd92b9 100644 --- a/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json +++ b/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json @@ -17,15 +17,6 @@ "apim_key": [] } ], - "x-ms-parameterized-host": { - "hostTemplate": "{Endpoint}/face/v1.0", - "useSchemePrefix": false, - "parameters": [ - { - "$ref": "#/parameters/Endpoint" - } - ] - }, "paths": { "/findsimilars": { "post": { @@ -4203,8 +4194,8 @@ "x-ms-parameter-location": "method", "collectionFormat": "csv" }, - "Endpoint": { - "name": "Endpoint", + "endpoint": { + "name": "endpoint", "description": "Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).", "x-ms-parameter-location": "client", "required": true, diff --git a/specification/cognitiveservices/data-plane/Form/readme.go.md b/specification/cognitiveservices/data-plane/Form/readme.go.md deleted file mode 100644 index 41c3e5a3d90d..000000000000 --- a/specification/cognitiveservices/data-plane/Form/readme.go.md +++ /dev/null @@ -1,26 +0,0 @@ -## Go - -These settings apply only when `--go` is specified on the command line. - -``` yaml $(go) -go: - license-header: MICROSOFT_APACHE_NO_VERSION - namespace: form - clear-output-folder: true -``` - -### Go multi-api - -``` yaml $(go) && $(multiapi) -batch: - - tag: release_1_0 -``` - -### Tag: release_1_0 and go - -These settings apply only when `--tag=release_1_0 --go` is specified on the command line. -Please also specify `--go-sdk-folder=`. - -``` yaml $(tag) == 'release_1_0' && $(go) -output-folder: $(go-sdk-folder)/services/cognitiveservices/v1.0/$(namespace) -``` \ No newline at end of file diff --git a/specification/cognitiveservices/data-plane/Form/readme.md b/specification/cognitiveservices/data-plane/Form/readme.md deleted file mode 100644 index 1a36d7271c48..000000000000 --- a/specification/cognitiveservices/data-plane/Form/readme.md +++ /dev/null @@ -1,72 +0,0 @@ -# Cognitive Services Form SDK - -> see https://aka.ms/autorest - -Configuration for generating Form SDK. - -The current release is `release_1_0`. - -``` yaml - -tag: release_1_0 -add-credentials: true -openapi-type: data-plane -``` -# Releases - -### Release 1.0 -These settings apply only when `--tag=release_1_0` is specified on the command line. - -``` yaml $(tag) == 'release_1_0' -input-file: stable/v1.0/Form.json -``` - -## Swagger to SDK - -This section describes what SDK should be generated by the automatic system. -This is not used by Autorest itself. - -``` yaml $(swagger-to-sdk) -swagger-to-sdk: - - repo: azure-sdk-for-python - - repo: azure-sdk-for-java - - repo: azure-sdk-for-go - - repo: azure-sdk-for-js - - repo: azure-sdk-for-node - - repo: azure-sdk-for-ruby - after_scripts: - - bundle install && rake arm:regen_all_profiles['azure_cognitiveservices_form'] -``` - - -## CSharp Settings -These settings apply only when `--csharp` is specified on the command line. -``` yaml $(csharp) -csharp: - sync-methods: None - license-header: MICROSOFT_MIT_NO_VERSION - azure-arm: false - namespace: Microsoft.Azure.CognitiveServices.Vision.Form - output-folder: $(csharp-sdks-folder)/CognitiveServices/dataPlane/Vision/Form/Form/Generated - clear-output-folder: true -``` - -## Go - -See configuration in [readme.go.md](./readme.go.md) - -## Java - -These settings apply only when `--java` is specified on the command line. -Please also specify `--azure-libraries-for-java-folder=`. - -``` yaml $(java) -java: - azure-arm: true - namespace: com.microsoft.azure.cognitiveservices.vision.formapi - license-header: MICROSOFT_MIT_NO_CODEGEN - payload-flattening-threshold: 1 - output-folder: $(azure-libraries-for-java-folder)/cognitiveservices/data-plane/vision/formapi - with-optional-parameters: true - with-single-async-method: true -``` diff --git a/specification/cognitiveservices/data-plane/Form/readme.nodejs.md b/specification/cognitiveservices/data-plane/Form/readme.nodejs.md deleted file mode 100644 index 0b0af7f29835..000000000000 --- a/specification/cognitiveservices/data-plane/Form/readme.nodejs.md +++ /dev/null @@ -1,14 +0,0 @@ -## Node.js - -These settings apply only when `--nodejs` is specified on the command line. -Please also specify `--node-sdks-folder=`. - -``` yaml $(nodejs) -nodejs: - package-name: azure-cognitiveservices-form - output-folder: $(node-sdks-folder)/lib/services/cognitiveServicesForm - azure-arm: false - generate-license-txt: true - generate-package-json: true - generate-readme-md: true -``` diff --git a/specification/cognitiveservices/data-plane/Form/readme.python.md b/specification/cognitiveservices/data-plane/Form/readme.python.md deleted file mode 100644 index 050ec3a6e9ca..000000000000 --- a/specification/cognitiveservices/data-plane/Form/readme.python.md +++ /dev/null @@ -1,26 +0,0 @@ -## Python - -These settings apply only when `--python` is specified on the command line. -Please also specify `--python-sdks-folder=`. -Use `--python-mode=update` if you already have a setup.py and just want to update the code itself. - -``` yaml $(python) -python-mode: create -python: - license-header: MICROSOFT_MIT_NO_VERSION - add-credentials: true - payload-flattening-threshold: 2 - namespace: azure.cognitiveservices.vision.form - package-name: azure-cognitiveservices-vision-form - clear-output-folder: true -``` -``` yaml $(python) && $(python-mode) == 'update' -python: - no-namespace-folders: true - output-folder: $(python-sdks-folder)/azure-cognitiveservices-vision-form/azure/cognitiveservices/vision/form -``` -``` yaml $(python) && $(python-mode) == 'create' -python: - basic-setup-py: true - output-folder: $(python-sdks-folder)/azure-cognitiveservices-vision-form -``` diff --git a/specification/cognitiveservices/data-plane/Form/readme.ruby.md b/specification/cognitiveservices/data-plane/Form/readme.ruby.md deleted file mode 100644 index 4d17040036c3..000000000000 --- a/specification/cognitiveservices/data-plane/Form/readme.ruby.md +++ /dev/null @@ -1,27 +0,0 @@ -## Ruby - -These settings apply only when `--ruby` is specified on the command line. - -``` yaml -package-name: azure_cognitiveservices_form -package-version: "0.16.0" -azure-arm: true -``` - -### Ruby multi-api - -``` yaml $(ruby) && $(multiapi) -batch: - - tag: release_1_0 -``` - -### Tag: release_1_0 and ruby - -These settings apply only when `--tag=release_1_0 --ruby` is specified on the command line. -Please also specify `--ruby-sdks-folder=`. - -``` yaml $(tag) == 'release_1_0' && $(ruby) -namespace: "Azure::CognitiveServices::Form::V1_0" -output-folder: $(ruby-sdks-folder)/data/azure_cognitiveservices_form/lib -title: "FormClient" -``` diff --git a/specification/cognitiveservices/data-plane/Form/readme.typescript.md b/specification/cognitiveservices/data-plane/Form/readme.typescript.md deleted file mode 100644 index f66280e9cedf..000000000000 --- a/specification/cognitiveservices/data-plane/Form/readme.typescript.md +++ /dev/null @@ -1,12 +0,0 @@ -## TypeScript - -These settings apply only when `--typescript` is specified on the command line. -Please also specify `--typescript-sdks-folder=`. - -``` yaml $(typescript) -typescript: - package-name: "@azure/cognitiveservices-form" - output-folder: "$(typescript-sdks-folder)/sdk/cognitiveservices/cognitiveservices-form" - azure-arm: false - generate-metadata: true -``` diff --git a/specification/cognitiveservices/data-plane/Form/stable/v1.0/Form.json b/specification/cognitiveservices/data-plane/Form/stable/v1.0/Form.json deleted file mode 100644 index 1a1d394d76cd..000000000000 --- a/specification/cognitiveservices/data-plane/Form/stable/v1.0/Form.json +++ /dev/null @@ -1,731 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "v1", - "title": "Cognitive Service Form Recognizer API V1 (Preview)", - "description": "Extracts information from forms and images into structured data based on a model created by a set of representative training forms." - }, - "securityDefinitions": { - "apim_key": { - "type": "apiKey", - "name": "Ocp-Apim-Subscription-Key", - "in": "header" - } - }, - "security": [ - { - "apim_key": [] - } - ], - "x-ms-parameterized-host": { - "hostTemplate": "{Endpoint}/form/v1.0", - "useSchemePrefix": false, - "parameters": [ - { - "$ref": "#/parameters/Endpoint" - } - ] - }, - "paths": { - "/formrecognizer/v1.0/custom/train": { - "post": { - "tags": [ - "Form" - ], - "summary": "Train a model to analyze using a set of documents of supported types.", - "description": "The train request must include a 'Source' parameter that is either a Azure Storage Blob Container SAS Uri or a path to a locally mounted drive. When local paths are specified, they must always follow the Linux/Unix style absolute path convention and be rooted to the {Mounts:Input} configuration setting value.", - "operationId": "FormrecognizerV1.0CustomTrainPost", - "consumes": [ - "application/json-patch+json", - "application/json", - "text/json", - "application/*+json" - ], - "produces": [ - "application/json", - "text/json" - ], - "parameters": [ - { - "name": "trainRequest", - "in": "body", - "description": "Request object for training.", - "required": false, - "schema": { - "$ref": "#/definitions/TrainRequest" - } - } - ], - "responses": { - "200": { - "description": "Success", - "schema": { - "$ref": "#/definitions/TrainResponse" - }, - "examples": { - "application/json": { - "modelId": "e390d2c0-0d6a-4a65-8277-597c0e863997", - "trainingDocuments": [ - { - "pages": 1, - "errors": [], - "status": "success" - } - ], - "errors": [ - { - "errorMessage": "Could not use 0.pdf for training." - } - ] - } - } - }, - "default": { - "description": "Response entity accompanying non-successful responses containing additional details about the error.", - "schema": { - "$ref": "#/definitions/ErrorResponse" - }, - "examples": { - "application/json": { - "error": { - "code": "BadArgument", - "innerError": { - "requestId": "00000000-0000-0000-0000-000000000000" - }, - "message": "Request body is invalid." - } - } - } - } - } - } - }, - "/formrecognizer/v1.0/custom/model/{id}/keys": { - "get": { - "tags": [ - "Form" - ], - "summary": "Get keys of a model.", - "description": "Use the API to retrieve the keys that were\r\n extracted by the specified model.", - "operationId": "FormrecognizerV1.0CustomModelByIdKeysGet", - "consumes": [], - "produces": [], - "parameters": [ - { - "name": "id", - "in": "path", - "description": "Model identifier.", - "required": true, - "type": "string" - } - ], - "responses": { - "200": { - "description": "Success", - "examples": { - "application/json": { - "clusters": { - "0": [ - "Invoice", - "123112313" - ], - "1": [ - "Please remit payment to:", - "Microsoft" - ] - } - } - } - }, - "default": { - "description": "Response entity accompanying non-successful responses containing additional details about the error.", - "schema": { - "$ref": "#/definitions/ErrorResponse" - }, - "examples": { - "application/json": { - "error": { - "code": "BadArgument", - "innerError": { - "requestId": "00000000-0000-0000-0000-000000000000" - }, - "message": "Request body is invalid." - } - } - } - } - } - } - }, - "/formrecognizer/v1.0/custom/model/{id}": { - "get": { - "tags": [ - "Form" - ], - "summary": "Get information about a model.", - "operationId": "FormrecognizerV1.0CustomModelByIdGet", - "consumes": [], - "produces": [], - "parameters": [ - { - "name": "id", - "in": "path", - "description": "Model identifier.", - "required": true, - "type": "string" - } - ], - "responses": { - "200": { - "description": "Success", - "examples": { - "application/json": { - "modelId": "708846bd-1fb2-49e1-a12f-9306e97bd473", - "version": "1", - "status": "ready", - "createdDateTime": "2019-04-17T16:04:35.4859654Z", - "lastUpdatedDateTime": "0001-01-01T00:00:00" - } - } - }, - "default": { - "description": "Response entity accompanying non-successful responses containing additional details about the error.", - "schema": { - "$ref": "#/definitions/ErrorResponse" - }, - "examples": { - "application/json": { - "error": { - "code": "BadArgument", - "innerError": { - "requestId": "00000000-0000-0000-0000-000000000000" - }, - "message": "Request body is invalid." - } - } - } - } - } - }, - "delete": { - "tags": [ - "Form" - ], - "summary": "Delete a model and all associated pre-processing data.", - "operationId": "FormrecognizerV1.0CustomModelByIdDelete", - "consumes": [], - "produces": [], - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The identifier of the model to delete.", - "required": true, - "type": "string" - } - ], - "responses": { - "204": { - "description": "Success" - }, - "default": { - "description": "Response entity accompanying non-successful responses containing additional details about the error.", - "schema": { - "$ref": "#/definitions/ErrorResponse" - }, - "examples": { - "application/json": { - "error": { - "code": "BadArgument", - "innerError": { - "requestId": "00000000-0000-0000-0000-000000000000" - }, - "message": "Request body is invalid." - } - } - } - } - } - } - }, - "/formrecognizer/v1.0/custom/model/{id}/analyze": { - "post": { - "tags": [ - "Form" - ], - "summary": "Analyze a document to extract key-value pairs and table\r\ninformation.", - "description": "The document to analyze must be must be of expected\r\n media type - currently supported types are application/pdf, image/jpg or image/png.", - "operationId": "FormrecognizerV1.0CustomModelByIdAnalyzePost", - "consumes": [ - "multipart/form-data" - ], - "produces": [ - "application/json", - "text/json" - ], - "parameters": [ - { - "name": "id", - "in": "path", - "description": "Identifier of the model to analyze the document with.", - "required": true, - "type": "string" - }, - { - "name": "keys", - "in": "query", - "description": "An optional list of known keys to extract the values for.", - "required": false, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "multi", - "uniqueItems": false - }, - { - "name": "form", - "in": "formData", - "description": "Upload image or pdf content for processing.", - "required": false, - "type": "file" - } - ], - "responses": { - "200": { - "description": "Success", - "schema": { - "$ref": "#/definitions/AnalyzeResponse" - }, - "examples": { - "application/json": { - "status": "success", - "pages": [ - { - "number": 1, - "height": 800, - "width": 600, - "clusterId": 0, - "keyValuePairs": [ - { - "key": [ - { - "text": "Address:", - "boundingBox": [ - 57.4, - 683.1, - 100.5, - 683.1, - 100.5, - 673.7, - 57.4, - 673.7 - ] - } - ], - "value": [ - { - "text": "1 Microsoft Way", - "boundingBox": [ - 57.4, - 672.2, - 126.6, - 672.2, - 126.6, - 658.9, - 57.4, - 658.9 - ], - "confidence": 0.9 - } - ] - } - ], - "tables": [ - { - "id": "table_0", - "columns": [ - { - "header": [ - { - "text": "InvoiceNumber", - "boundingBox": [ - 38.5, - 585.2, - 113.4, - 585.2, - 113.4, - 575.8, - 38.5, - 575.8 - ] - } - ], - "entries": [ - [ - { - "text": "38772349", - "boundingBox": [ - 305.6, - 692.1, - 403.5, - 692.1, - 403.5, - 684.2, - 305.6, - 684.2 - ], - "confidence": 0.9 - } - ] - ] - } - ] - } - ] - } - ], - "errors": [ - { - "errorMessage": "Page1: Field not extracted" - } - ] - } - } - }, - "default": { - "description": "Response entity accompanying non-successful responses containing additional details about the error.", - "schema": { - "$ref": "#/definitions/ErrorResponse" - }, - "examples": { - "application/json": { - "error": { - "code": "BadArgument", - "innerError": { - "requestId": "00000000-0000-0000-0000-000000000000" - }, - "message": "Request body is invalid." - } - } - } - } - } - } - }, - "/status": { - "get": { - "tags": [ - "Status" - ], - "operationId": "StatusGet", - "consumes": [], - "produces": [ - "application/json", - "text/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "Success", - "schema": { - "$ref": "#/definitions/ContainerStatus" - } - } - } - } - } - }, - "definitions": { - "TrainRequest": { - "description": "Contract to initiate a train request.", - "required": [ - "source" - ], - "type": "object", - "properties": { - "source": { - "description": "Get or set source path.", - "maxLength": 2048, - "minLength": 0, - "type": "string" - } - } - }, - "TrainResponse": { - "description": "Response of the Train API call.", - "type": "object", - "properties": { - "modelId": { - "description": "Identifier of the model.", - "type": "string" - }, - "trainingDocuments": { - "description": "List of documents used to train the model and the\r\ntrain operation error reported by each.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/FormDocumentReport" - } - }, - "errors": { - "description": "Errors returned during the training operation.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/FormOperationError" - } - } - } - }, - "FormDocumentReport": { - "type": "object", - "properties": { - "documentName": { - "description": "Reference to the data that the report is for.", - "type": "string" - }, - "pages": { - "format": "int32", - "description": "Total number of pages trained on.", - "type": "integer" - }, - "errors": { - "description": "List of errors per page.", - "uniqueItems": false, - "type": "array", - "items": { - "type": "string" - } - }, - "status": { - "description": "Status of the training operation.", - "enum": [ - "success", - "partialSuccess", - "failure" - ], - "type": "string" - } - } - }, - "FormOperationError": { - "description": "Error reported during an operation.", - "type": "object", - "properties": { - "errorMessage": { - "description": "Message reported during the train operation.", - "type": "string" - } - } - }, - "ErrorResponse": { - "type": "object", - "properties": { - "error": { - "$ref": "#/definitions/ErrorInformation" - } - } - }, - "ErrorInformation": { - "type": "object", - "properties": { - "code": { - "type": "string" - }, - "innerError": { - "$ref": "#/definitions/InnerError" - }, - "message": { - "type": "string" - } - } - }, - "InnerError": { - "type": "object", - "properties": { - "requestId": { - "type": "string" - } - } - }, - "AnalyzeResponse": { - "description": "Analyze API response.", - "type": "object", - "properties": { - "status": { - "description": "Status of the analyze operation.", - "enum": [ - "success", - "partialSuccess", - "failure" - ], - "type": "string" - }, - "pages": { - "description": "Page level information extracted in the analyzed\r\ndocument.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/Page" - } - }, - "errors": { - "description": "List of errors reported during the analyze\r\noperation.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/FormOperationError" - } - } - } - }, - "Page": { - "description": "Extraction information of a single page in a\r\nwith a document.", - "type": "object", - "properties": { - "number": { - "format": "int32", - "description": "Page number.", - "type": "integer" - }, - "height": { - "format": "int32", - "description": "Height of the page (in pixels).", - "type": "integer" - }, - "width": { - "format": "int32", - "description": "Width of the page (in pixels).", - "type": "integer" - }, - "clusterId": { - "format": "int32", - "description": "Cluster identifier.", - "type": "integer" - }, - "keyValuePairs": { - "description": "List of Key-Value pairs extracted from the page.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/KeyValuePair" - } - }, - "tables": { - "description": "List of Tables and their information extracted from the page.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/Table" - } - } - } - }, - "KeyValuePair": { - "description": "Representation of a key-value pair as a list\r\nof key and value tokens.", - "type": "object", - "properties": { - "key": { - "description": "List of tokens for the extracted key in a key-value pair.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/Token" - } - }, - "value": { - "description": "List of tokens for the extracted value in a key-value pair.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/Token" - } - } - } - }, - "Table": { - "description": "Extraction information about a table\r\ncontained in a page.", - "type": "object", - "properties": { - "id": { - "description": "Table identifier.", - "type": "string" - }, - "columns": { - "description": "List of columns contained in the table.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/TableColumn" - } - } - } - }, - "Token": { - "description": "Canonical representation of single extracted text.", - "type": "object", - "properties": { - "text": { - "description": "String value of the extracted text.", - "type": "string" - }, - "boundingBox": { - "description": "Bounding box of the extracted text. Represents the\r\nlocation of the extracted text as a pair of\r\ncartesian co-ordinates. The co-ordinate pairs are arranged by\r\ntop-left, top-right, bottom-right and bottom-left endpoints box\r\nwith origin reference from the bottom-left of the page.", - "uniqueItems": false, - "type": "array", - "items": { - "format": "double", - "type": "number" - } - }, - "confidence": { - "format": "double", - "description": "A measure of accuracy of the extracted text.", - "type": "number" - } - } - }, - "TableColumn": { - "description": "Extraction information of a column in\r\na table.", - "type": "object", - "properties": { - "header": { - "description": "List of extracted tokens for the column header.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/Token" - } - }, - "entries": { - "description": "Extracted text for each cell of a column. Each cell\r\nin the column can have a list of one or more tokens.", - "uniqueItems": false, - "type": "array", - "items": { - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/Token" - } - } - } - } - }, - "ContainerStatus": { - "type": "object", - "properties": { - "service": { - "type": "string" - }, - "apiStatus": { - "type": "string" - }, - "apiStatusMessage": { - "type": "string" - } - } - } - }, - "tags": [] -} \ No newline at end of file diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md index aab5be30eaf9..791e8d93b122 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md +++ b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md @@ -31,7 +31,6 @@ swagger-to-sdk: - repo: azure-sdk-for-python - repo: azure-sdk-for-java - repo: azure-sdk-for-go - - repo: azure-sdk-for-js - repo: azure-sdk-for-node - repo: azure-sdk-for-ruby after_scripts: diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json index 9ed79c6b76f0..613a782bf058 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json @@ -95,6 +95,11 @@ } } } + "x-ms-examples": { + "Train new model example": { + "$ref": "./examples/Train.json" + } + } } }, "/model/{id}/keys": { @@ -149,6 +154,11 @@ } } } + "x-ms-examples": { + "Get Keys from Model": { + "$ref": "./examples/GetKeys.json" + } + } } }, "/model/{id}": { @@ -197,7 +207,13 @@ } } } + "x-ms-examples": { + "Get Model from id": { + "$ref": "./examples/GetModelById.json" + } + } }, + "/model/{id}": { "delete": { "summary": "Delete a model and all associated pre-processing data.", "operationId": "Formrecognizer_DeleteModelById", @@ -234,6 +250,11 @@ } } } + "x-ms-examples": { + "Get Model from id": { + "$ref": "./examples/DeleteModelById.json" + } + } } }, "/model/{id}/analyze": { @@ -396,6 +417,11 @@ } } } + "x-ms-examples": { + "Get Model from id": { + "$ref": "./examples/Analyze.json" + } + } } }, "/status": { diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Analyze.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Analyze.json new file mode 100644 index 000000000000..97bddc53899b --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Analyze.json @@ -0,0 +1,110 @@ +{ + "parameters": { + "Endpoint": "{Endpoint}", + "Content-Type": "application/json", + "Ocp-Apim-Subscription-Key": "{API key}", + "id": "{Model Id}", + "body": { + "formData": {Image or Pdf file stream} + } + }, + "responses": { + "200": { + "body": [ + { + "status": "success", + "pages": [ + { + "number": 1, + "height": 800, + "width": 600, + "clusterId": 0, + "keyValuePairs": [ + { + "key": [ + { + "text": "Address:", + "boundingBox": [ + 57.4, + 683.1, + 100.5, + 683.1, + 100.5, + 673.7, + 57.4, + 673.7 + ] + } + ], + "value": [ + { + "text": "1 Microsoft Way", + "boundingBox": [ + 57.4, + 672.2, + 126.6, + 672.2, + 126.6, + 658.9, + 57.4, + 658.9 + ], + "confidence": 0.9 + } + ] + } + ], + "tables": [ + { + "id": "table_0", + "columns": [ + { + "header": [ + { + "text": "InvoiceNumber", + "boundingBox": [ + 38.5, + 585.2, + 113.4, + 585.2, + 113.4, + 575.8, + 38.5, + 575.8 + ] + } + ], + "entries": [ + [ + { + "text": "38772349", + "boundingBox": [ + 305.6, + 692.1, + 403.5, + 692.1, + 403.5, + 684.2, + 305.6, + 684.2 + ], + "confidence": 0.9 + } + ] + ] + } + ] + } + ] + } + ], + "errors": [ + { + "errorMessage": "Page1: Field not extracted" + } + ] + } + ] + } + } +} diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/DeleteModelById.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/DeleteModelById.json new file mode 100644 index 000000000000..ee5e16d02416 --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/DeleteModelById.json @@ -0,0 +1,16 @@ +{ + "parameters": { + "Endpoint": "{Endpoint}", + "Content-Type": "application/json", + "Ocp-Apim-Subscription-Key": "{API key}", + "id": "{Model Id}", + "body": { + } + }, + "responses": { + "204": { + "body": [ + ] + } + } +} diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetKeys.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetKeys.json new file mode 100644 index 000000000000..029a9005baec --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetKeys.json @@ -0,0 +1,28 @@ +{ + "parameters": { + "Endpoint": "{Endpoint}", + "Content-Type": "application/json", + "Ocp-Apim-Subscription-Key": "{API key}", + "id": "{Model Id}", + "body": { + } + }, + "responses": { + "200": { + "body": [ + { + "clusters": { + "0": [ + "Invoice", + "123112313" + ], + "1": [ + "Please remit payment to:", + "Microsoft" + ] + } + } + ] + } + } +} diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetModelById.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetModelById.json new file mode 100644 index 000000000000..cbaca67ea3ed --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetModelById.json @@ -0,0 +1,24 @@ +{ + "parameters": { + "Endpoint": "{Endpoint}", + "Content-Type": "application/json", + "Ocp-Apim-Subscription-Key": "{API key}", + "id": "{Model Id}", + "body": { + } + }, + "responses": { + "200": { + "body": [ + { + "modelId": "cd7452ff-1988-4048-9e14-89bf6f4c15de", + "version": "1", + "status": "ready", + "createdDateTime": "2019-04-18T12:47:15.3291661Z", + "lastUpdatedDateTime": "0001-01-01T00:00:00" + } + } + ] + } + } +} diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetStatus.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetStatus.json new file mode 100644 index 000000000000..9cc775dc860f --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetStatus.json @@ -0,0 +1,21 @@ +{ + "parameters": { + "Endpoint": "{Endpoint}", + "Content-Type": "application/json", + "Ocp-Apim-Subscription-Key": "{API key}", + "body": { + } + }, + "responses": { + "200": { + "body": [ + { + "service": "forms", + "apiStatus": "Valid", + "apiStatusMessage": "Api Key is valid." + } + } + ] + } + } +} diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Train.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Train.json new file mode 100644 index 000000000000..c08bf03a89f1 --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Train.json @@ -0,0 +1,31 @@ +{ + "parameters": { + "Endpoint": "{Endpoint}", + "Content-Type": "application/json", + "Ocp-Apim-Subscription-Key": "{API key}", + "body": { + "source": "/input/data", + } + }, + "responses": { + "200": { + "body": [ + { + "modelId": "640b1c8a-0a44-4611-94a6-f7d0130783cc", + "trainingDocuments": [ + { + "pages": 1, + "errors": [], + "status": "success" + } + ], + "errors": [ + { + "errorMessage": "Could not use 0.pdf for training." + } + ] + } + ] + } + } +} From 90946c630549903213518bbf4c475ce5185cc7e4 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Thu, 18 Apr 2019 09:21:44 -0700 Subject: [PATCH 04/33] Fixing json syntax errors. --- .../stable/v1.0/FormRecognizer.json | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json index 613a782bf058..99c810803756 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json @@ -94,12 +94,12 @@ } } } - } + }, "x-ms-examples": { "Train new model example": { "$ref": "./examples/Train.json" } - } + }, } }, "/model/{id}/keys": { @@ -153,7 +153,7 @@ } } } - } + }, "x-ms-examples": { "Get Keys from Model": { "$ref": "./examples/GetKeys.json" @@ -206,13 +206,14 @@ } } } - } + }, "x-ms-examples": { "Get Model from id": { "$ref": "./examples/GetModelById.json" } } - }, + } + }, "/model/{id}": { "delete": { "summary": "Delete a model and all associated pre-processing data.", @@ -249,7 +250,7 @@ } } } - } + }, "x-ms-examples": { "Get Model from id": { "$ref": "./examples/DeleteModelById.json" @@ -416,7 +417,7 @@ } } } - } + }, "x-ms-examples": { "Get Model from id": { "$ref": "./examples/Analyze.json" From 58126744f40c9adbc76b78f67909063fcc5278fa Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Thu, 18 Apr 2019 10:45:23 -0700 Subject: [PATCH 05/33] Incorporating feedback. --- .../stable/v1.0/FormRecognizer.json | 45 +++++-------------- .../stable/v1.0/examples/Analyze.json | 2 +- .../stable/v1.0/examples/GetModelById.json | 5 +-- .../stable/v1.0/examples/GetStatus.json | 21 --------- 4 files changed, 15 insertions(+), 58 deletions(-) delete mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetStatus.json diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json index 99c810803756..efa643e5e024 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json @@ -18,7 +18,7 @@ } ], "x-ms-parameterized-host": { - "hostTemplate": "{Endpoint}/FormRecognizer/v1.0", + "hostTemplate": "{Endpoint}/FormRecognizer/v1.0/custom", "useSchemePrefix": false, "parameters": [ { @@ -30,8 +30,8 @@ "/train": { "post": { "summary": "Train a model to analyze using a set of documents of supported types.", - "description": "The train request must include a 'Source' parameter that is\r\n either a Azure Storage Blob Container SAS Uri or a path to a locally mounted\r\n drive. When local paths are specified, they must always follow the Linux/Unix style\r\n absolute path convention and be rooted to the {Mounts:Input}\r\n configuration setting value.", - "operationId": "Formrecognizer_Train", + "description": "The train request must include a 'Source' parameter that is either a Azure Storage Blob Container SAS Uri or a path to a locally mounted drive. When local paths are specified, they must always follow the Linux/Unix style absolute path convention and be rooted to the {Mounts:Input} configuration setting value.", + "operationId": "FormRecognizer_CustomTrain", "consumes": [ "application/json-patch+json", "application/json", @@ -105,8 +105,8 @@ "/model/{id}/keys": { "get": { "summary": "Get keys of a model.", - "description": "Use the API to retrieve the keys that were\r\n extracted by the specified model.", - "operationId": "Formrecognizer_GetKeysByModelId", + "description": "Use the API to retrieve the keys that were extracted by the specified model.", + "operationId": "FormRecognizer_CustomGetKeysByModelId", "consumes": [], "produces": [], "parameters": [ @@ -161,10 +161,10 @@ } } }, - "/model/{id}": { + "/model/{id}/": { "get": { "summary": "Get information about a model.", - "operationId": "Formrecognizer_GetModelById", + "operationId": "FormRecognizer_CustomGetModelById", "consumes": [], "produces": [], "parameters": [ @@ -212,12 +212,10 @@ "$ref": "./examples/GetModelById.json" } } - } - }, - "/model/{id}": { + }, "delete": { "summary": "Delete a model and all associated pre-processing data.", - "operationId": "Formrecognizer_DeleteModelById", + "operationId": "FormRecognizer_CustomDeleteModelById", "consumes": [], "produces": [], "parameters": [ @@ -260,9 +258,9 @@ }, "/model/{id}/analyze": { "post": { - "summary": "Analyze a document to extract key-value pairs and table\r\ninformation.", - "description": "The document to analyze must be must be of expected\r\n media type - currently supported types are application/pdf, image/jpg or image/png.", - "operationId": "Formrecognizer_Analyze", + "summary": "Analyze a document to extract key-value pairs and table information.", + "description": "The document to analyze must be must be of expected media type - currently supported types are application/pdf, image/jpg or image/png.", + "operationId": "FormRecognizer_CustomAnalyze", "consumes": [ "multipart/form-data" ], @@ -424,25 +422,6 @@ } } } - }, - "/status": { - "get": { - "operationId": "StatusGet", - "consumes": [], - "produces": [ - "application/json", - "text/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "Success", - "schema": { - "$ref": "#/definitions/ContainerStatus" - } - } - } - } } }, "definitions": { diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Analyze.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Analyze.json index 97bddc53899b..60a280675e01 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Analyze.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Analyze.json @@ -5,7 +5,7 @@ "Ocp-Apim-Subscription-Key": "{API key}", "id": "{Model Id}", "body": { - "formData": {Image or Pdf file stream} + "formData": "{Image or Pdf file stream}" } }, "responses": { diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetModelById.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetModelById.json index cbaca67ea3ed..6c5fc0f32adf 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetModelById.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetModelById.json @@ -17,8 +17,7 @@ "createdDateTime": "2019-04-18T12:47:15.3291661Z", "lastUpdatedDateTime": "0001-01-01T00:00:00" } - } - ] + ] } } -} +} \ No newline at end of file diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetStatus.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetStatus.json deleted file mode 100644 index 9cc775dc860f..000000000000 --- a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetStatus.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "parameters": { - "Endpoint": "{Endpoint}", - "Content-Type": "application/json", - "Ocp-Apim-Subscription-Key": "{API key}", - "body": { - } - }, - "responses": { - "200": { - "body": [ - { - "service": "forms", - "apiStatus": "Valid", - "apiStatusMessage": "Api Key is valid." - } - } - ] - } - } -} From 843f2f70686370f65db416b6f14ea698bed7372e Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Thu, 18 Apr 2019 14:30:38 -0700 Subject: [PATCH 06/33] Refactor swagger to common type. --- .../FormRecognizer/stable/v1.0/FormRecognizer.json | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json index efa643e5e024..594cedaabec5 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json @@ -22,7 +22,7 @@ "useSchemePrefix": false, "parameters": [ { - "$ref": "#/parameters/Endpoint" + "$ref": "../../../Common/Parameters.json#/parameters/GlobalEndpoint" } ] }, @@ -714,16 +714,5 @@ } } } - }, - "parameters": { - "Endpoint": { - "name": "Endpoint", - "description": "Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).", - "x-ms-parameter-location": "client", - "required": true, - "type": "string", - "in": "path", - "x-ms-skip-url-encoding": true - } } } \ No newline at end of file From 2c78f40d0b95788d6429ab3babdb00f3ebf3acea Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Thu, 18 Apr 2019 22:37:07 -0700 Subject: [PATCH 07/33] Incorporating feedback. --- .../data-plane/FormRecognizer/readme.md | 2 +- .../stable/v1.0/FormRecognizer.json | 43 ++++++++----------- 2 files changed, 19 insertions(+), 26 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md index 791e8d93b122..c5653c84ad64 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md +++ b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md @@ -45,7 +45,7 @@ csharp: sync-methods: None license-header: MICROSOFT_MIT_NO_VERSION azure-arm: false - namespace: Microsoft.Azure.CognitiveServices.Vision.formrecognizer + namespace: Microsoft.Azure.CognitiveServices.Vision.FormRecognizer output-folder: $(csharp-sdks-folder)/CognitiveServices/dataPlane/Vision/FormRecognizer/Generated clear-output-folder: true ``` diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json index 594cedaabec5..b6c010629932 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json @@ -1,35 +1,26 @@ { "swagger": "2.0", "info": { - "version": "v1", - "title": "Cognitive Service Form Recognizer API V1 (Preview)", - "description": "Extracts information from forms and images into structured data based on a model created by a set of representative training forms." + "version": "v1", + "title": "Cognitive Service Form Recognizer API V1 (Preview)", + "description": "Extracts information from forms and images into structured data based on a model created by a set of representative training forms." }, "securityDefinitions": { - "apim_key": { - "type": "apiKey", - "name": "Ocp-Apim-Subscription-Key", - "in": "header" - } + "apim_key": { + "type": "apiKey", + "name": "Ocp-Apim-Subscription-Key", + "in": "header" + } }, "security": [ - { - "apim_key": [] - } + { + "apim_key": [] + } ], - "x-ms-parameterized-host": { - "hostTemplate": "{Endpoint}/FormRecognizer/v1.0/custom", - "useSchemePrefix": false, - "parameters": [ - { - "$ref": "../../../Common/Parameters.json#/parameters/GlobalEndpoint" - } - ] - }, "paths": { "/train": { "post": { - "summary": "Train a model to analyze using a set of documents of supported types.", + "summary": "Train Model", "description": "The train request must include a 'Source' parameter that is either a Azure Storage Blob Container SAS Uri or a path to a locally mounted drive. When local paths are specified, they must always follow the Linux/Unix style absolute path convention and be rooted to the {Mounts:Input} configuration setting value.", "operationId": "FormRecognizer_CustomTrain", "consumes": [ @@ -104,7 +95,7 @@ }, "/model/{id}/keys": { "get": { - "summary": "Get keys of a model.", + "summary": "Get Keys", "description": "Use the API to retrieve the keys that were extracted by the specified model.", "operationId": "FormRecognizer_CustomGetKeysByModelId", "consumes": [], @@ -163,7 +154,8 @@ }, "/model/{id}/": { "get": { - "summary": "Get information about a model.", + "summary": "Get Model", + "description": "Get information about a model.", "operationId": "FormRecognizer_CustomGetModelById", "consumes": [], "produces": [], @@ -214,7 +206,8 @@ } }, "delete": { - "summary": "Delete a model and all associated pre-processing data.", + "summary": "Delete Model", + "description": "Delete a model and all associated pre-processing data.", "operationId": "FormRecognizer_CustomDeleteModelById", "consumes": [], "produces": [], @@ -258,7 +251,7 @@ }, "/model/{id}/analyze": { "post": { - "summary": "Analyze a document to extract key-value pairs and table information.", + "summary": "Analyze document", "description": "The document to analyze must be must be of expected media type - currently supported types are application/pdf, image/jpg or image/png.", "operationId": "FormRecognizer_CustomAnalyze", "consumes": [ From 3840caed2937cf75689876008cf6761953013e24 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Fri, 19 Apr 2019 11:41:15 -0700 Subject: [PATCH 08/33] Moved to preview, refactor, fixes. --- .../v1.0/FormRecognizer.json | 231 ++---------------- .../v1.0/examples/Analyze.json | 0 .../v1.0/examples/DeleteModelById.json | 0 .../v1.0/examples/GetKeys.json | 0 .../v1.0/examples/GetModelById.json | 0 .../v1.0/examples/Train.json | 0 .../data-plane/FormRecognizer/readme.md | 2 +- 7 files changed, 26 insertions(+), 207 deletions(-) rename specification/cognitiveservices/data-plane/FormRecognizer/{stable => preview}/v1.0/FormRecognizer.json (63%) rename specification/cognitiveservices/data-plane/FormRecognizer/{stable => preview}/v1.0/examples/Analyze.json (100%) rename specification/cognitiveservices/data-plane/FormRecognizer/{stable => preview}/v1.0/examples/DeleteModelById.json (100%) rename specification/cognitiveservices/data-plane/FormRecognizer/{stable => preview}/v1.0/examples/GetKeys.json (100%) rename specification/cognitiveservices/data-plane/FormRecognizer/{stable => preview}/v1.0/examples/GetModelById.json (100%) rename specification/cognitiveservices/data-plane/FormRecognizer/{stable => preview}/v1.0/examples/Train.json (100%) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json similarity index 63% rename from specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json rename to specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index b6c010629932..9663356dbbbd 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -1,7 +1,7 @@ { "swagger": "2.0", "info": { - "version": "v1", + "version": "v1.0-preview", "title": "Cognitive Service Form Recognizer API V1 (Preview)", "description": "Extracts information from forms and images into structured data based on a model created by a set of representative training forms." }, @@ -38,7 +38,7 @@ "name": "trainRequest", "in": "body", "description": "Request object for training.", - "required": false, + "required": true, "schema": { "$ref": "#/definitions/TrainRequest" } @@ -49,40 +49,12 @@ "description": "Success", "schema": { "$ref": "#/definitions/TrainResponse" - }, - "examples": { - "application/json": { - "modelId": "e390d2c0-0d6a-4a65-8277-597c0e863997", - "trainingDocuments": [ - { - "pages": 1, - "errors": [], - "status": "success" - } - ], - "errors": [ - { - "errorMessage": "Could not use 0.pdf for training." - } - ] - } } }, "default": { "description": "Response entity accompanying non-successful responses containing additional details about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" - }, - "examples": { - "application/json": { - "error": { - "code": "BadArgument", - "innerError": { - "requestId": "00000000-0000-0000-0000-000000000000" - }, - "message": "Request body is invalid." - } - } } } }, @@ -99,7 +71,10 @@ "description": "Use the API to retrieve the keys that were extracted by the specified model.", "operationId": "FormRecognizer_CustomGetKeysByModelId", "consumes": [], - "produces": [], + "produces": [ + "application/json", + "text/json" + ], "parameters": [ { "name": "id", @@ -111,37 +86,12 @@ ], "responses": { "200": { - "description": "Success", - "examples": { - "application/json": { - "clusters": { - "0": [ - "Invoice", - "123112313" - ], - "1": [ - "Please remit payment to:", - "Microsoft" - ] - } - } - } + "description": "Success" }, "default": { "description": "Response entity accompanying non-successful responses containing additional details about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" - }, - "examples": { - "application/json": { - "error": { - "code": "BadArgument", - "innerError": { - "requestId": "00000000-0000-0000-0000-000000000000" - }, - "message": "Request body is invalid." - } - } } } }, @@ -155,10 +105,13 @@ "/model/{id}/": { "get": { "summary": "Get Model", - "description": "Get information about a model.", + "description": "Get information about a model.", "operationId": "FormRecognizer_CustomGetModelById", "consumes": [], - "produces": [], + "produces": [ + "application/json", + "text/json" + ], "parameters": [ { "name": "id", @@ -170,32 +123,12 @@ ], "responses": { "200": { - "description": "Success", - "examples": { - "application/json": { - "modelId": "708846bd-1fb2-49e1-a12f-9306e97bd473", - "version": "1", - "status": "ready", - "createdDateTime": "2019-04-17T16:04:35.4859654Z", - "lastUpdatedDateTime": "0001-01-01T00:00:00" - } - } + "description": "Success" }, "default": { "description": "Response entity accompanying non-successful responses containing additional details about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" - }, - "examples": { - "application/json": { - "error": { - "code": "BadArgument", - "innerError": { - "requestId": "00000000-0000-0000-0000-000000000000" - }, - "message": "Request body is invalid." - } - } } } }, @@ -207,10 +140,13 @@ }, "delete": { "summary": "Delete Model", - "description": "Delete a model and all associated pre-processing data.", + "description": "Delete model artifacts.", "operationId": "FormRecognizer_CustomDeleteModelById", "consumes": [], - "produces": [], + "produces": [ + "application/json", + "text/json" + ], "parameters": [ { "name": "id", @@ -222,23 +158,12 @@ ], "responses": { "204": { - "description": "Success" + "description": "Successfully removed model artifacts." }, "default": { "description": "Response entity accompanying non-successful responses containing additional details about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" - }, - "examples": { - "application/json": { - "error": { - "code": "BadArgument", - "innerError": { - "requestId": "00000000-0000-0000-0000-000000000000" - }, - "message": "Request body is invalid." - } - } } } }, @@ -251,7 +176,7 @@ }, "/model/{id}/analyze": { "post": { - "summary": "Analyze document", + "summary": "Analyze Form", "description": "The document to analyze must be must be of expected media type - currently supported types are application/pdf, image/jpg or image/png.", "operationId": "FormRecognizer_CustomAnalyze", "consumes": [ @@ -284,7 +209,7 @@ { "name": "form", "in": "formData", - "description": "Upload image or pdf content for processing.", + "description": "Upload content of type 'application/pdf', 'image/jpeg' or 'image/png' for processing.", "required": false, "type": "file" } @@ -294,118 +219,12 @@ "description": "Success", "schema": { "$ref": "#/definitions/AnalyzeResponse" - }, - "examples": { - "application/json": { - "status": "success", - "pages": [ - { - "number": 1, - "height": 800, - "width": 600, - "clusterId": 0, - "keyValuePairs": [ - { - "key": [ - { - "text": "Address:", - "boundingBox": [ - 57.4, - 683.1, - 100.5, - 683.1, - 100.5, - 673.7, - 57.4, - 673.7 - ] - } - ], - "value": [ - { - "text": "1 Microsoft Way", - "boundingBox": [ - 57.4, - 672.2, - 126.6, - 672.2, - 126.6, - 658.9, - 57.4, - 658.9 - ], - "confidence": 0.9 - } - ] - } - ], - "tables": [ - { - "id": "table_0", - "columns": [ - { - "header": [ - { - "text": "InvoiceNumber", - "boundingBox": [ - 38.5, - 585.2, - 113.4, - 585.2, - 113.4, - 575.8, - 38.5, - 575.8 - ] - } - ], - "entries": [ - [ - { - "text": "38772349", - "boundingBox": [ - 305.6, - 692.1, - 403.5, - 692.1, - 403.5, - 684.2, - 305.6, - 684.2 - ], - "confidence": 0.9 - } - ] - ] - } - ] - } - ] - } - ], - "errors": [ - { - "errorMessage": "Page1: Field not extracted" - } - ] - } } }, "default": { "description": "Response entity accompanying non-successful responses containing additional details about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" - }, - "examples": { - "application/json": { - "error": { - "code": "BadArgument", - "innerError": { - "requestId": "00000000-0000-0000-0000-000000000000" - }, - "message": "Request body is invalid." - } - } } } }, @@ -629,10 +448,10 @@ "description": "Extraction information about a table\r\ncontained in a page.", "type": "object", "properties": { - "id": { - "description": "Table identifier.", - "type": "string" - }, + "id": { + "description": "Table identifier.", + "type": "string" + }, "columns": { "description": "List of columns contained in the table.", "uniqueItems": false, diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Analyze.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Analyze.json similarity index 100% rename from specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Analyze.json rename to specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Analyze.json diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/DeleteModelById.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/DeleteModelById.json similarity index 100% rename from specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/DeleteModelById.json rename to specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/DeleteModelById.json diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetKeys.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetKeys.json similarity index 100% rename from specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetKeys.json rename to specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetKeys.json diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetModelById.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModelById.json similarity index 100% rename from specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/GetModelById.json rename to specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModelById.json diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Train.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json similarity index 100% rename from specification/cognitiveservices/data-plane/FormRecognizer/stable/v1.0/examples/Train.json rename to specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md index c5653c84ad64..9d6087b1a09f 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md +++ b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md @@ -18,7 +18,7 @@ openapi-type: data-plane These settings apply only when `--tag=release_1_0` is specified on the command line. ``` yaml $(tag) == 'release_1_0' -input-file: stable/v1.0/formrecognizer.json +input-file: preview/v1.0/formrecognizer.json ``` ## Swagger to SDK From 29ea35bd9beb9d708658d25ddb2616af643f0b67 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Fri, 19 Apr 2019 11:54:12 -0700 Subject: [PATCH 09/33] Updated text. --- .../FormRecognizer/preview/v1.0/FormRecognizer.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 9663356dbbbd..8d4af6e5c91c 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -21,7 +21,7 @@ "/train": { "post": { "summary": "Train Model", - "description": "The train request must include a 'Source' parameter that is either a Azure Storage Blob Container SAS Uri or a path to a locally mounted drive. When local paths are specified, they must always follow the Linux/Unix style absolute path convention and be rooted to the {Mounts:Input} configuration setting value.", + "description": "The train request must include a 'Source' parameter that is\r\n an Azure Storage blob container Uri that is that is accessible externally\r\n (preferably a Shared Access Signature Uri) or valid path to data in a locally mounted drive.\r\n When local paths are specified, they must follow the Linux/Unix path format and\r\n absolute path convention rooted to the input mount configuration setting value.\r\n Models are trained using documents that are of the following\r\n content type - 'application/pdf', 'image/jpeg' and 'image/png'.", "operationId": "FormRecognizer_CustomTrain", "consumes": [ "application/json-patch+json", @@ -68,7 +68,7 @@ "/model/{id}/keys": { "get": { "summary": "Get Keys", - "description": "Use the API to retrieve the keys that were extracted by the specified model.", + "description": "Use the API to retrieve the keys that were\r\n extracted by the specified model.", "operationId": "FormRecognizer_CustomGetKeysByModelId", "consumes": [], "produces": [ @@ -105,7 +105,7 @@ "/model/{id}/": { "get": { "summary": "Get Model", - "description": "Get information about a model.", + "description": "Get information about a model.", "operationId": "FormRecognizer_CustomGetModelById", "consumes": [], "produces": [ @@ -140,7 +140,7 @@ }, "delete": { "summary": "Delete Model", - "description": "Delete model artifacts.", + "description": "Delete model artifacts.", "operationId": "FormRecognizer_CustomDeleteModelById", "consumes": [], "produces": [ @@ -177,7 +177,7 @@ "/model/{id}/analyze": { "post": { "summary": "Analyze Form", - "description": "The document to analyze must be must be of expected media type - currently supported types are application/pdf, image/jpg or image/png.", + "description": "The document to analyze must be of a supported\r\n content type - content type - 'application/pdf', 'image/jpeg' and 'image/png'.", "operationId": "FormRecognizer_CustomAnalyze", "consumes": [ "multipart/form-data" From 6efacb52aa07a4f194210a915cffea325131668f Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Fri, 19 Apr 2019 12:10:12 -0700 Subject: [PATCH 10/33] Minor text change. --- .../data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 8d4af6e5c91c..55045c420550 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -21,7 +21,7 @@ "/train": { "post": { "summary": "Train Model", - "description": "The train request must include a 'Source' parameter that is\r\n an Azure Storage blob container Uri that is that is accessible externally\r\n (preferably a Shared Access Signature Uri) or valid path to data in a locally mounted drive.\r\n When local paths are specified, they must follow the Linux/Unix path format and\r\n absolute path convention rooted to the input mount configuration setting value.\r\n Models are trained using documents that are of the following\r\n content type - 'application/pdf', 'image/jpeg' and 'image/png'.", + "description": "The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration setting value. For e.g., if {Mounts:Input} configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'. Other content is ignored when training a model.", "operationId": "FormRecognizer_CustomTrain", "consumes": [ "application/json-patch+json", From 292f8ba2462f6f58b3403cdbf0bd95bbc8b1f4ff Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Fri, 19 Apr 2019 12:40:12 -0700 Subject: [PATCH 11/33] More minor text updates. --- .../FormRecognizer/preview/v1.0/FormRecognizer.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 55045c420550..622efc3266e2 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -21,7 +21,7 @@ "/train": { "post": { "summary": "Train Model", - "description": "The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration setting value. For e.g., if {Mounts:Input} configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'. Other content is ignored when training a model.", + "description": "The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration setting value. For e.g., if {Mounts:Input} configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'. Other content is ignored when training a model. The response contains information about documents that were used in training the model along with document level information of errors that were encountered that might have prevented them from being used in model generation. A separate list of errors is also returned to indicate if any error occurred during the operation itself.", "operationId": "FormRecognizer_CustomTrain", "consumes": [ "application/json-patch+json", @@ -177,7 +177,7 @@ "/model/{id}/analyze": { "post": { "summary": "Analyze Form", - "description": "The document to analyze must be of a supported\r\n content type - content type - 'application/pdf', 'image/jpeg' and 'image/png'.", + "description": "The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason.", "operationId": "FormRecognizer_CustomAnalyze", "consumes": [ "multipart/form-data" From 781f7db7e1f0684949a690fbd6506d5ed5e5a2b0 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Sat, 20 Apr 2019 20:43:24 -0700 Subject: [PATCH 12/33] Reverting accidental change --- .../cognitiveservices/data-plane/Face/stable/v1.0/Face.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json b/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json index d0aa9bbd92b9..16875c1244dc 100644 --- a/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json +++ b/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json @@ -4194,8 +4194,8 @@ "x-ms-parameter-location": "method", "collectionFormat": "csv" }, - "endpoint": { - "name": "endpoint", + "Endpoint": { + "name": "Endpoint", "description": "Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).", "x-ms-parameter-location": "client", "required": true, From 10c7f52cd89ed139b4c4801773c660289327063c Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Sat, 20 Apr 2019 23:40:40 -0700 Subject: [PATCH 13/33] Refactor --- .../preview/v1.0/FormRecognizer.json | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 622efc3266e2..9391e7e25ef5 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -48,7 +48,7 @@ "200": { "description": "Success", "schema": { - "$ref": "#/definitions/TrainResponse" + "$ref": "#/definitions/TrainResult" } }, "default": { @@ -68,7 +68,7 @@ "/model/{id}/keys": { "get": { "summary": "Get Keys", - "description": "Use the API to retrieve the keys that were\r\n extracted by the specified model.", + "description": "Use the API to retrieve the keys that were\r\n extracted by the specified model.", "operationId": "FormRecognizer_CustomGetKeysByModelId", "consumes": [], "produces": [ @@ -210,7 +210,7 @@ "name": "form", "in": "formData", "description": "Upload content of type 'application/pdf', 'image/jpeg' or 'image/png' for processing.", - "required": false, + "required": true, "type": "file" } ], @@ -218,7 +218,7 @@ "200": { "description": "Success", "schema": { - "$ref": "#/definitions/AnalyzeResponse" + "$ref": "#/definitions/AnalyzeResult" } }, "default": { @@ -252,7 +252,7 @@ } } }, - "TrainResponse": { + "TrainResult": { "description": "Response of the Train API call.", "type": "object", "properties": { @@ -349,8 +349,8 @@ } } }, - "AnalyzeResponse": { - "description": "Analyze API response.", + "AnalyzeResult": { + "description": "Analyze API call result.", "type": "object", "properties": { "status": { @@ -412,12 +412,12 @@ "$ref": "#/definitions/KeyValuePair" } }, - "tables": { + "extractedtables": { "description": "List of Tables and their information extracted from the page.", "uniqueItems": false, "type": "array", "items": { - "$ref": "#/definitions/Table" + "$ref": "#/definitions/ExtractedTable" } } } @@ -444,7 +444,7 @@ } } }, - "Table": { + "ExtractedTable": { "description": "Extraction information about a table\r\ncontained in a page.", "type": "object", "properties": { @@ -457,7 +457,7 @@ "uniqueItems": false, "type": "array", "items": { - "$ref": "#/definitions/TableColumn" + "$ref": "#/definitions/ExtractedTableColumn" } } } @@ -486,7 +486,7 @@ } } }, - "TableColumn": { + "ExtractedTableColumn": { "description": "Extraction information of a column in\r\na table.", "type": "object", "properties": { From e137884fa86c468602379458997d57b7cefb56b4 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Mon, 22 Apr 2019 11:24:16 -0700 Subject: [PATCH 14/33] Refactor, Adding GetModels REST API placeholder --- .../preview/v1.0/FormRecognizer.json | 49 +++++++++++++------ .../preview/v1.0/examples/GetModels.json | 30 ++++++++++++ 2 files changed, 63 insertions(+), 16 deletions(-) create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModels.json diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 9391e7e25ef5..cca3e81ae729 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -102,6 +102,35 @@ } } }, + "/models": { + "get": { + "summary": "Get Models", + "description": "Get information about all trained models", + "operationId": "FormRecognizer_CustomGetModels", + "consumes": [], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "Success" + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + }, + "x-ms-examples": { + "Get Model from id": { + "$ref": "./examples/GetModels.json" + } + } + }, + }, "/model/{id}/": { "get": { "summary": "Get Model", @@ -141,7 +170,7 @@ "delete": { "summary": "Delete Model", "description": "Delete model artifacts.", - "operationId": "FormRecognizer_CustomDeleteModelById", + "operationId": "FormRecognizer_CustomModelDeleteById", "consumes": [], "produces": [ "application/json", @@ -258,7 +287,9 @@ "properties": { "modelId": { "description": "Identifier of the model.", - "type": "string" + "type": "string", + "format": "uuid", + "x-nullable": false }, "trainingDocuments": { "description": "List of documents used to train the model and the\r\ntrain operation error reported by each.", @@ -511,20 +542,6 @@ } } } - }, - "ContainerStatus": { - "type": "object", - "properties": { - "service": { - "type": "string" - }, - "apiStatus": { - "type": "string" - }, - "apiStatusMessage": { - "type": "string" - } - } } } } \ No newline at end of file diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModels.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModels.json new file mode 100644 index 000000000000..15058111fd01 --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModels.json @@ -0,0 +1,30 @@ +{ + "parameters": { + "Endpoint": "{Endpoint}", + "Content-Type": "application/json", + "Ocp-Apim-Subscription-Key": "{API key}", + "id": "{Model Id}", + "body": { + } + }, + "responses": { + "200": { + "body": [ + { + "modelId": "cd7452ff-1988-4048-9e14-89bf6f4c15de", + "version": "1", + "status": "ready", + "createdDateTime": "2019-04-18T12:47:15Z", + "lastUpdatedDateTime": "0001-01-01T00:00:00" + }, + { + "modelId": "cd7452ff-1988-4048-9e14-89bf6f4c15df", + "version": "1", + "status": "ready", + "createdDateTime": "2019-04-18T12:47:15Z", + "lastUpdatedDateTime": "0001-01-01T00:00:00" + } + ] + } + } +} \ No newline at end of file From 3753fc5e91fa316ca84d272b5895acb5c60a3623 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Thu, 25 Apr 2019 08:29:41 -0700 Subject: [PATCH 15/33] Refactor, fixes --- .../preview/v1.0/FormRecognizer.json | 1126 +++++++++-------- 1 file changed, 609 insertions(+), 517 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index cca3e81ae729..53b3a106aa8b 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -1,547 +1,639 @@ { - "swagger": "2.0", - "info": { - "version": "v1.0-preview", - "title": "Cognitive Service Form Recognizer API V1 (Preview)", - "description": "Extracts information from forms and images into structured data based on a model created by a set of representative training forms." - }, - "securityDefinitions": { - "apim_key": { - "type": "apiKey", - "name": "Ocp-Apim-Subscription-Key", - "in": "header" - } - }, - "security": [ + "swagger": "2.0", + "info": { + "version": "v1.0-preview", + "title": "Cognitive Service Form Recognizer API V1 (Preview)", + "description": "Extracts information from forms and images into structured data based on a model created by a set of representative training forms." + }, + "securityDefinitions": { + "apim_key": { + "type": "apiKey", + "name": "Ocp-Apim-Subscription-Key", + "in": "header" + } + }, + "security": [ + { + "apim_key": [] + } + ], + "x-ms-parameterized-host": { + "hostTemplate": "{Endpoint}/formrecognizer/v1.0-preview/custom", + "useSchemePrefix": false, + "parameters": [ { - "apim_key": [] + "$ref": "#/parameters/Endpoint" } - ], - "paths": { - "/train": { - "post": { - "summary": "Train Model", - "description": "The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration setting value. For e.g., if {Mounts:Input} configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'. Other content is ignored when training a model. The response contains information about documents that were used in training the model along with document level information of errors that were encountered that might have prevented them from being used in model generation. A separate list of errors is also returned to indicate if any error occurred during the operation itself.", - "operationId": "FormRecognizer_CustomTrain", - "consumes": [ - "application/json-patch+json", - "application/json", - "text/json", - "application/*+json" - ], - "produces": [ - "application/json", - "text/json" - ], - "parameters": [ - { - "name": "trainRequest", - "in": "body", - "description": "Request object for training.", - "required": true, - "schema": { - "$ref": "#/definitions/TrainRequest" - } - } - ], - "responses": { - "200": { - "description": "Success", - "schema": { - "$ref": "#/definitions/TrainResult" - } - }, - "default": { - "description": "Response entity accompanying non-successful responses containing additional details about the error.", - "schema": { - "$ref": "#/definitions/ErrorResponse" - } - } - }, - "x-ms-examples": { - "Train new model example": { - "$ref": "./examples/Train.json" - } - }, + ] + }, + "schemes": [ + "https" + ], + "paths": { + "/train": { + "post": { + "summary": "Train Model", + "description": "The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration\r\n setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'.\"\r\n Other content is ignored when training a model.", + "operationId": "TrainCustomModel", + "consumes": [ + "application/json-patch+json", + "application/json", + "text/json", + "application/*+json" + ], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [ + { + "name": "trainRequest", + "in": "body", + "description": "Request object for training.", + "required": true, + "schema": { + "$ref": "#/definitions/TrainRequest" } - }, - "/model/{id}/keys": { - "get": { - "summary": "Get Keys", - "description": "Use the API to retrieve the keys that were\r\n extracted by the specified model.", - "operationId": "FormRecognizer_CustomGetKeysByModelId", - "consumes": [], - "produces": [ - "application/json", - "text/json" - ], - "parameters": [ - { - "name": "id", - "in": "path", - "description": "Model identifier.", - "required": true, - "type": "string" - } - ], - "responses": { - "200": { - "description": "Success" - }, - "default": { - "description": "Response entity accompanying non-successful responses containing additional details about the error.", - "schema": { - "$ref": "#/definitions/ErrorResponse" - } - } - }, - "x-ms-examples": { - "Get Keys from Model": { - "$ref": "./examples/GetKeys.json" - } - } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/TrainResult" } - }, - "/models": { - "get": { - "summary": "Get Models", - "description": "Get information about all trained models", - "operationId": "FormRecognizer_CustomGetModels", - "consumes": [], - "produces": [ - "application/json", - "text/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "Success" - }, - "default": { - "description": "Response entity accompanying non-successful responses containing additional details about the error.", - "schema": { - "$ref": "#/definitions/ErrorResponse" - } - } - }, - "x-ms-examples": { - "Get Model from id": { - "$ref": "./examples/GetModels.json" - } - } - }, - }, - "/model/{id}/": { - "get": { - "summary": "Get Model", - "description": "Get information about a model.", - "operationId": "FormRecognizer_CustomGetModelById", - "consumes": [], - "produces": [ - "application/json", - "text/json" - ], - "parameters": [ - { - "name": "id", - "in": "path", - "description": "Model identifier.", - "required": true, - "type": "string" - } - ], - "responses": { - "200": { - "description": "Success" - }, - "default": { - "description": "Response entity accompanying non-successful responses containing additional details about the error.", - "schema": { - "$ref": "#/definitions/ErrorResponse" - } - } - }, - "x-ms-examples": { - "Get Model from id": { - "$ref": "./examples/GetModelById.json" - } - } - }, - "delete": { - "summary": "Delete Model", - "description": "Delete model artifacts.", - "operationId": "FormRecognizer_CustomModelDeleteById", - "consumes": [], - "produces": [ - "application/json", - "text/json" - ], - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The identifier of the model to delete.", - "required": true, - "type": "string" - } - ], - "responses": { - "204": { - "description": "Successfully removed model artifacts." - }, - "default": { - "description": "Response entity accompanying non-successful responses containing additional details about the error.", - "schema": { - "$ref": "#/definitions/ErrorResponse" - } - } - }, - "x-ms-examples": { - "Get Model from id": { - "$ref": "./examples/DeleteModelById.json" - } - } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" } + } }, - "/model/{id}/analyze": { - "post": { - "summary": "Analyze Form", - "description": "The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason.", - "operationId": "FormRecognizer_CustomAnalyze", - "consumes": [ - "multipart/form-data" - ], - "produces": [ - "application/json", - "text/json" - ], - "parameters": [ - { - "name": "id", - "in": "path", - "description": "Identifier of the model to analyze the document with.", - "required": true, - "type": "string" - }, - { - "name": "keys", - "in": "query", - "description": "An optional list of known keys to extract the values for.", - "required": false, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "multi", - "uniqueItems": false - }, - { - "name": "form", - "in": "formData", - "description": "Upload content of type 'application/pdf', 'image/jpeg' or 'image/png' for processing.", - "required": true, - "type": "file" - } - ], - "responses": { - "200": { - "description": "Success", - "schema": { - "$ref": "#/definitions/AnalyzeResult" - } - }, - "default": { - "description": "Response entity accompanying non-successful responses containing additional details about the error.", - "schema": { - "$ref": "#/definitions/ErrorResponse" - } - } - }, - "x-ms-examples": { - "Get Model from id": { - "$ref": "./examples/Analyze.json" - } - } - } + "x-ms-examples": { + "Train new model example": { + "$ref": "./examples/Train.json" + } } + } }, - "definitions": { - "TrainRequest": { - "description": "Contract to initiate a train request.", - "required": [ - "source" - ], - "type": "object", - "properties": { - "source": { - "description": "Get or set source path.", - "maxLength": 2048, - "minLength": 0, - "type": "string" - } + "/model/{id}/keys": { + "get": { + "summary": "Get Keys", + "description": "Use the API to retrieve the keys that were\r\n extracted by the specified model.", + "operationId": "GetExtractedKeysByCustomModelId", + "consumes": [], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Model identifier.", + "required": true, + "type": "string", + "format": "uuid" + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/KeysResult" } - }, - "TrainResult": { - "description": "Response of the Train API call.", - "type": "object", - "properties": { - "modelId": { - "description": "Identifier of the model.", - "type": "string", - "format": "uuid", - "x-nullable": false - }, - "trainingDocuments": { - "description": "List of documents used to train the model and the\r\ntrain operation error reported by each.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/FormDocumentReport" - } - }, - "errors": { - "description": "Errors returned during the training operation.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/FormOperationError" - } - } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" } + } }, - "FormDocumentReport": { - "type": "object", - "properties": { - "documentName": { - "description": "Reference to the data that the report is for.", - "type": "string" - }, - "pages": { - "format": "int32", - "description": "Total number of pages trained on.", - "type": "integer" - }, - "errors": { - "description": "List of errors per page.", - "uniqueItems": false, - "type": "array", - "items": { - "type": "string" - } - }, - "status": { - "description": "Status of the training operation.", - "enum": [ - "success", - "partialSuccess", - "failure" - ], - "type": "string" - } + "x-ms-examples": { + "Get Keys from Model": { + "$ref": "./examples/GetKeys.json" + } + } + } + }, + "/models": { + "get": { + "summary": "Get Models", + "description": "Get information about all trained models", + "operationId": "GetListOfCustomModels", + "consumes": [], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/ModelInfoList" } - }, - "FormOperationError": { - "description": "Error reported during an operation.", - "type": "object", - "properties": { - "errorMessage": { - "description": "Message reported during the train operation.", - "type": "string" - } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" } + } }, - "ErrorResponse": { - "type": "object", - "properties": { - "error": { - "$ref": "#/definitions/ErrorInformation" - } + "x-ms-examples": { + "Get Model from id": { + "$ref": "./examples/GetModels.json" + } + } + } + }, + "/model/{id}/": { + "get": { + "summary": "Get Model", + "description": "Get information about a model.", + "operationId": "GetCustomModelById", + "consumes": [], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Model identifier.", + "required": true, + "type": "string", + "format": "uuid" + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/ModelInfo" } - }, - "ErrorInformation": { - "type": "object", - "properties": { - "code": { - "type": "string" - }, - "innerError": { - "$ref": "#/definitions/InnerError" - }, - "message": { - "type": "string" - } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" } + } }, - "InnerError": { - "type": "object", - "properties": { - "requestId": { - "type": "string" - } + "x-ms-examples": { + "Get Model from id": { + "$ref": "./examples/GetModelById.json" + } + } + }, + "delete": { + "summary": "Delete Model", + "description": "Delete model artifacts.", + "operationId": "DeleteCustomModelById", + "consumes": [], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "The identifier of the model to delete.", + "required": true, + "type": "string", + "format": "uuid" + } + ], + "responses": { + "204": { + "description": "Successfully removed model artifacts." + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" } + } }, - "AnalyzeResult": { - "description": "Analyze API call result.", - "type": "object", - "properties": { - "status": { - "description": "Status of the analyze operation.", - "enum": [ - "success", - "partialSuccess", - "failure" - ], - "type": "string" - }, - "pages": { - "description": "Page level information extracted in the analyzed\r\ndocument.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/Page" - } - }, - "errors": { - "description": "List of errors reported during the analyze\r\noperation.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/FormOperationError" - } - } + "x-ms-examples": { + "Get Model from id": { + "$ref": "./examples/DeleteModelById.json" + } + } + } + }, + "/model/{id}/analyze": { + "post": { + "summary": "Analyze Form", + "description": "The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason.", + "operationId": "AnalyzeCustomModel", + "consumes": [ + "application/pdf", + "image/jpeg", + "image/png", + "multipart/form-data" + ], + "produces": [ + "application/json", + "text/json" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Model Identifier to analyze the document with.", + "required": true, + "type": "string" + }, + { + "name": "keys", + "in": "query", + "description": "An optional list of known keys to extract the values for.", + "required": false, + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "uniqueItems": false + }, + { + "name": "form_stream", + "in": "formData", + "description": "Upload content of type 'application/pdf', 'image/jpeg' or 'image/png' for processing.", + "required": true, + "type": "file" + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/AnalyzeResult" } - }, - "Page": { - "description": "Extraction information of a single page in a\r\nwith a document.", - "type": "object", - "properties": { - "number": { - "format": "int32", - "description": "Page number.", - "type": "integer" - }, - "height": { - "format": "int32", - "description": "Height of the page (in pixels).", - "type": "integer" - }, - "width": { - "format": "int32", - "description": "Width of the page (in pixels).", - "type": "integer" - }, - "clusterId": { - "format": "int32", - "description": "Cluster identifier.", - "type": "integer" - }, - "keyValuePairs": { - "description": "List of Key-Value pairs extracted from the page.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/KeyValuePair" - } - }, - "extractedtables": { - "description": "List of Tables and their information extracted from the page.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/ExtractedTable" - } - } + }, + "default": { + "description": "Response entity accompanying non-successful responses containing additional details about the error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" } + } }, - "KeyValuePair": { - "description": "Representation of a key-value pair as a list\r\nof key and value tokens.", - "type": "object", - "properties": { - "key": { - "description": "List of tokens for the extracted key in a key-value pair.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/Token" - } - }, - "value": { - "description": "List of tokens for the extracted value in a key-value pair.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/Token" - } - } - } + "x-ms-examples": { + "Get Model from id": { + "$ref": "./examples/Analyze.json" + } + } + } + } + }, + "definitions": { + "TrainRequest": { + "description": "Contract to initiate a train request.", + "required": [ + "source" + ], + "type": "object", + "properties": { + "source": { + "description": "Get or set source path.", + "maxLength": 2048, + "minLength": 0, + "type": "string" + } + } + }, + "TrainResult": { + "description": "Response of the Train API call.", + "type": "object", + "properties": { + "modelId": { + "description": "Identifier of the model.", + "type": "string", + "format": "uuid", + "x-nullable": false }, - "ExtractedTable": { - "description": "Extraction information about a table\r\ncontained in a page.", - "type": "object", - "properties": { - "id": { - "description": "Table identifier.", - "type": "string" - }, - "columns": { - "description": "List of columns contained in the table.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/ExtractedTableColumn" - } - } - } + "trainingDocuments": { + "description": "List of documents used to train the model and the\r\ntrain operation error reported by each.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/FormDocumentReport" + } }, - "Token": { - "description": "Canonical representation of single extracted text.", - "type": "object", - "properties": { - "text": { - "description": "String value of the extracted text.", - "type": "string" - }, - "boundingBox": { - "description": "Bounding box of the extracted text. Represents the\r\nlocation of the extracted text as a pair of\r\ncartesian co-ordinates. The co-ordinate pairs are arranged by\r\ntop-left, top-right, bottom-right and bottom-left endpoints box\r\nwith origin reference from the bottom-left of the page.", - "uniqueItems": false, - "type": "array", - "items": { - "format": "double", - "type": "number" - } - }, - "confidence": { - "format": "double", - "description": "A measure of accuracy of the extracted text.", - "type": "number" - } - } + "errors": { + "description": "Errors returned during the training operation.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/FormOperationError" + } + } + } + }, + "KeysResult": { + "description": "Response of the Keys API call.", + "type": "object", + "properties": { + "clusters" : { + "description": "Cluster of keys", + "type": "object" + } + } + }, + "ModelInfo": { + "description": "Response of the Model API call.", + "type": "object", + "properties": { + "modelId": { + "description": "Identifier of the model.", + "type": "string", + "format": "uuid", + "x-nullable": false + }, + "version": { + "description": "Version of model.", + "type": "integer", + "minimum": 1 + }, + "status": { + "description": "Status of model.", + "type": "string", + "enum": [ + "Created", + "Ready", + "Invalid" + ] + }, + "createdDateTime": { + "description": "Date and Time model is created.", + "type": "string", + "format": "date-time" + }, + "lastUpdatedDateTime": { + "description": "Date and Time model is last updated.", + "type": "string", + "format": "date-time" + } + } + }, + "ModelInfoList": { + "description": "List of all the models created.", + "uniqueItems": true, + "type": "array", + "items": { + "$ref": "#/definitions/ModelInfo" + } + }, + "FormDocumentReport": { + "type": "object", + "properties": { + "documentName": { + "description": "Reference to the data that the report is for.", + "type": "string" }, - "ExtractedTableColumn": { - "description": "Extraction information of a column in\r\na table.", - "type": "object", - "properties": { - "header": { - "description": "List of extracted tokens for the column header.", - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/Token" - } - }, - "entries": { - "description": "Extracted text for each cell of a column. Each cell\r\nin the column can have a list of one or more tokens.", - "uniqueItems": false, - "type": "array", - "items": { - "uniqueItems": false, - "type": "array", - "items": { - "$ref": "#/definitions/Token" - } - } - } + "pages": { + "format": "int32", + "description": "Total number of pages trained on.", + "type": "integer" + }, + "errors": { + "description": "List of errors per page.", + "uniqueItems": false, + "type": "array", + "items": { + "type": "string" + } + }, + "status": { + "description": "Status of the training operation.", + "enum": [ + "success", + "partialSuccess", + "failure" + ], + "type": "string" + } + } + }, + "FormOperationError": { + "description": "Error reported during an operation.", + "type": "object", + "properties": { + "errorMessage": { + "description": "Message reported during the train operation.", + "type": "string" + } + } + }, + "ErrorResponse": { + "type": "object", + "properties": { + "error": { + "$ref": "#/definitions/ErrorInformation" + } + } + }, + "ErrorInformation": { + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "innerError": { + "$ref": "#/definitions/InnerError" + }, + "message": { + "type": "string" + } + } + }, + "InnerError": { + "type": "object", + "properties": { + "requestId": { + "type": "string" + } + } + }, + "AnalyzeResult": { + "description": "Analyze API call result.", + "type": "object", + "properties": { + "status": { + "description": "Status of the analyze operation.", + "enum": [ + "success", + "partialSuccess", + "failure" + ], + "type": "string" + }, + "pages": { + "description": "Page level information extracted in the analyzed\r\ndocument.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/ExtractedPage" + } + }, + "errors": { + "description": "List of errors reported during the analyze\r\noperation.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/FormOperationError" + } + } + } + }, + "ExtractedPage": { + "description": "Extraction information of a single page in a\r\nwith a document.", + "type": "object", + "properties": { + "number": { + "format": "int32", + "description": "Page number.", + "type": "integer" + }, + "height": { + "format": "int32", + "description": "Height of the page (in pixels).", + "type": "integer" + }, + "width": { + "format": "int32", + "description": "Width of the page (in pixels).", + "type": "integer" + }, + "clusterId": { + "format": "int32", + "description": "Cluster identifier.", + "type": "integer" + }, + "keyValuePairs": { + "description": "List of Key-Value pairs extracted from the page.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/ExtractedKeyValuePair" + } + }, + "extractedtables": { + "description": "List of Tables and their information extracted from the page.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/ExtractedTable" + } + } + } + }, + "ExtractedKeyValuePair": { + "description": "Representation of a key-value pair as a list\r\nof key and value tokens.", + "type": "object", + "properties": { + "key": { + "description": "List of tokens for the extracted key in a key-value pair.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/ExtractedToken" + } + }, + "value": { + "description": "List of tokens for the extracted value in a key-value pair.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/ExtractedToken" + } + } + } + }, + "ExtractedTable": { + "description": "Extraction information about a table\r\ncontained in a page.", + "type": "object", + "properties": { + "id": { + "description": "Table identifier.", + "type": "string" + }, + "columns": { + "description": "List of columns contained in the table.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/ExtractedTableColumn" + } + } + } + }, + "ExtractedToken": { + "description": "Canonical representation of single extracted text.", + "type": "object", + "properties": { + "text": { + "description": "String value of the extracted text.", + "type": "string" + }, + "boundingBox": { + "description": "Bounding box of the extracted text. Represents the\r\nlocation of the extracted text as a pair of\r\ncartesian co-ordinates. The co-ordinate pairs are arranged by\r\ntop-left, top-right, bottom-right and bottom-left endpoints box\r\nwith origin reference from the bottom-left of the page.", + "uniqueItems": false, + "type": "array", + "items": { + "format": "double", + "type": "number" + } + }, + "confidence": { + "format": "double", + "description": "A measure of accuracy of the extracted text.", + "type": "number" + } + } + }, + "ExtractedTableColumn": { + "description": "Extraction information of a column in\r\na table.", + "type": "object", + "properties": { + "header": { + "description": "List of extracted tokens for the column header.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/ExtractedToken" + } + }, + "entries": { + "description": "Extracted text for each cell of a column. Each cell\r\nin the column can have a list of one or more tokens.", + "uniqueItems": false, + "type": "array", + "items": { + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/ExtractedToken" } + } } + } + } + }, + "parameters": { + "Endpoint": { + "name": "Endpoint", + "description": "Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).", + "x-ms-parameter-location": "client", + "required": true, + "type": "string", + "in": "path", + "x-ms-skip-url-encoding": true } + } } \ No newline at end of file From 5ed88d4b9f8788e926ff7ec3919b609d70cd57de Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Thu, 25 Apr 2019 14:12:39 -0700 Subject: [PATCH 16/33] Refactor, Updated definitions. --- .../preview/v1.0/FormRecognizer.json | 66 ++++++++----------- 1 file changed, 27 insertions(+), 39 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 53b3a106aa8b..9fa576030241 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -133,7 +133,9 @@ "200": { "description": "Success", "schema": { - "$ref": "#/definitions/ModelInfoList" + "uniqueItems": false, + "type": "array", + "items": { "$ref": "#/definitions/ModelResult" } } }, "default": { @@ -174,7 +176,7 @@ "200": { "description": "Success", "schema": { - "$ref": "#/definitions/ModelInfo" + "$ref": "#/definitions/ModelResult" } }, "default": { @@ -337,58 +339,44 @@ } }, "KeysResult": { - "description": "Response of the Keys API call.", + "description": "Result of an operation to get\r\nthe keys extracted by a model.", "type": "object", "properties": { - "clusters" : { - "description": "Cluster of keys", - "type": "object" + "clusters": { + "description": "Object mapping ClusterIds to Key lists.", + "type": "object", + "additionalProperties": { + "uniqueItems": false, + "type": "array", + "items": { "type": "string" } + } } } }, - "ModelInfo": { - "description": "Response of the Model API call.", + "ModelResult": { + "description": "Result of a model status query operation.", "type": "object", "properties": { "modelId": { - "description": "Identifier of the model.", - "type": "string", - "format": "uuid", - "x-nullable": false - }, - "version": { - "description": "Version of model.", - "type": "integer", - "minimum": 1 + "description": "Get or set model identifier.", + "type": "string" }, "status": { - "description": "Status of model.", - "type": "string", - "enum": [ - "Created", - "Ready", - "Invalid" - ] + "description": "Get or set the status of model.", + "enum": [ "created", "ready", "invalid" ], + "type": "string" }, "createdDateTime": { - "description": "Date and Time model is created.", - "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Get or set the created date time of the model.", + "type": "string" }, "lastUpdatedDateTime": { - "description": "Date and Time model is last updated.", - "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Get or set the model last updated datetime.", + "type": "string" } - } - }, - "ModelInfoList": { - "description": "List of all the models created.", - "uniqueItems": true, - "type": "array", - "items": { - "$ref": "#/definitions/ModelInfo" - } + } }, "FormDocumentReport": { "type": "object", From 9864cca7a497976fd2ef01204e94a0d28bf63d8d Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Thu, 25 Apr 2019 16:14:30 -0700 Subject: [PATCH 17/33] Fix type definition --- .../FormRecognizer/preview/v1.0/FormRecognizer.json | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 9fa576030241..68188591720d 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -250,7 +250,8 @@ "in": "path", "description": "Model Identifier to analyze the document with.", "required": true, - "type": "string" + "type": "string", + "format": "uuid" }, { "name": "keys", @@ -512,7 +513,7 @@ "$ref": "#/definitions/ExtractedKeyValuePair" } }, - "extractedtables": { + "tables": { "description": "List of Tables and their information extracted from the page.", "uniqueItems": false, "type": "array", From da9d7d33f33d75de86efb53e25f768138b32e7d8 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Fri, 26 Apr 2019 10:40:28 -0700 Subject: [PATCH 18/33] model* API endpoint updated --- .../FormRecognizer/preview/v1.0/FormRecognizer.json | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 68188591720d..628f24cbc30b 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -77,7 +77,7 @@ } } }, - "/model/{id}/keys": { + "/models/{id}/keys": { "get": { "summary": "Get Keys", "description": "Use the API to retrieve the keys that were\r\n extracted by the specified model.", @@ -152,7 +152,7 @@ } } }, - "/model/{id}/": { + "/models/{id}/": { "get": { "summary": "Get Model", "description": "Get information about a model.", @@ -229,7 +229,7 @@ } } }, - "/model/{id}/analyze": { + "/models/{id}/analyze": { "post": { "summary": "Analyze Form", "description": "The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason.", @@ -251,7 +251,7 @@ "description": "Model Identifier to analyze the document with.", "required": true, "type": "string", - "format": "uuid" + "format": "uuid" }, { "name": "keys", @@ -360,7 +360,9 @@ "properties": { "modelId": { "description": "Get or set model identifier.", - "type": "string" + "type": "string", + "format": uuid, + "x-nullable": false }, "status": { "description": "Get or set the status of model.", From 81b674317498aed0591d8b73bf9ad5b06cdadaf9 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Fri, 26 Apr 2019 11:09:33 -0700 Subject: [PATCH 19/33] Fix build issue, Reverting change to face swagger --- .../data-plane/Face/stable/v1.0/Face.json | 9 +++++++++ .../data-plane/FormRecognizer/readme.md | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json b/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json index 16875c1244dc..07f5f0df564a 100644 --- a/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json +++ b/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json @@ -17,6 +17,15 @@ "apim_key": [] } ], + "x-ms-parameterized-host": { + "hostTemplate": "{Endpoint}/face/v1.0", + "useSchemePrefix": false, + "parameters": [ + { + "$ref": "#/parameters/Endpoint" + } + ] + }, "paths": { "/findsimilars": { "post": { diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md index 9d6087b1a09f..f081fb4c8402 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md +++ b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md @@ -18,7 +18,7 @@ openapi-type: data-plane These settings apply only when `--tag=release_1_0` is specified on the command line. ``` yaml $(tag) == 'release_1_0' -input-file: preview/v1.0/formrecognizer.json +input-file: preview/v1.0/FormRecognizer.json ``` ## Swagger to SDK From 4d751315fe8e737882535c76edfdc2f1acb74aed Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Fri, 26 Apr 2019 12:09:16 -0700 Subject: [PATCH 20/33] updated namespace --- .../cognitiveservices/data-plane/FormRecognizer/readme.md | 4 ++-- .../data-plane/FormRecognizer/readme.python.md | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md index f081fb4c8402..2b2e234f7b27 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md +++ b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md @@ -45,7 +45,7 @@ csharp: sync-methods: None license-header: MICROSOFT_MIT_NO_VERSION azure-arm: false - namespace: Microsoft.Azure.CognitiveServices.Vision.FormRecognizer + namespace: Microsoft.Azure.CognitiveServices.FormRecognizer output-folder: $(csharp-sdks-folder)/CognitiveServices/dataPlane/Vision/FormRecognizer/Generated clear-output-folder: true ``` @@ -62,7 +62,7 @@ Please also specify `--azure-libraries-for-java-folder= Date: Fri, 26 Apr 2019 17:25:56 -0700 Subject: [PATCH 21/33] Updated return type for /models api --- .../preview/v1.0/FormRecognizer.json | 20 +++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 628f24cbc30b..7351f1f2d0f5 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -133,9 +133,7 @@ "200": { "description": "Success", "schema": { - "uniqueItems": false, - "type": "array", - "items": { "$ref": "#/definitions/ModelResult" } + "$ref": "#/definitions/ModelsResult" } }, "default": { @@ -361,7 +359,7 @@ "modelId": { "description": "Get or set model identifier.", "type": "string", - "format": uuid, + "format": "uuid", "x-nullable": false }, "status": { @@ -381,6 +379,20 @@ } } }, + "ModelsResult": { + "description": "Result of query operation to fetch multiple models.", + "type": "object", + "properties": { + "models": { + "description": "Collection of models.", + "uniqueItems": false, + "type": "array", + "items": { + "$ref": "#/definitions/ModelResult" + } + } + } + }, "FormDocumentReport": { "type": "object", "properties": { From 4e65e771a2d7d3e454399950701b5b97336d5840 Mon Sep 17 00:00:00 2001 From: Barbara Date: Fri, 26 Apr 2019 21:27:33 -0700 Subject: [PATCH 22/33] Update FormRecognizer.json fix paths of methods (add custom) and fix path of hosttemplate --- .../preview/v1.0/FormRecognizer.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 7351f1f2d0f5..09dbf493303c 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -18,7 +18,7 @@ } ], "x-ms-parameterized-host": { - "hostTemplate": "{Endpoint}/formrecognizer/v1.0-preview/custom", + "hostTemplate": "{Endpoint}/formrecognizer/v1.0-preview", "useSchemePrefix": false, "parameters": [ { @@ -30,7 +30,7 @@ "https" ], "paths": { - "/train": { + "/custom/train": { "post": { "summary": "Train Model", "description": "The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration\r\n setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'.\"\r\n Other content is ignored when training a model.", @@ -77,7 +77,7 @@ } } }, - "/models/{id}/keys": { + "/custom/models/{id}/keys": { "get": { "summary": "Get Keys", "description": "Use the API to retrieve the keys that were\r\n extracted by the specified model.", @@ -118,7 +118,7 @@ } } }, - "/models": { + "/custom/models": { "get": { "summary": "Get Models", "description": "Get information about all trained models", @@ -150,7 +150,7 @@ } } }, - "/models/{id}/": { + "/custom/models/{id}/": { "get": { "summary": "Get Model", "description": "Get information about a model.", @@ -190,7 +190,7 @@ } } }, - "delete": { + "/custom/delete": { "summary": "Delete Model", "description": "Delete model artifacts.", "operationId": "DeleteCustomModelById", @@ -227,7 +227,7 @@ } } }, - "/models/{id}/analyze": { + "/custom/models/{id}/analyze": { "post": { "summary": "Analyze Form", "description": "The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason.", @@ -639,4 +639,4 @@ "x-ms-skip-url-encoding": true } } -} \ No newline at end of file +} From 4c99141f58811a0d372dd3014b7efad028bba3c5 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Tue, 30 Apr 2019 09:50:13 -0700 Subject: [PATCH 23/33] Refactor, opid changes. --- .../preview/v1.0/FormRecognizer.json | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 09dbf493303c..14847ace1504 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -34,7 +34,7 @@ "post": { "summary": "Train Model", "description": "The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration\r\n setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'.\"\r\n Other content is ignored when training a model.", - "operationId": "TrainCustomModel", + "operationId": "TrainModel", "consumes": [ "application/json-patch+json", "application/json", @@ -81,7 +81,7 @@ "get": { "summary": "Get Keys", "description": "Use the API to retrieve the keys that were\r\n extracted by the specified model.", - "operationId": "GetExtractedKeysByCustomModelId", + "operationId": "GetExtractedKeys", "consumes": [], "produces": [ "application/json", @@ -122,7 +122,7 @@ "get": { "summary": "Get Models", "description": "Get information about all trained models", - "operationId": "GetListOfCustomModels", + "operationId": "GetModels", "consumes": [], "produces": [ "application/json", @@ -150,11 +150,11 @@ } } }, - "/custom/models/{id}/": { + "/custom/models/{id}": { "get": { "summary": "Get Model", "description": "Get information about a model.", - "operationId": "GetCustomModelById", + "operationId": "GetModel", "consumes": [], "produces": [ "application/json", @@ -190,10 +190,10 @@ } } }, - "/custom/delete": { + "delete": { "summary": "Delete Model", "description": "Delete model artifacts.", - "operationId": "DeleteCustomModelById", + "operationId": "DeleteModel", "consumes": [], "produces": [ "application/json", @@ -231,7 +231,7 @@ "post": { "summary": "Analyze Form", "description": "The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason.", - "operationId": "AnalyzeCustomModel", + "operationId": "AnalyzeWithModel", "consumes": [ "application/pdf", "image/jpeg", @@ -262,11 +262,11 @@ }, "collectionFormat": "multi", "uniqueItems": false - }, + }, { "name": "form_stream", "in": "formData", - "description": "Upload content of type 'application/pdf', 'image/jpeg' or 'image/png' for processing.", + "description": "A pdf document or image (jpg,png) file to analyze.", "required": true, "type": "file" } From 8385975148ed0e78dcb8126d1a8ceaf602139d2e Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Tue, 30 Apr 2019 11:03:19 -0700 Subject: [PATCH 24/33] removing multi as it causing autorest codegen issues with langs like go, ruby etc. --- .../data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 14847ace1504..47c6f82a24d1 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -260,7 +260,6 @@ "items": { "type": "string" }, - "collectionFormat": "multi", "uniqueItems": false }, { From 9b1f37a9a06cc8d9bc7f9bc9137b4e6e0b0fdc05 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Tue, 30 Apr 2019 12:40:56 -0700 Subject: [PATCH 25/33] reverting face.json changes. --- .../cognitiveservices/data-plane/Face/stable/v1.0/Face.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json b/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json index 07f5f0df564a..5ccdf42ae6d6 100644 --- a/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json +++ b/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json @@ -25,7 +25,7 @@ "$ref": "#/parameters/Endpoint" } ] - }, + }, "paths": { "/findsimilars": { "post": { From 355ce60ea5b697c3ff693e2bff99f9ffebde92bf Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Tue, 30 Apr 2019 14:17:50 -0700 Subject: [PATCH 26/33] renamed example, fixed typo in example to make it valid json --- .../data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json | 2 +- .../preview/v1.0/examples/{GetModelById.json => GetModel.json} | 0 .../data-plane/FormRecognizer/preview/v1.0/examples/Train.json | 2 +- 3 files changed, 2 insertions(+), 2 deletions(-) rename specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/{GetModelById.json => GetModel.json} (100%) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 47c6f82a24d1..e05a04efea50 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -186,7 +186,7 @@ }, "x-ms-examples": { "Get Model from id": { - "$ref": "./examples/GetModelById.json" + "$ref": "./examples/GetModel.json" } } }, diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModelById.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModel.json similarity index 100% rename from specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModelById.json rename to specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModel.json diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json index c08bf03a89f1..39bd8922eb4d 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json @@ -4,7 +4,7 @@ "Content-Type": "application/json", "Ocp-Apim-Subscription-Key": "{API key}", "body": { - "source": "/input/data", + "source": "/input/data" } }, "responses": { From afc041b90293c894a3ff3ec8f08cd52dbec4d6e7 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Tue, 30 Apr 2019 16:41:55 -0700 Subject: [PATCH 27/33] API review feedback, Reverting OpIds --- .../preview/v1.0/FormRecognizer.json | 18 +++++++----------- .../preview/v1.0/examples/Train.json | 1 + 2 files changed, 8 insertions(+), 11 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index e05a04efea50..57aea9278aac 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -34,16 +34,12 @@ "post": { "summary": "Train Model", "description": "The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration\r\n setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'.\"\r\n Other content is ignored when training a model.", - "operationId": "TrainModel", + "operationId": "TrainCustomModel", "consumes": [ - "application/json-patch+json", - "application/json", - "text/json", - "application/*+json" + "application/json" ], "produces": [ - "application/json", - "text/json" + "application/json" ], "parameters": [ { @@ -122,7 +118,7 @@ "get": { "summary": "Get Models", "description": "Get information about all trained models", - "operationId": "GetModels", + "operationId": "GetCustomModels", "consumes": [], "produces": [ "application/json", @@ -154,7 +150,7 @@ "get": { "summary": "Get Model", "description": "Get information about a model.", - "operationId": "GetModel", + "operationId": "GetCustomModel", "consumes": [], "produces": [ "application/json", @@ -193,7 +189,7 @@ "delete": { "summary": "Delete Model", "description": "Delete model artifacts.", - "operationId": "DeleteModel", + "operationId": "DeleteCustomModel", "consumes": [], "produces": [ "application/json", @@ -231,7 +227,7 @@ "post": { "summary": "Analyze Form", "description": "The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason.", - "operationId": "AnalyzeWithModel", + "operationId": "AnalyzeWithCustomModel", "consumes": [ "application/pdf", "image/jpeg", diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json index 39bd8922eb4d..b6d0511cc881 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json @@ -14,6 +14,7 @@ "modelId": "640b1c8a-0a44-4611-94a6-f7d0130783cc", "trainingDocuments": [ { + "documentName": "docname.pdf", "pages": 1, "errors": [], "status": "success" From c5ddd4bb38d34fdc58652ccc0aa5d0b670f439d4 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Wed, 1 May 2019 04:24:21 -0700 Subject: [PATCH 28/33] API review feedback, fixing examples for model verification --- .../preview/v1.0/FormRecognizer.json | 19 ++++----- .../preview/v1.0/examples/Analyze.json | 8 ++-- ...{DeleteModelById.json => DeleteModel.json} | 4 +- .../preview/v1.0/examples/GetKeys.json | 4 +- .../preview/v1.0/examples/GetModel.json | 4 +- .../preview/v1.0/examples/GetModels.json | 30 +++++++------- .../preview/v1.0/examples/Train.json | 40 ++++++++++++++----- 7 files changed, 59 insertions(+), 50 deletions(-) rename specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/{DeleteModelById.json => DeleteModel.json} (90%) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index 57aea9278aac..db9431589bd8 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -80,9 +80,8 @@ "operationId": "GetExtractedKeys", "consumes": [], "produces": [ - "application/json", - "text/json" - ], + "application/json" + ], "parameters": [ { "name": "id", @@ -121,8 +120,7 @@ "operationId": "GetCustomModels", "consumes": [], "produces": [ - "application/json", - "text/json" + "application/json" ], "parameters": [], "responses": { @@ -153,8 +151,7 @@ "operationId": "GetCustomModel", "consumes": [], "produces": [ - "application/json", - "text/json" + "application/json" ], "parameters": [ { @@ -192,8 +189,7 @@ "operationId": "DeleteCustomModel", "consumes": [], "produces": [ - "application/json", - "text/json" + "application/json" ], "parameters": [ { @@ -218,7 +214,7 @@ }, "x-ms-examples": { "Get Model from id": { - "$ref": "./examples/DeleteModelById.json" + "$ref": "./examples/DeleteModel.json" } } } @@ -235,8 +231,7 @@ "multipart/form-data" ], "produces": [ - "application/json", - "text/json" + "application/json" ], "parameters": [ { diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Analyze.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Analyze.json index 60a280675e01..0846d50372cb 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Analyze.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Analyze.json @@ -5,13 +5,14 @@ "Ocp-Apim-Subscription-Key": "{API key}", "id": "{Model Id}", "body": { - "formData": "{Image or Pdf file stream}" + "formData": { + "form_stream": "{Image or Pdf file stream}" + } } }, "responses": { "200": { - "body": [ - { + "body":{ "status": "success", "pages": [ { @@ -104,7 +105,6 @@ } ] } - ] } } } diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/DeleteModelById.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/DeleteModel.json similarity index 90% rename from specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/DeleteModelById.json rename to specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/DeleteModel.json index ee5e16d02416..ba8131f4ee07 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/DeleteModelById.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/DeleteModel.json @@ -9,8 +9,8 @@ }, "responses": { "204": { - "body": [ - ] + "body": { + } } } } diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetKeys.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetKeys.json index 029a9005baec..174194c2ecd7 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetKeys.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetKeys.json @@ -9,8 +9,7 @@ }, "responses": { "200": { - "body": [ - { + "body": { "clusters": { "0": [ "Invoice", @@ -22,7 +21,6 @@ ] } } - ] } } } diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModel.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModel.json index 6c5fc0f32adf..c1f30750f103 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModel.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModel.json @@ -9,15 +9,13 @@ }, "responses": { "200": { - "body": [ - { + "body":{ "modelId": "cd7452ff-1988-4048-9e14-89bf6f4c15de", "version": "1", "status": "ready", "createdDateTime": "2019-04-18T12:47:15.3291661Z", "lastUpdatedDateTime": "0001-01-01T00:00:00" } - ] } } } \ No newline at end of file diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModels.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModels.json index 15058111fd01..908a1cc4ca84 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModels.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModels.json @@ -9,22 +9,22 @@ }, "responses": { "200": { - "body": [ - { - "modelId": "cd7452ff-1988-4048-9e14-89bf6f4c15de", - "version": "1", - "status": "ready", - "createdDateTime": "2019-04-18T12:47:15Z", - "lastUpdatedDateTime": "0001-01-01T00:00:00" - }, - { - "modelId": "cd7452ff-1988-4048-9e14-89bf6f4c15df", - "version": "1", - "status": "ready", - "createdDateTime": "2019-04-18T12:47:15Z", - "lastUpdatedDateTime": "0001-01-01T00:00:00" + "body": { + "models": [ + { + "modelId": "f973e3c1-1148-43bb-bea8-49d0603ab3a8", + "status": "ready", + "createdDateTime": "2019-05-01T10:53:21+00:00", + "lastUpdatedDateTime": "2019-05-01T10:53:23+00:00" + }, + { + "modelId": "8dd53a98-bc73-43da-8533-60183824eb8e", + "status": "ready", + "createdDateTime": "2019-04-30T21:39:41+00:00", + "lastUpdatedDateTime": "2019-04-30T21:39:44+00:00" + } + ] } - ] } } } \ No newline at end of file diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json index b6d0511cc881..78f443b7d659 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json @@ -4,29 +4,47 @@ "Content-Type": "application/json", "Ocp-Apim-Subscription-Key": "{API key}", "body": { - "source": "/input/data" + "source": "/input/data" } }, "responses": { "200": { - "body": [ - { - "modelId": "640b1c8a-0a44-4611-94a6-f7d0130783cc", + "body":{ + "modelId": "ad1901b6-ddaa-4249-8938-3f03f65cc893", "trainingDocuments": [ { - "documentName": "docname.pdf", + "documentName": "0.pdf", "pages": 1, "errors": [], "status": "success" - } - ], - "errors": [ + }, + { + "documentName": "1.pdf", + "pages": 1, + "errors": [], + "status": "success" + }, + { + "documentName": "2.pdf", + "pages": 1, + "errors": [], + "status": "success" + }, + { + "documentName": "3.pdf", + "pages": 1, + "errors": [], + "status": "success" + }, { - "errorMessage": "Could not use 0.pdf for training." + "documentName": "4.pdf", + "pages": 1, + "errors": [], + "status": "success" } - ] + ], + "errors": [] } - ] } } } From 0f9441c753a9d85fe0b38ab6317c44bbe30b4ebf Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Wed, 1 May 2019 05:42:55 -0700 Subject: [PATCH 29/33] Fixing examples for model validation --- .../FormRecognizer/preview/v1.0/examples/Analyze.json | 4 ++-- .../preview/v1.0/examples/DeleteModel.json | 2 -- .../preview/v1.0/examples/GetModel.json | 11 +++++------ .../FormRecognizer/preview/v1.0/examples/Train.json | 2 ++ 4 files changed, 9 insertions(+), 10 deletions(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Analyze.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Analyze.json index 0846d50372cb..e7d6b8978479 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Analyze.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Analyze.json @@ -6,9 +6,9 @@ "id": "{Model Id}", "body": { "formData": { - "form_stream": "{Image or Pdf file stream}" } - } + }, + "form_stream": "{Image or Pdf file stream}" }, "responses": { "200": { diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/DeleteModel.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/DeleteModel.json index ba8131f4ee07..f157f9ac038b 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/DeleteModel.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/DeleteModel.json @@ -9,8 +9,6 @@ }, "responses": { "204": { - "body": { - } } } } diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModel.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModel.json index c1f30750f103..1e8abf15a011 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModel.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/GetModel.json @@ -9,13 +9,12 @@ }, "responses": { "200": { - "body":{ - "modelId": "cd7452ff-1988-4048-9e14-89bf6f4c15de", - "version": "1", + "body": { + "modelId": "f973e3c1-1148-43bb-bea8-49d0603ab3a8", "status": "ready", - "createdDateTime": "2019-04-18T12:47:15.3291661Z", - "lastUpdatedDateTime": "0001-01-01T00:00:00" - } + "createdDateTime": "2019-05-01T10:53:21+00:00", + "lastUpdatedDateTime": "2019-05-01T10:53:23+00:00" + } } } } \ No newline at end of file diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json index 78f443b7d659..0bbd8c65df62 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/examples/Train.json @@ -4,6 +4,8 @@ "Content-Type": "application/json", "Ocp-Apim-Subscription-Key": "{API key}", "body": { + }, + "trainRequest" : { "source": "/input/data" } }, From 6b2d1b2cb127de1bec827dc3b96c7adb347095f2 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Wed, 1 May 2019 12:06:51 -0700 Subject: [PATCH 30/33] Capturing feedback from API Review --- .../FormRecognizer/preview/v1.0/feedback.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/feedback.md diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/feedback.md b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/feedback.md new file mode 100644 index 000000000000..759e1ac26bf4 --- /dev/null +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/feedback.md @@ -0,0 +1,47 @@ +Form Recognizer: API Review Feedback + +PR Link: https://github.com/Azure/azure-rest-api-specs/pull/568 + +Feedback: +--------- +1. [shahabhijeet] Don't specify x-nullable: false. +2. [shahabhijeet] Use x-ms-enum for Status field (or other enums) +3. [shahabhijeet] Consider modeling error responses to something like: +{ + "error": { + "code": "", + "message": "", + "target": "", + "additionalInfo": [], + "details": [ + { + "code": "", + "target": "", + "message": "", + "additionalInfo": [ + { + "type": "PolicyViolation", + "info": { + "policySetDefinitionDisplayName": "Secure the environment", + "policySetDefinitionId":"/subscriptions/00000-00000-0000-000/providers/Microsoft.Authorization/policySetDefinitions/TestPolicySet", + "policyDefinitionDisplayName": "Allowed locations", + "policyDefinitionId":"/subscriptions/00000-00000-0000-000/providers/Microsoft.Authorization/policyDefinitions/TestPolicy1", + "policyAssignmentDisplayName": "Allow Central US and WEU only", + "policyAsssignmentId":"/subscriptions/00000-00000-0000-000/providers/Microsoft.Authorization/policyAssignments/TestAssignment1", + ... + ... + ... + } + } + ] + } + ] + } +} +Also: https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/common-api-details.md#error-response-content +(this is not the updated link, as I am trying to find the updated model, will post as soon as I find it, hence provided an actual example. +The format I am recommending allows you to have multiple error information objects as an array and "info" object is nothing but a generic JObject for dumping information like innerException. + +4. [johanste] /TrainCustomModel operation creates an addressable resource (keyed by the modelId in the response) +This should probably return a 201 with a Location header pointing to the result. + From 0c0e7b26a78f9cb05912ac32947eee6b6453bceb Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Wed, 1 May 2019 12:09:12 -0700 Subject: [PATCH 31/33] Capturing feedback from API review --- .../data-plane/FormRecognizer/preview/v1.0/feedback.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/feedback.md b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/feedback.md index 759e1ac26bf4..e34d3e792b1a 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/feedback.md +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/feedback.md @@ -1,6 +1,6 @@ Form Recognizer: API Review Feedback -PR Link: https://github.com/Azure/azure-rest-api-specs/pull/568 +PR Link: https://github.com/Azure/azure-rest-api-specs/pull/5684 Feedback: --------- From 96cb967612d9326cced9028a9943b5963d3c2bb1 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Thu, 2 May 2019 15:04:04 -0700 Subject: [PATCH 32/33] Fix generated code path, Fix generated SDK class name --- .../cognitiveservices/data-plane/FormRecognizer/readme.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md index 2b2e234f7b27..31031d049968 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/readme.md +++ b/specification/cognitiveservices/data-plane/FormRecognizer/readme.md @@ -46,7 +46,8 @@ csharp: license-header: MICROSOFT_MIT_NO_VERSION azure-arm: false namespace: Microsoft.Azure.CognitiveServices.FormRecognizer - output-folder: $(csharp-sdks-folder)/CognitiveServices/dataPlane/Vision/FormRecognizer/Generated + output-folder: $(csharp-sdks-folder)/CognitiveServices/dataPlane/Vision/FormRecognizer/FormRecognizer/Generated + title: "FormRecognizerClient" clear-output-folder: true ``` From af8009ba5c5f718bdf18e19407b076602dc82999 Mon Sep 17 00:00:00 2001 From: Sandeep Parab Date: Thu, 2 May 2019 17:19:01 -0700 Subject: [PATCH 33/33] Update title to be used for SDK code generation --- .../data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json index db9431589bd8..fffb70145ec3 100644 --- a/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json +++ b/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json @@ -2,7 +2,7 @@ "swagger": "2.0", "info": { "version": "v1.0-preview", - "title": "Cognitive Service Form Recognizer API V1 (Preview)", + "title": "Form Recognizer Client", "description": "Extracts information from forms and images into structured data based on a model created by a set of representative training forms." }, "securityDefinitions": {