Update JSON schema documentation for cleanup and consistency.

catalog-rest-service/src/main/resources/json/schema/api/teams/createTeam.json

@@ -7,7 +7,7 @@
 
   "properties" : {
     "name": {
-      "$ref": "../../entity/teams/team.json#/defintions/teamName"
+      "$ref": "../../entity/teams/team.json#/definitions/teamName"
     },
     "displayName": {
       "description": "Optional name used for display purposes. Example 'Marketing Team'",

catalog-rest-service/src/main/resources/json/schema/entity/data/database.json

@@ -28,7 +28,7 @@
       "type": "string"
     },
     "description": {
-      "description": "Description of the database instance. What it has and how to use it.",
+      "description": "Description of the database instance.",
       "type": "string"
     },
     "href": {

catalog-rest-service/src/main/resources/json/schema/entity/data/table.json

@@ -8,7 +8,7 @@
   "definitions": {
     "tableType": {
       "javaType": "org.openmetadata.catalog.type.TableType",
-      "description": "Type for capturing a column in a table.",
+      "description": "This schema defines the type for a column in a table.",
       "type": "string",
       "enum": [
         "Regular",
@@ -37,7 +37,7 @@
     },
     "columnDataType": {
       "javaType": "org.openmetadata.catalog.type.ColumnDataType",
-      "description": "Type for capturing a column in a table.",
+      "description": "This enum defines the type for column data type.",
       "type": "string",
       "enum": [
         "NUMBER",
@@ -77,7 +77,7 @@
     },
     "columnConstraint": {
       "javaType": "org.openmetadata.catalog.type.ColumnConstraint",
-      "description": "Column constraint.",
+      "description": "This enum defines the type for column constraint.",
       "type": "string",
       "enum": [
         "NULL",
@@ -90,7 +90,7 @@
     "tableConstraint": {
       "type": "object",
       "javaType": "org.openmetadata.catalog.type.TableConstraint",
-      "description": "Table constraint.",
+      "description": "This enum defines the type for table constraint.",
       "properties": {
         "constraintType": {
           "type": "string",
@@ -124,7 +124,7 @@
       "pattern": "^[^.]*$"
     },
     "fullyQualifiedColumnName": {
-      "description": "Fully qualified name of the column that includes serviceName.databaseName.tableName.columnName.",
+      "description": "Fully qualified name of the column that includes `serviceName.databaseName.tableName.columnName`.",
       "type": "string",
       "minLength": 1,
       "maxLength": 256
@@ -132,7 +132,7 @@
     "column": {
       "type": "object",
       "javaType": "org.openmetadata.catalog.type.Column",
-      "description": "Type for capturing a column in a table.",
+      "description": "This schema defines the type for a column in a table.",
       "properties": {
         "name": {
           "$ref": "#/definitions/columnName"
@@ -173,7 +173,7 @@
     "columnJoins": {
       "type": "object",
       "javaType": "org.openmetadata.catalog.type.ColumnJoin",
-      "description": "Information on other tables that this table column is frequently joined with.",
+      "description": "This schema defines the type to capture how frequently a column in this table is joined with columns in the other tables.",
       "properties": {
         "columnName": {
           "$ref": "#/definitions/columnName"
@@ -199,6 +199,7 @@
     "tableJoins": {
       "type": "object",
       "javaType": "org.openmetadata.catalog.type.TableJoins",
+      "description": "This schema defines the type to capture how columns in this table is joined with columns in the other tables.",
       "properties": {
         "startDate": {
           "description": "Date can be only from today going back to last 29 days.",
@@ -220,7 +221,7 @@
     "tableData": {
       "type": "object",
       "javaType": "org.openmetadata.catalog.type.TableData",
-      "description": "Information on other tables that this table column is frequently joined with.",
+      "description": "This schema defines the type to capture rows of sample data for the table.",
       "properties": {
         "columns": {
           "description": "List of local column names (not fully qualified column names) of the table.",
@@ -243,7 +244,7 @@
   },
   "properties": {
     "id": {
-      "description": "Unique identifier that identifies this table instance.",
+      "description": "Unique identifier of this table instance.",
       "$ref": "../../type/basic.json#/definitions/uuid"
     },
     "name": {
@@ -262,11 +263,11 @@
       "$ref": "#/definitions/tableType"
     },
     "fullyQualifiedName": {
-      "description": "Fully qualified name of the table in the form serviceName.databaseName.tableName.",
+      "description": "Fully qualified name of the table in the form `serviceName.databaseName.tableName`.",
       "type": "string"
     },
     "columns": {
-      "description": "Columns in the table.",
+      "description": "Columns in this table.",
       "type": "array",
       "items": {
         "$ref": "#/definitions/column"
@@ -282,8 +283,8 @@
       "default": null
     },
     "usageSummary": {
-      "$ref": "../../type/usageDetails.json",
       "description": "Latest usage information for this table.",
+      "$ref": "../../type/usageDetails.json",
       "default": null
     },
     "owner": {
@@ -319,6 +320,7 @@
     }
   },
   "required": [
+    "id",
     "name",
     "columns"
   ]

catalog-rest-service/src/main/resources/json/schema/entity/services/databaseService.json

@@ -44,16 +44,17 @@
   },
   "properties": {
     "id": {
-      "description": "Unique identifier that identifies an entity instance.",
+      "description": "Unique identifier of this database service instance.",
       "$ref": "../../type/basic.json#/definitions/uuid"
     },
     "name": {
-      "description": "Name that identifies the this entity instance uniquely. Same as id if when name is not unique.",
+      "description": "Name that identifies this database service.",
       "type": "string",
       "minLength": 1,
       "maxLength": 64
     },
     "serviceType": {
+      "description": "Type of database service such as MySQL, BigQuery, Snowflake, Redshift, Postgres...",
       "$ref": "#/definitions/databaseServiceType"
     },
     "description": {
@@ -61,10 +62,11 @@
       "type": "string"
     },
     "href": {
-      "description": "Link to the resource corresponding to this entity.",
+      "description": "Link to the resource corresponding to this database service.",
       "$ref": "../../type/basic.json#/definitions/href"
     },
     "jdbc": {
+      "description": "JDBC connection information",
       "$ref": "../../type/jdbcConnection.json#/definitions/jdbcInfo"
     },
     "ingestionSchedule": {

catalog-rest-service/src/main/resources/json/schema/entity/teams/team.json

@@ -5,7 +5,7 @@
   "description": "This schema defines Team entity. A Team is a group of zero or more users. Team can have ownership of data assets.",
   "type": "object",
 
-  "defintions" : {
+  "definitions" : {
     "teamName" : {
       "description": "Unique name of the team typically the team ID from the identify provider. Example - group Id from ldap.",
       "type": "string",
@@ -19,7 +19,7 @@
       "$ref": "../../type/basic.json#/definitions/uuid"
     },
     "name": {
-      "$ref": "#/defintions/teamName"
+      "$ref": "#/definitions/teamName"
     },
     "displayName": {
       "description": "Name used for display purposes. Example 'Data Science team'.",
@@ -38,6 +38,7 @@
       "$ref": "../../type/profile.json"
     },
     "deleted" : {
+      "description": "When true the team has been deleted.",
       "type": "boolean"
     },
     "users" : {
@@ -45,7 +46,7 @@
       "$ref": "../../type/entityReference.json#/definitions/entityReferenceList"
     },
     "owns" : {
-      "description": "Entities owned by the team.",
+      "description": "List of entities owned by the team.",
       "$ref": "../../type/entityReference.json#/definitions/entityReferenceList"
     }
   },

catalog-rest-service/src/main/resources/json/schema/entity/teams/user.json

@@ -54,6 +54,7 @@
       "boolean" : false
     },
     "profile": {
+      "description": "Profile of the user.",
       "$ref": "../../type/profile.json"
     },
     "teams" : {
@@ -61,11 +62,11 @@
       "$ref": "../../type/entityReference.json#/definitions/entityReferenceList"
     },
     "owns" : {
-      "description": "Entities owned by the user.",
+      "description": "List of entities owned by the user.",
       "$ref": "../../type/entityReference.json#/definitions/entityReferenceList"
     },
     "follows" : {
-      "description": "Entities followed by the user.",
+      "description": "List of entities followed by the user.",
       "$ref": "../../type/entityReference.json#/definitions/entityReferenceList"
     }
   },

catalog-rest-service/src/main/resources/json/schema/type/basic.json

@@ -18,7 +18,7 @@
       "maxLength": 127
     },
     "entityLink": {
-      "description": "Link to an entity or field of an entity of format <#E/{enties}/{entityName}/{field}/{fieldValue}.",
+      "description": "Link to an entity or field of an entity of format `<#E/{enties}/{entityName}/{field}/{fieldValue}`.",
       "type": "string",
       "pattern": "^<#E/\\S+/\\S+>$"
     },

catalog-rest-service/src/main/resources/json/schema/type/entityReference.json

@@ -20,7 +20,7 @@
       "$ref": "basic.json#/definitions/uuid"
     },
     "type": {
-      "description": "Entity type/class name - Examples: database, table, metrics, redshift, mysql, bigquery, snowflake...",
+      "description": "Entity type/class name - Examples: `database`, `table`, `metrics`, `redshift`, `mysql`, `bigquery`, `snowflake`...",
       "type": "string"
     },
     "name": {

catalog-rest-service/src/main/resources/json/schema/type/jdbcConnection.json

@@ -39,9 +39,11 @@
   "description":"JDBC connection information",
   "properties": {
     "driverClass": {
+      "description": "JDBC driver class",
       "$ref" : "#/definitions/driverClass"
     },
     "connectionUrl": {
+      "description": "JDBC connection URL",
       "$ref" : "#/definitions/connectionUrl"
     },
     "userName": {

catalog-rest-service/src/main/resources/json/schema/type/schedule.json

@@ -11,7 +11,7 @@
       "$ref": "basic.json#/definitions/dateTime"
     },
     "repeatFrequency": {
-      "description": "Repeat frequency in ISO 8601 duration format.",
+      "description": "Repeat frequency in ISO 8601 duration format. Example - 'P23DT23H'",
       "$ref": "basic.json#/definitions/duration"
     }
   }