Update dataset v2 descriptions and examples.

specification/maps/data-plane/Microsoft.Maps/Dataset/preview/2.0/dataset.json

@@ -118,7 +118,7 @@
     },
     "ConversionIdQuery": {
       "name": "conversionId",
-      "description": "The unique ID used to create the dataset. The `conversionId` must have been obtained from a successful call to the Conversion Service Convert API and must be provided with multiple query parameters with same name (if more than one is provided).",
+      "description": "The unique ID used to create the dataset. The `conversionId` must have been obtained from a successful call to the Conversion Service Convert API and may be provided with multiple query parameters with same name (if more than one is provided).",
       "type": "string",
       "in": "query",
       "required": true,
@@ -144,7 +144,7 @@
       "name": "datasetId",
       "type": "string",
       "in": "query",
-      "description": "The ID for the dataset to append to. ** the dataset must originate from a conversion ontology that matches conversionId",
+      "description": "The ID for the dataset to append with. The dataset must originate from a conversion ontology that matches conversionId",
       "required": false,
       "x-ms-parameter-location": "method"
     },
@@ -161,7 +161,7 @@
     "/datasets": {
       "post": {
         "x-publish": true,
-        "description": "**Dataset Create API**\n\n**Applies to:** S1 pricing tier.\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API \nand SDK. The Dataset APIs are part of Creator. This API allows the caller to create a dataset from data that \nwas uploaded to the Azure Maps Data Service.\n\nYou can use this API in a scenario like uploading a DWG zip package for a building, converting the zip package using \nthe Azure Maps Conversion Service, creating a dataset from the converted zip package. The created dataset can be \nused to create tilesets using the Azure Maps Tileset Service and can be queried via the Azure Maps WFS Service.\n\n## Submit Create Request\n\nTo create your dataset, you will use a `POST` request where the `conversionId` query parameter is an id that represents \nthe converted DWG zip package, the `type` parameter will describe the data type to use for the dataset, the `datasetId`\nparameter will describe if the provided data should be appended to a current dataset and, optionally, the \n`description` query parameter will contain a description (if description is not provided a default description will be \ngiven).\n\nThe Create API is a \n[long-running request](https://aka.ms/am-creator-lrt).",
+        "description": "## Dataset Create API\n\n### Applies to: S1 pricing tier.\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. The Dataset APIs are part of Creator. This API allows the caller to create a dataset from data that was uploaded to the Azure Maps Data Service and converted using the Azure Maps Conversion Service.\n\nYou can use this API in a scenario like uploading a DWG zip package for a building, converting the zip package using the Azure Maps Conversion Service, and creating a dataset from the converted zip package. The created dataset can be used to create tilesets using the Azure Maps Tileset Service and can be queried via the Azure Maps WFS Service.\n\n### Submit Create Request\n\nTo create your dataset, you will use a `POST` request where the `conversionId` query parameter is an ID that represents the converted DWG zip package, the `datasetId` parameter will be the ID of a previously created dataset to append with the current dataset and, optionally, the `description` query parameter will contain a description (if description is not provided a default description will be given).\n\nThe Create API is a [long-running request](https://aka.ms/am-creator-lrt).",
         "operationId": "Dataset_CreatePreview",
         "x-ms-long-running-operation": true,
         "x-ms-long-running-operation-options": {
@@ -212,7 +212,7 @@
       },
       "get": {
         "x-publish": true,
-        "description": "**Dataset List API**\n\n**Applies to:** S1 pricing tier.\n<br>\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. The Dataset APIs are part of Creator.\nThis API allows the caller to fetch a list of all previously successfully created datasets.\n\n\n### Submit List Request\n\nTo list all your datasets, you will issue a `GET` request with no additional parameters.<br>\n\n\n### List Data Response\n\nThe List API returns the complete list of all datasets in `json` format. The response contains the following fields (if they are not null or empty):\n  > created - The timestamp the dataset was created.\n  > datasetId - The id for the dataset.\n  > description - The description for the dataset.\n  > datasetSources - The source data that was used when the create request was issued.\n\nThe `datasetSources` describes the source data that was used when the create request was issued and contains the following elements (if they are not null or empty):\n  > conversionIds - The list of `conversionId` (null if none were provided).\n  > udids - The list of `udid` (null if none were provided).\n  > appendDatasetId - The `datasetId` that was used for an append operation (null if none was used).\n  > type - The type of data stored in the dataset that was created.\n\nHere's a sample response returning the `timestamp`, `datasetId`, `description`, and `datasetSources` of 3 dataset resources:\n\n<br>\n\n```json\n{\n  \"datasets\": [\n    {\n      \"timestamp\": \"2020-01-01T22:50:48+00:00\",\n      \"datasetId\": \"f6495f62-94f8-0ec2-c252-45626f82fcb2\",\n      \"description\": \"Some description or comment for the dataset.\",\n      \"datasetSources\": {\n        \"conversionIds\": [\n          \"15d21452-c9bb-27b6-5e79-743ca5c3205d\"\n        ],\n        \"type\": \"facility\"\n      },\n      \"status\": \"Succeeded\"\n    },\n    {\n      \"timestamp\": \"2020-01-01T22:57:53+00:00\",\n      \"datasetId\": \"8b1288fa-1958-4a2b-b68e-13a7i5af7d7c\",\n      \"description\": \"Create from upload '0c1288fa-2058-4a1b-b68d-13a5f5af7d7c'.\",\n      \"datasetSources\": {\n        \"udids\": [\n          \"0c1288fa-2058-4a1b-b68d-13a5f5af7d7c\"\n        ],\n        \"type\": \"facility\"\n      },\n      \"status\": \"Succeeded\"\n    },\n    {\n      \"timestamp\": \"2020-01-01T20:39:36+00:00\",\n      \"datasetId\": \"7c1288fa-2058-4a1b-b68f-13a6h5af7d7c\",\n      \"description\": \"Some other description or comment for the dataset.\",\n      \"datasetSources\": {\n        \"conversionIds\": [\n          \"15d21452-c9bb-27b6-5e79-743ca5c3205d\"\n        ],\n        \"appendDatasetId\": \"8b1288fa-1958-4a2b-b68e-13a7i5af7d7c\",\n        \"type\": \"facility\"\n      },\n      \"status\": \"Succeeded\"\n    }\n  ]\n}\n```\n<br>",
+        "description": "## Dataset List API\n\n### Applies to: S1 pricing tier.\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. The Dataset APIs are part of Creator.\n\nThis API allows the caller to fetch a list of all previously successfully created datasets.\n\n### Submit List Request\n\nTo list all your datasets, you will issue a `GET` request with no additional parameters.\n\n\n### List Data Response\n\nThe List API returns the complete list of all datasets in `json` format. The response contains the following fields (if they are not null or empty):\n> created - The timestamp the dataset was created.\n> datasetId - The id for the dataset.\n> description - The description for the dataset.\n> datasetSources - The source data that was used when the create request was issued.\n> ontology - The source ontology that was used in the conversion service for the input data.<br/>\n\nThe `datasetSources` describes the source data that was used when the create request was issued and contains the following elements (if they are not null or empty):\n\n> conversionIds - The list of `conversionId` (null if none were provided).\n> appendDatasetId - The `datasetId` that was used for an append operation (null if none was used).\n>featureCounts - The counts for each feature type in the dataset.<br/>\n\nHere's a sample response returning the `timestamp`, `datasetId`, `description`, `datasetSources`, and `ontology` of 3 dataset resources:\n\n\n```json\n{\n  \"datasets\": [\n    {\n      \"timestamp\": \"2020-01-01T22:50:48.123Z\",\n      \"datasetId\": \"f6495f62-94f8-0ec2-c252-45626f82fcb2\",\n      \"description\": \"Some description or comment for the dataset.\",\n      \"datasetSources\": {\n        \"conversionIds\": [\n          \"15d21452-c9bb-27b6-5e79-743ca5c3205d\"\n        ],      },\n      \"ontology\": \"facility-2.0\",\n      \"featureCounts\": {\n        \"directoryInfo\": 2,\n        \"category\": 10,\n        \"facility\": 1,\n        \"level\": 3,\n        \"unit\": 183,\n        \"zone\": 3,\n        \"verticalPenetration\": 6,\n        \"opening\": 48,\n        \"areaElement\": 108\n      }\n    },\n    {\n      \"timestamp\": \"2020-01-01T22:57:53.123Z\",\n      \"datasetId\": \"8b1288fa-1958-4a2b-b68e-13a7i5af7d7c\",\n      \"description\": \"Create from upload '0c1288fa-2058-4a1b-b68d-13a5f5af7d7c'.\",\n      \"datasetSources\": {\n        \"conversionIds\": [\n          \"0c1288fa-2058-4a1b-b68d-13a5f5af7d7c\"\n        ],\n        \"appendDatasetId\": \"46d1edb6-d29e-4786-9589-dbd4efd7a977\"\n      },\n      \"ontology\": \"facility-2.0\",\n      \"featureCounts\": {\n        \"directoryInfo\": 2,\n        \"category\": 10,\n        \"facility\": 1,\n        \"level\": 3,\n        \"unit\": 183,\n        \"zone\": 3,\n        \"verticalPenetration\": 6,\n        \"opening\": 48,\n        \"areaElement\": 108\n      }\n    }\n  ]\n}\n```",
         "operationId": "Dataset_ListPreview",
         "x-ms-examples": {
           "List all the previously created datasets": {
@@ -255,8 +255,13 @@
     "/datasets/{datasetId}": {
       "get": {
         "x-publish": true,
-        "description": "**Dataset Get API**\n\n**Applies to:** S1 pricing tier.\n<br>\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. The Dataset APIs are part of Creator.\nThis API allows the caller to fetch a previously successfully created dataset.\n",
+        "description": "## Dataset Get Details API\n\n### Applies to: S1 pricing tier.\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. The Dataset APIs are part of Creator.\n\nThis API allows the caller to fetch a previously successfully created dataset.\n\n### Submit Get Details Request\n\nTo get the details for a previously created dataset, you will issue a `GET` request with the `datasetId` in the path.\n\n### Get Details Response\n\nThe Get Details API returns the details for a dataset in `json` format. The response contains the following fields (if they are not null or empty):\n> created - The timestamp the dataset was created.\n> datasetId - The id for the dataset.\n> description - The description for the dataset.\n> datasetSources - The source data that was used when the create request was issued.\n> ontology - The source ontology that was used in the conversion service for the input data.<br/>\n\nThe `datasetSources` describes the source data that was used when the create request was issued and contains the following elements (if they are not null or empty):\n> conversionIds - The list of `conversionId` (null if none were provided).\n> appendDatasetId - The `datasetId` that was used for an append operation (null if none was used).\n>featureCounts - The counts for each feature type in the dataset.<br/>\n\nHere's a sample response returning the `timestamp`, `datasetId`, `description`, `datasetSources`, and `ontology` of a dataset resource:\n\n```json\n{\n   \"timestamp\": \"2020-01-01T22:50:48.123Z\",\n   \"datasetId\": \"f6495f62-94f8-0ec2-c252-45626f82fcb2\",\n   \"description\": \"Some description or comment for the dataset.\",\n   \"datasetSources\": {\n     \"conversionIds\": [\n       \"15d21452-c9bb-27b6-5e79-743ca5c3205d\"\n     ],\n   },\n   \"ontology\": \"facility-2.0\",\n   \"featureCounts\": {\n     \"directoryInfo\": 2,\n     \"category\": 10,\n     \"facility\": 1,\n     \"level\": 3,\n     \"unit\": 183,\n     \"zone\": 3,\n     \"verticalPenetration\": 6,\n     \"opening\": 48,\n     \"areaElement\": 108\n   }\n }\n```",
         "operationId": "Dataset_GetPreview",
+        "x-ms-examples": {
+          "Get details for a previously created dataset": {
+            "$ref": "./examples/Dataset_GetDetails.json"
+          }
+        },
         "parameters": [
           {
             "$ref": "#/parameters/DatasetId"
@@ -294,7 +299,7 @@
       },
       "delete": {
         "x-publish": true,
-        "description": "**Dataset Delete API**\n\n**Applies to:** S1 pricing tier.\n<br>\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. The Dataset APIs are part of Creator.\nThis API allows the caller to delete a previously created dataset.<br>    \nYou can also use this API to delete old/unused datasets to create space for new Creator content.\n\n\n### Submit Delete Request\n\nTo delete your content you will issue a `DELETE` request where the path will contain the `datasetId` of the dataset to delete.<br> \n\n\n### Delete Data Response\n\nThe Delete API returns a HTTP `204 No Content` response if the dataset resource was deleted successfully.<br>",
+        "description": "## Dataset Delete API\n\n### Applies to:S1 pricing tier.\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. The Dataset APIs are part of Creator. This API allows the caller to delete a previously created dataset.\n\nYou can also use this API to delete old/unused datasets to create space for new Creator content.\n\n### Submit Delete Request\n\nTo delete your content you will issue a `DELETE` request where the path will contain the `datasetId` of the dataset to delete.",
         "operationId": "Dataset_DeletePreview",
         "x-ms-examples": {
           "Delete previously created dataset": {
@@ -336,7 +341,7 @@
     },
     "/datasets/operations/{operationId}": {
       "get": {
-        "description": "This path will be obtained from a call to /datasets/create.  While in progress, an http200 will be returned with no extra headers -  followed by an http200 with Resource-Location header once successfully completed.",
+        "description": "## Dataset Operations API\n\n### Applies to: S1 pricing tier\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. The Dataset APIs are part of Creator. This API allows the caller to view the current progress of a dataset operation and the path is obtained from a call to the Create API.\n\n### Submit Operations Request\n\nTo view the current progress of a dataset operation, you will use a `GET` request where the `operationId` given the path is the ID that represents the operation.\n\n### Operation Response\n\nWhile in progress, a `200-OK` http status code will be returned with no extra headers. If the operation succeeds, a `200-OK` http status code with Resource-Location header will be returned.",
         "parameters": [
           {
             "$ref": "#/parameters/SubscriptionKey"

specification/maps/data-plane/Microsoft.Maps/Dataset/preview/2.0/examples/Dataset_Create.json

@@ -2,26 +2,13 @@
   "parameters": {
     "api-version": "2.0",
     "subscription-key": "[subscription-key]",
-    "conversionId": "[conversionId]",
-    "type": "facility"
+    "conversionId": "[conversionId]"
   },
   "responses": {
-    "201": {
-      "headers": {
-        "Location": "https://atlas.microsoft.com/dataset/{datasetId}?api-version=1.0",
-        "Access-Control-Expose-Headers": "Location"
-      },
-      "body": {
-        "operationId": "{operationId}",
-        "status": "Succeeded",
-        "created": "2020-01-02 1:02:03 AM +00:00",
-        "resourceLocation": "https://atlas.microsoft.com/dataset/{datasetId}?api-version=1.0"
-      }
-    },
     "202": {
       "headers": {
-        "Location": "https://atlas.microsoft.com/dataset/operations/{operationId}?api-version=1.0",
-        "Access-Control-Expose-Headers": "Location"
+        "Operation-Location": "https://atlas.microsoft.com/dataset/operations/{operationId}?api-version=1.0",
+        "Access-Control-Expose-Headers": "Operation-Location"
       }
     },
     "400": {

specification/maps/data-plane/Microsoft.Maps/Dataset/preview/2.0/examples/Dataset_GetDetails.json

@@ -0,0 +1,85 @@
+{
+    "parameters": {
+      "api-version": "2.0",
+      "subscription-key": "[subscription-key]",
+      "datasetId": "[datasetId]"
+    },
+    "responses": {
+      "201": {
+        "headers": {
+          "Location": "https://atlas.microsoft.com/dataset/{datasetId}?api-version=1.0",
+          "Access-Control-Expose-Headers": "Resource-Location"
+        },
+        "body": {
+          "created": "2021-05-21T01:02:03.456Z",
+          "datasetId": "{datasetId}",
+          "description": "Some description or comment about the dataset",
+          "datasetSources": {
+              "conversionIds": [
+                  "{conversionId1}",
+                  "{conversionId2}"
+              ],
+              "appendDatasetId": "{appendDatasetId}"
+          },
+          "featureCounts": {
+              "directoryInfo": 2,
+              "category": 10,
+              "facility": 1,
+              "level": 3,
+              "unit": 183,
+              "zone": 3,
+              "verticalPenetration": 6,
+              "opening": 48,
+              "areaElement": 108
+          },
+          "ontology": "facility-2.0"
+        }
+      },
+      "400": {
+        "headers": {},
+        "body": {
+          "error": {
+            "code": "400 BadRequest",
+            "message": "Bad request - Error message."
+          }
+        }
+      },
+      "401": {
+        "headers": {},
+        "body": {
+          "error": {
+            "code": "401 Unauthorized",
+            "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
+          }
+        }
+      },
+      "403": {
+        "headers": {},
+        "body": {
+          "error": {
+            "code": "403 Forbidden",
+            "message": "Permission, capacity, or authentication issues."
+          }
+        }
+      },
+      "404": {
+        "headers": {},
+        "body": {
+          "error": {
+            "code": "404 NotFound",
+            "message": "Not Found - The requested resource could not be found, but it may be available again in the future."
+          }
+        }
+      },
+      "500": {
+        "headers": {},
+        "body": {
+          "error": {
+            "code": "500 InternalServerError",
+            "message": "Unknown error - An error occurred while processing the request. Please try again later."
+          }
+        }
+      }
+    }
+  }
+