deriva-annotation-config

Using deriva-annotation-config to configure annotations

The deriva-annotation-config utility reads a configuration file and uses it to set annotationss for an ermrest catalog (or for a schema or table within that catalog). Usage is:

deriva-annotation-config [-n|--dryrun] [-v|--verbose] [-s|--schema schema] [-t|--table table] [--host host] [--config-file config_file] [--credential-file credential_file] catalog

where the required arguments are:

catalog: an ermrest catalog number (e.g., 1)

--config_file file: the name of a configuration file

Options are:

-credential_file file: read credentials from the named file (if not specified, look for credentials maintained by deriva-auth)

--dryrun: do nothing, just print out the catalog schema that would be applied

--verbose: verbose, print acls and acl bindings for each object

--schema schema: operate only on the named schema, not the whole catalog

--table table: operate only on the named table, not the whole catalog (requires the --schema option)

--host host: configure the server on the specified host (default localhost)

Config file format

The config file is a JSON file divided into the following stanzas:

known_attributes: Attributes (i.e., annotation URIs, such as tag:isrd.isi.edu,2016:display) managed through this config file

schema_annotations: Catalog-level annotations.

schema_annotations: Annotations for individual schemas.

table_annotations: Annotations for individual tables.

column_annotations: Annotations for individual columns.

foreign_key_annotations: Annotations for foreign keys.

The `known_attributes` stanza

This stanza contains parameters that control the behavior of deriva-annotation-config itself. This section has three sub-sections: managed, ignored, and ignore_all_unmanaged.

The managed section is a list of annotation types managed by deriva-annotation-config.

The ignore_all_unmanaged section is a boolean: if true, deriva-annotation-config will leave any annotations not in the managed list unchanged. If false, deriva-annotation-config will clear any annotations not in the managed list.

The ignored section is a list of annotation types that are recognized by deriva-annotation-config but that aren’t created or updated by it, depending on the value of ignore_all_unmanaged. If ignore_all_unmanaged is true, the program leaves existing annotations of this type alone. If ignore_all_unmanaged is false, the program removes existing annotation sof this type.

Example:

    "known_attributes": {
        "ignore_all_unmanaged": false,
        "managed": [
            "tag:isrd.isi.edu,2016:column-display", 
            "tag:isrd.isi.edu,2016:display", 
            "tag:isrd.isi.edu,2016:foreign-key", 
            ...
	],
	"ignored" : [
            "comment", 
            "description", 
            "facetOrder"
	]
    }

This is a version one might use to remove all comment, description, and facetOrder annotations from a catalog. If ignore_all_attributes were true, those annotations would be left unchanged.

The schema_annotations stanza

This is where annotations for schemas are set. The syntax is a list of entries of the form:

{schema_descriptor: value, annotation_descriptor: value}

A schema_descriptor is either:

"schema": schema_name

or

"schema_pattern:" regular_expression

When setting permissions on a schema:

if an exact schema match is found, the associated ACL is used (and any matching schema_pattern entries are ignored).
If no exact schema match is found and exactly one matching schema_pattern entry is found, then that ACL is used.
If no exact schema match is found and more than one matching schema_pattern entry is found, then an error is thrown.

An annotation_descriptor has the form:

"uri": annotation_uri "value":: annotation_value

For example:

        {
            "schema": "Vocabulary", 
            "uri": "tag:misd.isi.edu,2015:display", 
            "value": {
                "name_style": {
                    "title_case": true, 
                    "underline_space": true
                }
            }
        }

The table_annotations stanza

This is where annotationss for tables are set. The syntax is a list of entries of the form: {schema_descriptor, table_descriptor, annotation_desciptor} The schema_descriptor and annotation_descriptor have the same form as above.

A table_descriptor is either:

"table": table_name

or

"table_pattern:" regular_expression

Regular expression matching is used:

If an entry with an exact schema and table match is found, the associated ACL is used (and any other matching entries are ignored).
Otherwise, if entry with an exact schema match and exactly one table_pattern match is found, that ACL is used.
Otherwise, if exactly one entry with a schema_pattern and table_pattern match is found, that ACL is used.
If none of the above is true, and multiple matching entries are found, then an error is thrown.

For example:

    "table_annotations": [
        {
            "schema": "Vocabulary", 
            "table_pattern": ".*_terms", 
            "uri": "tag:isrd.isi.edu,2016:table-display", 
            "value": {
                "row_name": {
                    "row_markdown_pattern": "{{name}}"
                }
            }
        }

This sets an annotation for any table in the “Vocabulary” schema whose table name ends in “_terms”.

The column_annotations stanza

This is where ACLs for columns are set. The syntax is a list of entries of the form: {schema_descriptor, table_descriptor, column_descriptor, annotation_descriptor} The schema, table, and annotation descriptors have the same form as above. The column_descriptor is either:

"column": table_name

or

"column_pattern:" regular_expression

Regular expression matching is used:

If an entry with exact schema, table, and column matches is found, the associated ACL is used (and any other matching entries are ignored).
Otherwise, if exactly one entry is found with schema, table, and column matches is found, that ACL is used
If multiple regular-expression matches are found and no exact match is found, an exception is thrown.

Example:

        {
            "column": "RCT", 
            "schema_pattern": ".*", 
            "table_pattern": ".*", 
            "uri": "tag:misd.isi.edu,2015:display", 
            "value": {
                "name": "Creation Time"
            }
        }

This sets the display name for any column named “RCT” in the catalog.

The foreign_key_annotations stanza

This is where annotations for foreign keys are set. The syntax is a list of entries of the form:

{schema_descriptor, table_descriptor, fkey_schema_descriptor, fkey_name_descriptor, annotation_descriptor}

The schema, table, and annotation descriptors have the same form as above. The fkey_schema_descriptor is either:

"foreign_key_schema": foreign_key_schema_name

or

"foreign_key_schema_pattern": regular_expression

The fkey_name_descriptor is either:

"foreign_key": foreign_key_name

or

"foreign_key_pattern": regular_expression

These specify the foreign key schema and name. As with the column_acls stanza:

If an exact match is found, it’s used
If no exact match is found and exactly one regular expression match is found, it’s used.
If no exact match is found and more than one regular expression match is found, an error is thrown.

Example:

        {
            "foreign_key": "Antibody_Gene_Association_NCBI_GeneID_fkey", 
            "foreign_key_schema": "", 
            "schema": "Antibody", 
            "table": "Antibody_Gene_Association", 
            "uri": "tag:isrd.isi.edu,2016:foreign-key", 
            "value": {
                "to_name": "Related Genes"
            }
        }

deriva-annotation-config

Using deriva-annotation-config to configure annotations

Config file format

The known_attributes stanza

The schema_annotations stanza

The table_annotations stanza

The column_annotations stanza

The foreign_key_annotations stanza

The `known_attributes` stanza