From dc5aacd3e9cad6c3e3cc9efb47d0bb0038cd2824 Mon Sep 17 00:00:00 2001 From: sureshms Date: Mon, 9 Aug 2021 15:57:30 -0700 Subject: [PATCH] Update JSON schema documentation for cleanup and consistency. --- .../json/schema/api/teams/createTeam.json | 2 +- .../json/schema/entity/data/database.json | 2 +- .../json/schema/entity/data/table.json | 26 ++++++++++--------- .../entity/services/databaseService.json | 8 +++--- .../json/schema/entity/teams/team.json | 7 ++--- .../json/schema/entity/teams/user.json | 5 ++-- .../resources/json/schema/type/basic.json | 2 +- .../json/schema/type/entityReference.json | 2 +- .../json/schema/type/jdbcConnection.json | 2 ++ .../resources/json/schema/type/schedule.json | 2 +- 10 files changed, 33 insertions(+), 25 deletions(-) diff --git a/catalog-rest-service/src/main/resources/json/schema/api/teams/createTeam.json b/catalog-rest-service/src/main/resources/json/schema/api/teams/createTeam.json index 0e3fa4d91b1..54e81a8ad7d 100644 --- a/catalog-rest-service/src/main/resources/json/schema/api/teams/createTeam.json +++ b/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'", diff --git a/catalog-rest-service/src/main/resources/json/schema/entity/data/database.json b/catalog-rest-service/src/main/resources/json/schema/entity/data/database.json index 99ea6e3c007..6372dbaa369 100644 --- a/catalog-rest-service/src/main/resources/json/schema/entity/data/database.json +++ b/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": { diff --git a/catalog-rest-service/src/main/resources/json/schema/entity/data/table.json b/catalog-rest-service/src/main/resources/json/schema/entity/data/table.json index f6bef60a2a4..54eb7c6ddc0 100644 --- a/catalog-rest-service/src/main/resources/json/schema/entity/data/table.json +++ b/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" ] diff --git a/catalog-rest-service/src/main/resources/json/schema/entity/services/databaseService.json b/catalog-rest-service/src/main/resources/json/schema/entity/services/databaseService.json index 5a0fb616e75..3bccf416937 100644 --- a/catalog-rest-service/src/main/resources/json/schema/entity/services/databaseService.json +++ b/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": { diff --git a/catalog-rest-service/src/main/resources/json/schema/entity/teams/team.json b/catalog-rest-service/src/main/resources/json/schema/entity/teams/team.json index 92b746b879d..cee88b4c958 100644 --- a/catalog-rest-service/src/main/resources/json/schema/entity/teams/team.json +++ b/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" } }, diff --git a/catalog-rest-service/src/main/resources/json/schema/entity/teams/user.json b/catalog-rest-service/src/main/resources/json/schema/entity/teams/user.json index 3e92a5fcf0e..c958935964e 100644 --- a/catalog-rest-service/src/main/resources/json/schema/entity/teams/user.json +++ b/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" } }, diff --git a/catalog-rest-service/src/main/resources/json/schema/type/basic.json b/catalog-rest-service/src/main/resources/json/schema/type/basic.json index f5e7f2566a5..782be2b5cb0 100644 --- a/catalog-rest-service/src/main/resources/json/schema/type/basic.json +++ b/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+>$" }, diff --git a/catalog-rest-service/src/main/resources/json/schema/type/entityReference.json b/catalog-rest-service/src/main/resources/json/schema/type/entityReference.json index 5baf18187ca..530425d119e 100644 --- a/catalog-rest-service/src/main/resources/json/schema/type/entityReference.json +++ b/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": { diff --git a/catalog-rest-service/src/main/resources/json/schema/type/jdbcConnection.json b/catalog-rest-service/src/main/resources/json/schema/type/jdbcConnection.json index a7f9dc8cb92..b4e87a0fd1e 100644 --- a/catalog-rest-service/src/main/resources/json/schema/type/jdbcConnection.json +++ b/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": { diff --git a/catalog-rest-service/src/main/resources/json/schema/type/schedule.json b/catalog-rest-service/src/main/resources/json/schema/type/schedule.json index 3d1e1cd9979..f6969242606 100644 --- a/catalog-rest-service/src/main/resources/json/schema/type/schedule.json +++ b/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" } }