cadc_tap_schema11.yaml: Add descriptions of TAP_SCHEMA from tap-schem…

…a SQL

python/felis/schemas/cadc_tap_schema11.yaml

@@ -3,27 +3,29 @@
 # columns and tables added which are not currently used or filled by Felis.
 name: tap_schema
 version: "1.1"
-description: |
-    This schema defines the tables and columns that are used to describe the
-    TAP_SCHEMA of a TAP service. It is based on the IVOA TAP Recommendation
-    (http://www.ivoa.net/documents/TAP/20100327/index.html).
+description: A TAP-standard-mandated schema to describe tablesets in a TAP 1.1 service
 tables:
 - name: "schemas11"
+  description: description of schemas in this tableset
   primaryKey: "#schemas11.schema_name"
   mysql:engine: "InnoDB"
   columns:
     - name: "schema_name"
       datatype: "string"
+      description: schema name for reference to tap_schema.schemas
       length: 64
       nullable: false
     - name: "utype"
       datatype: "string"
+      description: lists the utypes of schemas in the tableset
       length: 512
     - name: "description"
       datatype: "string"
+      description: describes schemas in the tableset
       length: 512
     - name: "schema_index"
       datatype: "int"
+      description: recommended sort order when listing schemas
     # extension: permissions for user-created content
     - name: "owner_id"
       datatype: "string"
@@ -37,21 +39,26 @@ tables:
       datatype: "string"
       length: 128
 - name: "schemas"
+  description: description of schemas in this tableset
   primaryKey: "#schemas.schema_name"
   mysql:engine: "InnoDB"
   columns:
     - name: "schema_name"
       datatype: "string"
+      description: schema name for reference to tap_schema.schemas
       length: 64
       nullable: false
     - name: "utype"
       datatype: "string"
+      description: lists the utypes of schemas in the tableset
       length: 512
     - name: "description"
       datatype: "string"
+      description: describes schemas in the tableset
       length: 512
     - name: "schema_index"
       datatype: "int"
+      description: recommended sort order when listing schemas
     # extension: permissions for user-created content
     - name: "owner_id"
       datatype: "string"
@@ -65,29 +72,36 @@ tables:
       datatype: "string"
       length: 128
 - name: "tables11"
+  description: description of tables in this tableset
   primaryKey: "#tables11.table_name"
   mysql:engine: "InnoDB"
   columns:
   - name: schema_name
     datatype: string
+    description: the schema this table belongs to
     length: 64
     nullable: false
   - name: table_name
     datatype: string
+    description: the fully qualified table name
     length: 128
     nullable: false
   - name: table_type
     datatype: string
+    description: "one of: table view"
     length: 8
     nullable: false
   - name: utype
     datatype: string
+    description: lists the utype of tables in the tableset
     length: 512
   - name: description
     datatype: string
+    description: describes tables in the tableset
     length: 512
   - name: table_index
     datatype: int
+    description: recommended sort order when listing tables
   # extension: permissions for user-created content
   - name: owner_id
     datatype: string
@@ -101,34 +115,41 @@ tables:
     datatype: string
     length: 128
   constraints:
-    - name: "fk_tables_schemas11_schema_name"
+    - name: "fk_tables11_schemas11_schema_name"
       "@type": ForeignKey
       columns: ["#tables11.schema_name"]
       referencedColumns: ["#schemas11.schema_name"]
 - name: "tables"
+  description: description of tables in this tableset
   primaryKey: "#tables.table_name"
   mysql:engine: "InnoDB"
   columns:
   - name: schema_name
     datatype: string
+    description: the schema this table belongs to
     length: 64
     nullable: false
   - name: table_name
     datatype: string
+    description: the fully qualified table name
     length: 128
     nullable: false
   - name: table_type
     datatype: string
+    description: "one of: table view"
     length: 8
     nullable: false
   - name: utype
     datatype: string
+    description: lists the utype of tables in the tableset
     length: 512
   - name: description
     datatype: string
+    description: describes tables in the tableset
     length: 512
   - name: table_index
     datatype: int
+    description: recommended sort order when listing tables
   # extension: permissions for user-created content
   - name: owner_id
     datatype: string
@@ -147,49 +168,63 @@ tables:
       columns: ["#tables.schema_name"]
       referencedColumns: ["#schemas.schema_name"]
 - name: "columns11"
+  description: description of columns in this tableset
   primaryKey: ["#columns11.table_name", "#columns11.column_name"]
   mysql:engine: "InnoDB"
   columns:
   - name: table_name
     datatype: string
+    description: the table this column belongs to
     length: 128
     nullable: false
   - name: column_name
     datatype: string
+    description: the column name
     length: 64
     nullable: false
   - name: datatype
     datatype: string
+    description: lists the ADQL datatype of columns in the tableset
     length: 64
     nullable: false
   - name: arraysize
     datatype: string
+    description: lists the size of variable-length columns in the tableset
     length: 10
   - name: xtype
     datatype: string
+    description: a DALI or custom extended type annotation
     length: 64
   - name: size
     datatype: int
+    description: "deprecated: use arraysize"
   - name: description
     datatype: string
+    description: describes the columns in the tableset
     length: 512
   - name: utype
     datatype: string
+    description: lists the utypes of columns in the tableset
     length: 512
   - name: unit
     datatype: string
+    description: lists the unit used for column values in the tableset
     length: 64
   - name: ucd
     datatype: string
+    description: lists the UCDs of columns in the tableset
     length: 64
   - name: indexed
     datatype: int
+    description: an indexed column; 1 means 1, 0 means 0
     nullable: false
   - name: principal
     datatype: int
+    description: a principal column; 1 means 1, 0 means 0
     nullable: false
   - name: std
     datatype: int
+    description: a standard column; 1 means 1, 0 means 0
     nullable: false
   - name: column_index
     datatype: int
@@ -198,57 +233,72 @@ tables:
     datatype: string
     length: 32
   constraints:
-    - name: "fk_columns_tables11_table_name"
+    - name: "fk_columns11_tables11_table_name"
       "@type": ForeignKey
       columns: ["#columns11.table_name"]
       referencedColumns: ["#tables11.table_name"]
 - name: "columns"
+  description: description of columns in this tableset
   primaryKey: ["#columns.table_name", "#columns.column_name"]
   mysql:engine: "InnoDB"
   columns:
   - name: table_name
     datatype: string
+    description: the table this column belongs to
     length: 128
     nullable: false
   - name: column_name
     datatype: string
+    description: the column name
     length: 64
     nullable: false
   - name: datatype
     datatype: string
+    description: lists the ADQL datatype of columns in the tableset
     length: 64
     nullable: false
   - name: arraysize
     datatype: string
+    description: lists the size of variable-length columns in the tableset
     length: 10
   - name: xtype
     datatype: string
+    description: a DALI or custom extended type annotation
     length: 64
   - name: size
     datatype: int
+    description: "deprecated: use arraysize"
   - name: description
     datatype: string
+    description: describes the columns in the tableset
     length: 512
   - name: utype
     datatype: string
+    description: lists the utypes of columns in the tableset
     length: 512
   - name: unit
     datatype: string
+    description: lists the unit used for column values in the tableset
     length: 64
   - name: ucd
     datatype: string
+    description: lists the UCDs of columns in the tableset
     length: 64
   - name: indexed
     datatype: int
+    description: an indexed column; 1 means 1, 0 means 0
     nullable: false
   - name: principal
     datatype: int
+    description: a principal column; 1 means 1, 0 means 0
     nullable: false
   - name: std
     datatype: int
+    description: a standard column; 1 means 1, 0 means 0
     nullable: false
   - name: column_index
     datatype: int
+    description: recommended sort order when listing columns
   # extension: globally unique columnID for use as an XML ID attribute on the FIELD in VOTable output
   - name: id
     datatype: string
@@ -259,26 +309,32 @@ tables:
       columns: ["#columns.table_name"]
       referencedColumns: ["#tables.table_name"]
 - name: "keys11"
+  description: description of foreign keys in this tableset
   primaryKey: "#keys11.key_id"
   mysql:engine: "InnoDB"
   columns:
   - name: key_id
     datatype: string
+    description: unique key to join to tap_schema.key_columns
     length: 64
     nullable: false
   - name: from_table
     datatype: string
+    description: the table with the foreign key
     length: 128
     nullable: false
   - name: target_table
     datatype: string
+    description: the table with the primary key
     length: 128
     nullable: false
   - name: description
     datatype: string
+    description: describes keys in the tableset
     length: 512
   - name: utype
     datatype: string
+    description: lists the utype of keys in the tableset
     length: 512
   # extension: permissions for user-created content
   - name: owner_id
@@ -293,7 +349,7 @@ tables:
     datatype: string
     length: 128
   constraints:
-    - name: "fk_keys_tables11_from_table"
+    - name: "fk_keys11_tables11_from_table"
       "@type": ForeignKey
       columns: ["#keys11.from_table"]
       referencedColumns: ["#tables11.table_name"]
@@ -302,26 +358,32 @@ tables:
       columns: ["#keys11.target_table"]
       referencedColumns: ["#tables11.table_name"]
 - name: "keys"
+  description: description of foreign keys in this tableset
   primaryKey: "#keys.key_id"
   mysql:engine: "InnoDB"
   columns:
   - name: key_id
     datatype: string
+    description: unique key to join to tap_schema.key_columns
     length: 64
     nullable: false
   - name: from_table
     datatype: string
+    description: the table with the foreign key
     length: 128
     nullable: false
   - name: target_table
     datatype: string
+    description: the table with the primary key
     length: 128
     nullable: false
   - name: description
     datatype: string
+    description: describes keys in the tableset
     length: 512
   - name: utype
     datatype: string
+    description: lists the utype of keys in the tableset
     length: 512
   # extension: permissions for user-created content
   - name: owner_id
@@ -345,6 +407,7 @@ tables:
       columns: ["#keys.target_table"]
       referencedColumns: ["#tables.table_name"]
 - name: "key_columns11"
+  description: description of foreign key columns in this tableset
   mysql:engine: "InnoDB"
   columns:
   - name: key_id
@@ -360,11 +423,12 @@ tables:
     length: 64
     nullable: false
   constraints:
-    - name: "fk_key_columns11_keys_key_id"
+    - name: "fk_key11_columns11_keys_key_id"
       "@type": ForeignKey
       columns: ["#key_columns11.key_id"]
       referencedColumns: ["#keys11.key_id"]
 - name: "key_columns"
+  description: description of foreign key columns in this tableset
   mysql:engine: "InnoDB"
   columns:
   - name: key_id